Index: apps/dtplite ================================================================== --- apps/dtplite +++ apps/dtplite @@ -11,1521 +11,19 @@ # Meta description markup language. It covers the most # Meta description common use cases, but is not as # Meta description configurable as its big brother dtp. # Meta category Processing doctools documents # Meta subject doctools doctoc docidx -# Meta require {doctools 1} -# Meta require {doctools::idx 1} -# Meta require {doctools::toc 1} -# Meta require fileutil -# Meta require textutil::repeat +# Meta require {dtplite 1.0.4} # Meta author Andreas Kupries # Meta license BSD # @@ Meta End -package provide dtplite 1.0.4 +package require 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. - -# 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 -package require doctools::idx 1.0.4 ; -package require doctools::toc 1.1.3 ; -package require fileutil -package require textutil::repeat - -# ### ### ### ######### ######### ######### -## Internal data and status - -namespace eval ::dtplite { - - # Path to where the output goes to. This is a file in case of mode - # 'file', irrelevant for mode 'file.stdout', and the directory for - # all the generated files for the two directory modes. Specified - # through the mandatory option '-o'. - - variable output "" - - # Path to where the documents to convert come from. This is a - # single file in the case of the two file modes, and a directory - # for the directory modes. In the later case all files under that - # directory are significant, including links, if identifiable as - # in doctools format (fileutil::fileType). Specified through the - # last argument on the command line. The relative path of a file - # under 'input' also becomes its relative path under 'output'. - - variable input "" - - # The extension to use for the generated files. Ignored by the - # file modes, as for them they either don't generate a file, or - # know its full name already, i.e. including any wanted - # extension. Set via option '-ext'. Defaults to the format name if - # '-ext' was not used. - - variable ext "" - - # Optional. HTML specific, requires engine parameter 'meta'. Path - # to a stylesheet file to use in the output. The file modes link - # to it using the original location, but the directory modes copy - # the file into the 'output' and link it there (to make the - # 'output' more selfcontained). Initially set via option '-style'. - - variable style "" - - # Optional. Path to a file. Contents of the file are assigned to - # engine parameter 'header', if present. If navigation buttons - # were defined their HTML will be appended to the file contents - # before doing the assignment. A specification is ignored if the - # engine does not support the parameter 'header'. Set via option - # '-header'. - - variable header "" - - # Like header, but for the document footer, and no navigation bar - # insert. Set via option '-footer', requires engine parameter - # 'footer'. - - variable footer "" - - # List of buttons/links for a navigation bar. No navigation bar is - # created if this is empty. HTML specific, requires engine - # parameter 'header' (The navigation bar is merged with the - # 'header' data, see above). Each element of the list is a - # 2-element list, containing the button label and url, in this - # order. Initial data comes from the command line, via option - # '-nav'. The commands 'Navbutton(Push|Pop)' then allow the - # programmatic addition and removal of buttons at the left (stack - # like, top at index 0). This is used for the insertion of links - # to TOC and Index into each document, if applicable. - - variable nav {} - - # An array caching the result of merging header and navbar data, - # keyed by the navbar definition (list). This allows us to quickly - # access the complete header for a navbar, without having to - # generate it over and over again. Its usefulness is a bit limited - # by the fact that the navbar itself can be generated on a - # file-by-file basis (required to get the relative links - # correct. It helps only if the generated navbars are identical to - # each other. - - variable navcache - array set navcache {} - - # The name of the format to convert the doctools documents - # into. Set via the next-to-last argument on the command - # line. Used as extension for the generated files as well by the - # directory modes, and if not overridden via '-ext'. See 'ext' - # above. - - variable format "" - - # Boolean flag. Set by the option '-merge'. Ignored when a file - # mode is detected, but for a directory it determines the - # difference between the two directory modes, i.e. plain - # generation, or incremental merging of many inputs into one - # output. - - variable merge 0 - - # Boolean flag. Automatically set by code distinguishing between - # file and directory modes. Set for a the file modes, unset for - # the directory modes. - - variable single 1 - - # Boolean flag. Automatically set by the code processing the '-o' - # option. Set if output is '-', unset otherwise. Ignored for the - # directory modes. Distinguished between the two file modes, i.e. - # writing to a file (unset), or stdout (set). - - variable stdout 0 - - # Name of the found processing mode. Derived from the values of - # the three boolean flags (merge, single, stdout). This value is - # used during the dispatch to the command implementing the mode, - # after processing the command line. - # - # Possible/Legal values: Meaning - # --------------------- ------- - # File File mode. Write result to a file. - # File.Stdout File mode. Write result to stdout. - # Directory Directory mode. Plain processing of one set. - # Directory.Merge Directory mode. Merging of multiple sets into - # one output. - # --------------------- ------- - - variable mode "" - - # Name of the module currently processed. Derived from the 'input' - # (last element of this path, without extension). - - variable module "" - - # Crossreference data. Extracted from the processed documents, a - # rearrangement and filtration of the full meta data (See 'meta' - # below). Relevant only to the directory modes. I.e. the file - # modes don't bother with its extraction and use. - - variable xref - array set xref {} - - # Index data. Mapping from keyword (label) to the name of its - # anchor in the index output. Requires support for the engine - # parameter 'kwid' in the index engine. - - variable kwid - array set kwid {} - - # Cache. This array maps from the path of an input file/document - # (relative to 'input'), to the paths of the file to generate - # (relative to 'output', including extension and such). In other - # words we derive the output paths from the inputs only once and - # then simply get them here. - - variable out - array set out {} - - # Meta data cache. Stores the meta data extracted from the input - # files/documents, per input. The meta data is a dictionary and - # processed several ways to get: Crossreferences (See 'xref' - # above), Table Of Contents, and Keyword Index. The last two are - # not cached, but ephemeral. - - variable meta - array set meta {} - - # Cache of input documents. When we read an input file we store - # its contents here, keyed by path (relative to 'input') so that - # we don't have to go to the disk when we we need the file again. - # The directory modes need each input twice, for metadata - # extraction, and the actual conversion. - - variable data - array set data {} - - # Database of image files for use by dt_imap. - - variable imap - array set imap {} - - # Database of exclusion patterns. Files matching these are not - # 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 -# -## Only the directory merge mode uses external data, saving the -## internal representations of current toc, index. and xref -## information for use by future mergers. It uses three files, -## described below. The files are created if they don't exist. -## Remove them when the merging is complete. -# -## .toc -## Contains the current full toc in form of a dictionary. -# Keys are division labels, values the lists of toc items. -# -## .idx -## Contains the current full index, plus keyword id map. Is a list of -# three elements, index, start id for new kwid entries, and the -# keyword id map (kwid). Index and Kwid are both dictionaries, keyed -# by keywords. Index value is a list of 2-tuples containing symbolic -# file plus label, in this order. Kwid value is the id of the anchor -# for that keyword in the index. -# -## .xrf -## Contains the current cross reference database, a dictionary. Keys -# are tags the formatter can search for (keywords, keywrds with -# prefixes, keywords with suffixces), values a list containing either -# the file to refer to to, or both file and an anchor in that -# file. The latter is for references into the index. - -# ### ### ### ######### ######### ######### -## Option processing. -## Validate command line. -## Full command line syntax. -## -# dtplite -o outputpath \ -# ?-merge? \ -# ?-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 utoc - - # Process the options, perform basic validation. - - while {[llength $argv]} { - set opt [lindex $argv 0] - if {![string match "-*" $opt]} break - - if {[string equal $opt "-o"]} { - if {[llength $argv] < 2} Usage - set output [lindex $argv 1] - set argv [lrange $argv 2 end] - } elseif {[string equal $opt "-merge"]} { - 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] - } elseif {[string equal $opt "-style"]} { - if {[llength $argv] < 2} Usage - set style [lindex $argv 1] - set argv [lrange $argv 2 end] - } elseif {[string equal $opt "-header"]} { - if {[llength $argv] < 2} Usage - set header [lindex $argv 1] - set argv [lrange $argv 2 end] - } elseif {[string equal $opt "-footer"]} { - if {[llength $argv] < 2} Usage - set footer [lindex $argv 1] - set argv [lrange $argv 2 end] - } elseif {[string equal $opt "-nav"]} { - if {[llength $argv] < 3} Usage - lappend nav [lrange $argv 1 2] - set argv [lrange $argv 3 end] - } else { - Usage - } - } - - # Additional validation, and extraction of the non-option - # arguments. - - if {[llength $argv] != 2} Usage - - set format [lindex $argv 0] - set input [lindex $argv 1] - - if {[string equal $format validate]} { - set format null - } - - # Final validation across the whole configuration. - - if {[string equal $format ""]} { - ArgError "Illegal empty format specification" - - } else { - # Early check: Is the chosen format ok ? For this we have - # create and configure a doctools object. - - doctools::new dt - if {[catch {dt configure -format $format}]} { - ArgError "Unknown format \"$format\"" - } - dt configure -deprecated 1 - - # Check style, header, and footer options, if present. - - CheckInsert header {Header file} - CheckInsert footer {Footer file} - - if {[llength $nav] && ![in [dt parameters] header]} { - ArgError "-nav not supported by format \"$format\"" - } - if {![string equal $style ""]} { - if {![in [dt parameters] meta]} { - ArgError "-style not supported by format \"$format\"" - } elseif {![file exists $style]} { - ArgError "Unable to find style file \"$style\"" - } - } - } - - # Set up an extension based on the format, if no extension was - # specified. also compute the name of the module, based on the - # input. [SF Tcllib Bug 1111364]. Has to come before the line - # marked with a [*], or a filename without extension is created. - - if {[string equal $ext ""]} { - set ext $format - } - - CheckInput $input {Input path} - if {[file isfile $input]} { - # Input file. Merge mode is not possible. Output can be file - # or directory, or "-" for stdout. The output may exist, but - # does not have to. The directory it is in however does have - # to exist, and has to be writable (if the output does not - # exist yet). An existing output has to be writable. - - if {$merge} { - ArgError "-merge illegal when processing a single input file." - } - if {![string equal $output "-"]} { - CheckTheOutput - - # If the output is an existing directory then we have to - # ensure that the actual output is a file in that - # directory, and we derive its name from the name of the - # input file (and -ext, if present). - - if {[file isdirectory $output]} { - # [*] [SF Tcllib Bug 1111364] - set output [file join $output [file tail [Output $input]]] - } - } else { - set stdout 1 - } - } else { - # Input directory. Merge mode is possible. Output has to be a - # directory. The output may exist, but does not have to. The - # directory it is in however does have to exist. An existing - # output has to be writable. - - set single 0 - CheckTheOutput 1 - } - - # Determine the operation mode from the flags - - if {$single} { - if {$stdout} { - set mode File.Stdout - } else { - set mode File - } - } elseif {$merge} { - set mode Directory.Merge - } else { - set mode Directory - } - - set module [file rootname [file tail [file normalize $input]]] - return -} - -# ### ### ### ######### ######### ######### -## Option processing. -## Helpers: Generation of error messages. -## I. General usage/help message. -## II. Specific messages. -# -# Both write their messages to stderr and then -# exit the application with status 1. -## - -proc ::dtplite::Usage {} { - global argv0 - puts stderr "$argv0 wrong#args, expected:\ - -o outputpath ?-merge? ?-ext ext?\ - ?-style file? ?-header file?\ - ?-footer file? ?-nav label url?...\ - format inputpath" - exit 1 -} - -proc ::dtplite::ArgError {text} { - global argv0 - puts stderr "$argv0: $text" - exit 1 -} - -proc in {list item} { - expr {([lsearch -exact $list $item] >= 0)} -} - -# ### ### ### ######### ######### ######### -## Helper commands. File paths. -## Conversion of relative paths -## to absolute ones for input -## and output. Derivation of -## output file name from input. - -proc ::dtplite::Pick {f} { - variable input - return [file join $input $f] -} - -proc ::dtplite::Output {f} { - variable ext - return [file rootname $f].$ext -} - -proc ::dtplite::At {f} { - variable output - set of [file normalize [file join $output $f]] - file mkdir [file dirname $of] - return $of -} - -# ### ### ### ######### ######### ######### -## Check existence and permissions of an input/output file or -## directory. - -proc ::dtplite::CheckInput {f label} { - if {![file exists $f]} { - ArgError "Unable to find $label \"$f\"" - } elseif {![file readable $f]} { - ArgError "$label \"$f\" not readable (permission denied)" - } - return -} - -proc ::dtplite::CheckTheOutput {{needdir 0}} { - variable output - variable format - - if {[string equal $format null]} { - # The format does not generate output, so not specifying an - # output file is ok for that case. - return - } - - if {[string equal $output ""]} { - ArgError "No output path specified" - } - - set base [file dirname $output] - if {[string equal $base ""]} {set base [pwd]} - - if {![file exists $output]} { - if {![file exists $base]} { - ArgError "Output base path \"$base\" not found" - } - if {![file writable $base]} { - ArgError "Output base path \"$base\" not writable (permission denied)" - } - } else { - if {![file writable $output]} { - ArgError "Output path \"$output\" not writable (permission denied)" - } - if {$needdir && ![file isdirectory $output]} { - ArgError "Output path \"$output\" not a directory" - } - } - return -} - -proc ::dtplite::CheckInsert {option label} { - variable format - variable $option - upvar 0 $option opt - - if {![string equal $opt ""]} { - if {![in [dt parameters] $option]} { - ArgError "-$option not supported by format \"$format\"" - } - CheckInput $opt $label - set opt [Get $opt] - } - return -} - -# ### ### ### ######### ######### ######### -## Helper commands. File reading and writing. - -proc ::dtplite::Get {f} { - variable data - if {[info exists data($f)]} {return $data($f)} - return [set data($f) [fileutil::cat $f]] -} - -proc ::dtplite::Write {f data} { - # An empty filename is acceptable, the format will be 'null' - if {[string equal $f ""]} return - fileutil::writeFile $f $data - return -} - -# ### ### ### ######### ######### ######### -## Dump accumulated warnings. - -proc ::dtplite::Warnings {} { - set warnings [dt warnings] - if {[llength $warnings] > 0} { - puts stderr [join $warnings \n] - } - return -} - -# ### ### ### ######### ######### ######### -## Configuation phase, validate command line. - -::dtplite::processCmdline - -# ### ### ### ######### ######### ######### -## We can assume that we have from here on a command 'dt', which is a -## doctools object command, and already configured for the format to -## generate. -# ### ### ### ######### ######### ######### - -# ### ### ### ######### ######### ######### -## Commands implementing the main functionality. - -proc ::dtplite::Do.File {} { - # Process a single input file, write the result to a single outut file. - - variable input - variable output - - SinglePrep - Write $output [dt format [Get $input]] - Warnings - return -} - -proc ::dtplite::Do.File.Stdout {} { - # Process a single input file, write the result to stdout. - - variable input - - SinglePrep - puts stdout [dt format [Get $input]] - close stdout - Warnings - return -} - -proc ::dtplite::Do.Directory {} { - # Process a directory of input files, through all subdirectories. - # Generate index and toc, but no merging with an existing index - # and toc. I.e. any existing index and toc files are overwritten. - - 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 - # ........ in merge op. - # Phase II. Build index and toc information from the meta data. - # Phase III. Convert each file, using index, toc and meta - # .......... information. - - MapImages - set files [LocateManpages $input] - if {![llength $files]} { - ArgError "Module \"$module\" has no files to process." - } - - MetadataGet $files - StyleMakeLocal - - 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 - FooterSetup dt - MapSetup dt - - foreach f [lsort -dict $files] { - puts stdout \t$f - - set o $out($f) - dt configure -file [At $o] -ibase $input/$f - - NavbuttonPush {Keyword Index} [Output index] $o - NavbuttonPush {Table Of Contents} [Output toc] $o - HeaderSetup dt - NavbuttonPop - NavbuttonPop - StyleSetup dt $o - - if {[string equal $format null]} { - dt format [Get [Pick $f]] - } else { - Write [At $o] [dt format [Get [Pick $f]]] - } - Warnings - } - return -} - -proc ::dtplite::Do.Directory.Merge {} { - # See Do.Directory, but merge the TOC/Index information from this - # set of input files into an existing TOC/Index. - - variable input - 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 - # ........ in merge op. - # Phase II. Build module local toc from the meta data, insert it - # ......... into the main toc as well, and generate a global - # ......... index. - # Phase III. Process each file, using cross references, and links - # .......... to boths tocs and the index. - - MapImages - set files [LocateManpages $input] - if {![llength $files]} { - 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] - 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 - MapSetup dt - - foreach f [lsort -dict $files] { - puts stdout \t$f - - set o $out($f) - 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 - NavbuttonPop - NavbuttonPop - NavbuttonPop - StyleSetup dt $o - - if {[string equal $format null]} { - dt format [Get [Pick $f]] - } else { - Write [At $o] [dt format [Get [Pick $f]]] - } - Warnings - } - return -} - -# ### ### ### ######### ######### ######### -## Helper commands. Preparations shared between the two file modes. - -proc ::dtplite::SinglePrep {} { - variable input - variable module - - MapImages - StyleSetup dt - HeaderSetup dt - FooterSetup dt - MapSetup dt - - dt configure -module $module -file $input - return -} - -# ### ### ### ######### ######### ######### -## Get the base meta data out of the listed documents. - -proc ::dtplite::MetadataGet {files {floc {}}} { - # meta :: map (symbolicfile -> metadata) - # metadata = dict (key -> value) - # key = set { desc, fid, file, keywords, - # module, section, see_also, - # shortdesc, title, version } - # desc :: string 'document title' - # fid :: string 'file name, without path/extension' - # file :: string 'file name, without path' - # keywords :: list (string...) 'key phrases' - # module :: string 'module the file is in' - # section :: string 'manpage section' - # see_also :: list (string...) 'related files' - # shortdesc :: string 'module description' - # title :: string 'manpage file name intended' - # version :: string 'file/package version' - variable meta - variable input - variable out - - doctools::new meta -format list -deprecated 1 - foreach f $files { - meta configure -file $input/$f - set o [Output [file join $floc files $f]] - set out($f) $o - set meta($o) [lindex [string trim [meta format [Get [Pick $f]]]] 1] - } - meta destroy - return -} - -# ### ### ### ######### ######### ######### -## Handling Tables of Contents: -## - Get them out of the base meta data. -## - As above, and merging them with global toc. -## - Conversion of internals into doctoc. -## - Processing doctoc into final formatting. - -proc ::dtplite::TocGet {desc {f toc}} { - # Generate the intermediate form of a TOC for the current document - # set. This generates a single division. - - # Get toc out of the meta data. - variable meta - set res {} - foreach {k item} [array get meta] { - lappend res [TocItem $k $item] - } - return [list $desc [list $f $res]] -} - -proc ::dtplite::TocMap {toc {base {}}} { - if {$base == {}} { - set base [lindex [lindex $toc 1] 0] - } - set items [lindex [lindex $toc 1] 1] - - set res {} - foreach i $items { - foreach {f label desc} $i break - lappend res $f [fileutil::relativeUrl $base $f] - } - return $res -} - -proc ::dtplite::TocItem {f meta} { - array set md $meta - set desc $md(desc) - set label $md(title) - return [list $f $label $desc] -} - -proc ::dtplite::TocMergeSaved {sub} { - # sub is the TOC of the current doc set (local toc). Merge this - # into the main toc (as read from the saved global state), and - # return the resulting internal rep for further processing. - - set fqn [At .toc] - if {[file exists $fqn]} { - array set _ [Get $fqn] - } - array set _ $sub - set thetoc [array get _] - - # Save extended toc for next merge. - Write $fqn $thetoc - - return $thetoc -} - -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 (index 1). - # Write as doctoc. - - array set toc $data - - TagsBegin - if {[array size toc] < 2} { - # Empty, or single division. The division is the TOC, toplevel. - - unset toc - 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 1 $data] { - foreach {symfile label desc} $item break - Tag+ item \ - [FmtR mxf $symfile] \ - [FmtR mxl $label] \ - [list $desc] - } - } else { - Tag+ toc_begin [list {Table Of Contents} Modules] - 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 1 $div] { - foreach {symfile label desc} $item break - Tag+ item \ - [FmtR mxf $symfile] \ - [FmtR mxl $label] \ - [list $desc] - } - Tag+ division_end - } - } - - Tag+ toc_end - - #puts ____________________\n[join $lines \n]\n_________________________ - return [join $lines \n]\n -} - -proc ::dtplite::TocWrite {ftoc findex text {map {}}} { - variable format - - if {[string equal $format null]} return - Write [At .tocdoc] $text - - set ft [Output $ftoc] - - doctools::toc::new toc -format $format -file $ft - - NavbuttonPush {Keyword Index} [Output $findex] $ftoc - HeaderSetup toc - NavbuttonPop - FooterSetup toc - StyleSetup toc $ftoc - - foreach {k v} $map {toc map $k $v} - - Write [At $ft] [toc format $text] - toc destroy - return -} - -proc ::dtplite::TocAlign {fv lv div} { - upvar 1 $fv mxf $lv mxl - set mxf 0 - set mxl 0 - foreach item $div { - foreach {symfile label desc} $item break - Max mxf $symfile - Max mxl $label - } - return -} - -# ### ### ### ######### ######### ######### -## Handling Keyword Indices: -## - Get them out of the base meta data. -## - As above, and merging them with global index. -## - Conversion of internals into docidx. -## - Processing docidx into final formatting. - -proc ::dtplite::IdxGet {{f index}} { - # Get index out of the meta data. - array set keys {} - array set kdup {} - return [lindex [IdxExtractMeta] 1] -} - -proc ::dtplite::IdxGetSaved {{f index}} { - # Get index out of the meta data, merge into global state. - variable meta - variable kwid - - array set keys {} - array set kwid {} - array set kdup {} - set start 0 - - set fqn [At .idx] - if {[file exists $fqn]} { - foreach {kw kd start ki} [Get $fqn] break - array set keys $kw - array set kwid $ki - array set kdup $kd - } - - foreach {start theindex} [IdxExtractMeta $start] break - - # Save extended index for next merge. - Write $fqn [list $theindex [array get kdup] $start [array get kwid]] - - return $theindex -} - -proc ::dtplite::IdxExtractMeta {{start 0}} { - # Get index out of the meta data. - variable meta - variable kwid - - upvar keys keys kdup kdup - foreach {k item} [array get meta] { - foreach {symfile keywords label} [IdxItem $k $item] break - # Store inverted file - keyword relationship - # Kdup is used to prevent entering of duplicates. - # Checks full (keyword file label). - foreach k $keywords { - set kx [list $k $symfile $label] - if {![info exists kdup($kx)]} { - lappend keys($k) [list $symfile $label] - set kdup($kx) . - } - if {[info exist kwid($k)]} continue - set kwid($k) key$start - incr start - } - } - return [list $start [array get keys]] -} - -proc ::dtplite::IdxItem {f meta} { - array set md $meta - set keywords $md(keywords) - set title $md(title) - return [list $f $keywords $title] -} - -proc ::dtplite::IdxGenerate {desc data} { - # Sort by keyword label. - # Write as docidx. - - array set keys $data - - TagsBegin - Tag+ index_begin [list {Keyword Index} $desc] - - foreach k [lsort -dict [array names keys]] { - IdxAlign mxf $keys($k) - - Tag+ key [list $k] - foreach v [lsort -dict -index 1 $keys($k)] { - foreach {file label} $v break - Tag+ manpage [FmtR mxf $file] [list $label] - } - } - - Tag+ index_end - #puts ____________________\n[join $lines \n]\n_________________________ - return [join $lines \n]\n -} - -proc ::dtplite::IdxWrite {findex ftoc text} { - variable format - - if {[string equal $format null]} return - Write [At .idxdoc] $text - - set fi [Output $findex] - - doctools::idx::new idx -format $format -file $fi - - NavbuttonPush {Table Of Contents} [Output $ftoc] $findex - HeaderSetup idx - NavbuttonPop - FooterSetup idx - StyleSetup idx $findex - XrefSetupKwid idx - - Write [At $fi] [idx format $text] - idx destroy - return -} - -proc ::dtplite::IdxAlign {v keys} { - upvar 1 $v mxf - set mxf 0 - foreach item $keys { - foreach {symfile label} $item break - Max mxf $symfile - } - return -} - -# ### ### ### ######### ######### ######### -## Column sizing - -proc ::dtplite::Max {v str} { - upvar 1 $v max - set l [string length [list $str]] - if {$max < $l} {set max $l} - return -} - -proc ::dtplite::FmtR {v str} { - upvar 1 $v max - return [list $str][textutil::repeat::blank \ - [expr {$max - [string length [list $str]]}]] -} - -# ### ### ### ######### ######### ######### -## Code generation. - -proc ::dtplite::Tag {n args} { - if {[llength $args]} { - return "\[$n [join $args]\]" - } else { - return "\[$n\]" - } - #return \[[linsert $args 0 $n]\] -} - -proc ::dtplite::Tag+ {n args} { - upvar 1 lines lines - lappend lines [eval [linsert $args 0 ::dtplite::Tag $n]] - return -} - -proc ::dtplite::TagsBegin {} { - upvar 1 lines lines - set lines {} - return -} - -# ### ### ### ######### ######### ######### -## Collect all files for possible use as image - -proc ::dtplite::MapImages {} { - variable input - variable output - variable single - variable stdout - - # Ignore images when writing results to a pipe. - if {$stdout} return - - set out [file normalize $output] - set path [file normalize $input] - set res {} - - if {$single} { - # output is file, image directory is sibling to it. - set imgbase [file join [file dirname $output] image] - # input to search is director the input file is in, and below - set path [file dirname $path] - } else { - # output is directory, image directory is inside. - set imgbase [file join $out image] - } - - set n [llength [file split $path]] - - foreach f [::fileutil::find $path] { - MapImage \ - [::fileutil::stripN $f $n] \ - $f [file join $imgbase [file tail $f]] - } - return -} - -proc ::dtplite::MapImage {path orig dest} { - # A file a/b/x.y is stored under - # a/b/x.y, b/x.y, and x.y - - variable imap - set plist [file split $path] - while {[llength $plist]} { - set imap([join $plist /]) [list $orig $dest] - set plist [lrange $plist 1 end] - } - return -} - -proc ::dtplite::MapSetup {dt} { - # imap :: map (symbolicfile -> list (originpath,destpath))) - variable imap - # Skip if no data available - - #puts MIS|[array size imap]| - if {![array size imap]} return - - foreach sf [array names imap] { - foreach {origin destination} $imap($sf) break - $dt img $sf $origin $destination - } - return -} - -# ### ### ### ######### ######### ######### -## Find the documents to process. - -proc ::dtplite::LocateManpages {path} { - set path [file normalize $path] - set n [llength [file split $path]] - set res {} - foreach f [::fileutil::find $path ::dtplite::IsDoctools] { - lappend res [::fileutil::stripN $f $n] - } - return $res -} - -proc ::dtplite::IsDoctools {f} { - set res [expr {[in [::fileutil::fileType $f] doctools] && ![Excluded [file normalize $f]]}] - #puts ...$f\t$res\t|[fileutil::fileType $f]|\texcluded=[Excluded [file normalize $f]]\tin.[pwd] - return $res -} - -proc ::dtplite::Excluded {f} { - variable excl - foreach p $excl { - if {[string match $p $f]} {return 1} - } - return 0 -} - -# ### ### ### ######### ######### ######### -## Handling a style sheet -## - Decoupling output from input location. -## - Generate HTML to insert into a generated document. - -proc ::dtplite::StyleMakeLocal {{pfx {}}} { - variable style - if {[string equal $style ""]} return - set base [file join $pfx [file tail $style]] - - # TODO input == output does what here ? - - file copy -force $style [At $base] - set style $base - return -} - -proc ::dtplite::StyleSetup {o {f {}}} { - variable style - if {[string equal $style ""]} return - if {![in [$o parameters] meta]} return - - if {![string equal $f ""]} { - set dst [fileutil::relativeUrl $f $style] - } else { - set dst $style - } - set value "" - - $o setparam meta $value - return -} - -# ### ### ### ######### ######### ######### -## Handling the cross references -## - Getting them out of the base meta data. -## - ditto, plus merging with saved xref information. -## - Insertion into processor, cached list. -## - Setting up the keyword-2-anchor map. - -proc ::dtplite::XrefGet {} { - variable meta - variable xref - variable kwid - - array set keys {} - foreach {symfile item} [array get meta] { - array set md $item - # Cross-references ... File based, see-also - - set t $md(title) - set ts ${t}($md(section)) - set td $md(desc) - - set xref(sa,$t) [set _ [list $symfile]] - set xref(sa,$ts) $_ - set xref($t) $_ ; # index on manpage file name - set xref($ts) $_ ; # ditto, with section added - set xref($td) $_ ; # index on document title - - # Store an inverted file - keyword relationship, for the index - foreach kw $md(keywords) { - lappend keys($kw) $symfile - } - } - - set if [Output index] - foreach k [array names keys] { - if {[info exists xref(kw,$k)]} continue - - set frag $kwid($k) - set xref(kw,$k) [set _ [list $if $frag]] - set xref($k) $_ - } - return -} - -proc ::dtplite::XrefGetSaved {} { - # xref :: map (xrefid -> list (symbolicfile)) - variable xref - array set xref {} - - # Load old cross references, from a previous run - set fqn [At .xrf] - if {[file exists $fqn]} { - array set xref [set s [Get $fqn]] - } - - # Add any new cross references ... - XrefGet - Write $fqn [array get xref] - return -} - -proc ::dtplite::XrefSetup {o} { - # xref :: map (xrefid -> list (symbolicfile)) - variable xref - # Skip if no data available - if {![array size xref]} return - # Skip if backend doesn't support an index - if {![in [$o parameters] xref]} return - - # Transfer index data to the backend. The data we keep has to be - # re-formatted from a dict into a list of tuples with leading - # xrefid. - - # xrefl :: list (list (xrefid symbolicfile...)...) - variable xrefl - if {![info exist xrefl]} { - set xrefl {} - foreach k [array names xref] { - lappend xrefl [linsert $xref($k) 0 $k] - set f [lindex $xref($k) 0] - dt map $f [At $f] - } - } - $o setparam xref $xrefl - return -} - -proc ::dtplite::XrefSetupKwid {o} { - # kwid :: map (label -> anchorname) - variable kwid - # Skip if no data available - if {![array size kwid]} return - # Skip if backend doesn't support an index - if {![in [$o parameters] kwid]} return - # Transfer index data to the backend - $o setparam kwid [array get kwid] - return -} - -# ### ### ### ######### ######### ######### -## Extending and shrinking the navigation bar. - -proc ::dtplite::NavbuttonPush {label file ref} { - # nav = list (list (label reference) ...) - variable nav - set nav [linsert $nav 0 [list $label [fileutil::relativeUrl $ref $file]]] - return -} - -proc ::dtplite::NavbuttonPop {} { - # nav = list (list (label reference) ...) - variable nav - set nav [lrange $nav 1 end] - return -} - -# ### ### ### ######### ######### ######### -## Header/Footer mgmt -## Header is merged from regular header, plus nav bar. -## Caching the merge result for quicker future access. - -proc ::dtplite::HeaderSetup {o} { - variable header - variable nav - variable navcache - - if {[string equal $header ""] && ![llength $nav]} return - if {![in [$o parameters] header]} return - - if {![info exists navcache($nav)]} { - set sep 0 - set hdr "" - if {![string equal $header ""]} { - append hdr $header - set sep 1 - } - if {[llength $nav]} { - if {$sep} {append hdr
\n} - append hdr
\ \[\n - - set first 1 - foreach item $nav { - if {!$first} {append hdr "| "} else {append hdr " "} - set first 0 - foreach {label url} $item break - append hdr "" $label "\n" - } - append hdr \]\
\n - } - set navcache($nav) $hdr - } else { - set hdr $navcache($nav) - } - - $o setparam header $hdr - return -} - -proc ::dtplite::FooterSetup {o} { - variable footer - if {[string equal $footer ""]} return - if {![in [$o parameters] footer]} return - $o setparam footer $footer - return -} - -# ### ### ### ######### ######### ######### -## Invoking the functionality. - -if {[catch { - set mode $::dtplite::mode - ::dtplite::Do.$mode -} msg]} { - ## puts $::errorInfo - ::dtplite::ArgError $msg -} + +exit [dtplite::do $argv] # ### ### ### ######### ######### ######### exit Index: embedded/man/files/apps/dtplite.n ================================================================== --- embedded/man/files/apps/dtplite.n +++ embedded/man/files/apps/dtplite.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -484,50 +483,41 @@ 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 - +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 - +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 - +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. @@ -559,7 +549,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2004 Andreas Kupries - .fi Index: embedded/man/files/apps/nns.n ================================================================== --- embedded/man/files/apps/nns.n +++ embedded/man/files/apps/nns.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -352,7 +351,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2007-2008 Andreas Kupries - .fi Index: embedded/man/files/apps/nnsd.n ================================================================== --- embedded/man/files/apps/nnsd.n +++ embedded/man/files/apps/nnsd.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -310,7 +309,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2007-2008 Andreas Kupries - .fi Index: embedded/man/files/apps/nnslog.n ================================================================== --- embedded/man/files/apps/nnslog.n +++ embedded/man/files/apps/nnslog.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -313,7 +312,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2008 Andreas Kupries - .fi Index: embedded/man/files/apps/page.n ================================================================== --- embedded/man/files/apps/page.n +++ embedded/man/files/apps/page.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -299,11 +298,11 @@ .sp If the argument is missing \fB-\fR is assumed. .RE .PP .SS OPERATION -... reading ... transforming ... writing - plugins - pipeline ... +\... 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. @@ -321,11 +320,10 @@ 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 @@ -461,19 +459,16 @@ It sets the application up as a parser generator accepting parsing expression grammars and writing a packrat parser in Tcl. The actual arguments it specifies are: .sp .CS - - - --reset - --append - --reader peg - --transform reach - --transform use - --writer me - +--reset +--append +--reader peg +--transform reach +--transform use +--writer me .CE .sp .RE .TP \fB-r\fR \fIname\fR @@ -642,7 +637,6 @@ .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/apps/tcldocstrip.n ================================================================== --- embedded/man/files/apps/tcldocstrip.n +++ embedded/man/files/apps/tcldocstrip.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -394,13 +393,12 @@ 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 +\\.dtx, LaTeX, conversion, docstrip, documentation, literate programming, markup, source .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/modules/aes/aes.n ================================================================== --- embedded/man/files/modules/aes/aes.n +++ embedded/man/files/modules/aes/aes.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -341,25 +340,19 @@ 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 @@ -382,7 +375,6 @@ Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2005, Pat Thoyts Copyright (c) 2012, Andreas Kupries - .fi Index: embedded/man/files/modules/amazon-s3/S3.n ================================================================== --- embedded/man/files/modules/amazon-s3/S3.n +++ embedded/man/files/modules/amazon-s3/S3.n @@ -1,8 +1,8 @@ '\" '\" 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. +'\" 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? @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -367,11 +366,11 @@ .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). +from Tcllib (available at \fIhttp://core.tcl.tk/tcllib/\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, @@ -1254,14 +1253,11 @@ 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 @@ -1539,29 +1535,23 @@ 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 +-timestamp aws do_my_process ./tempfiles other arguments S3::Push -bucket sample -prefix of/interest -directory ./tempfiles \\ - -compare newer -delete true - +-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 - +-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 @@ -1591,8 +1581,7 @@ amazon, cloud, s3 .SH CATEGORY Networking .SH COPYRIGHT .nf -Copyright (c) Copyright 2006,2008 Darren New. All Rights Reserved. See LICENSE.TXT for terms. - +2006,2008 Darren New. All Rights Reserved. See LICENSE.TXT for terms. .fi Index: embedded/man/files/modules/amazon-s3/xsxp.n ================================================================== --- embedded/man/files/modules/amazon-s3/xsxp.n +++ embedded/man/files/modules/amazon-s3/xsxp.n @@ -1,8 +1,8 @@ '\" '\" 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. +'\" 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? @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -344,11 +343,10 @@ 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? @@ -382,8 +380,7 @@ dom, parser, xml .SH CATEGORY Text processing .SH COPYRIGHT .nf -Copyright (c) Copyright 2006 Darren New. All Rights Reserved. - +2006 Darren New. All Rights Reserved. .fi Index: embedded/man/files/modules/asn/asn.n ================================================================== --- embedded/man/files/modules/asn/asn.n +++ embedded/man/files/modules/asn/asn.n @@ -222,11 +222,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -711,7 +710,6 @@ .SH COPYRIGHT .nf Copyright (c) 2004 Andreas Kupries Copyright (c) 2004 Jochen Loewer Copyright (c) 2004-2011 Michael Schlenker - .fi Index: embedded/man/files/modules/base32/base32.n ================================================================== --- embedded/man/files/modules/base32/base32.n +++ embedded/man/files/modules/base32/base32.n @@ -1,8 +1,8 @@ '\" '\" 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 +'\" Public domain '\" '\" The definitions below are for supplemental macros used in Tcl/Tk '\" manual entries. '\" '\" .AP type name in/out ?indent? @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -292,22 +291,19 @@ 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 - +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 @@ -318,8 +314,7 @@ base32, rfc3548 .SH CATEGORY Text processing .SH COPYRIGHT .nf -Copyright (c) Public domain - +Public domain .fi Index: embedded/man/files/modules/base32/base32core.n ================================================================== --- embedded/man/files/modules/base32/base32core.n +++ embedded/man/files/modules/base32/base32core.n @@ -1,8 +1,8 @@ '\" '\" 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 +'\" Public domain '\" '\" The definitions below are for supplemental macros used in Tcl/Tk '\" manual entries. '\" '\" .AP type name in/out ?indent? @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -306,8 +305,7 @@ base32 .SH CATEGORY Text processing .SH COPYRIGHT .nf -Copyright (c) Public domain - +Public domain .fi Index: embedded/man/files/modules/base32/base32hex.n ================================================================== --- embedded/man/files/modules/base32/base32hex.n +++ embedded/man/files/modules/base32/base32hex.n @@ -1,8 +1,8 @@ '\" '\" 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 +'\" Public domain '\" '\" The definitions below are for supplemental macros used in Tcl/Tk '\" manual entries. '\" '\" .AP type name in/out ?indent? @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -294,22 +293,19 @@ 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 - +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 @@ -320,8 +316,7 @@ base32, hex, rfc3548 .SH CATEGORY Text processing .SH COPYRIGHT .nf -Copyright (c) Public domain - +Public domain .fi Index: embedded/man/files/modules/base64/ascii85.n ================================================================== --- embedded/man/files/modules/base64/ascii85.n +++ embedded/man/files/modules/base64/ascii85.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -273,35 +272,26 @@ 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] @@ -320,7 +310,6 @@ .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 2010, Emiliano Gavilán - .fi Index: embedded/man/files/modules/base64/base64.n ================================================================== --- embedded/man/files/modules/base64/base64.n +++ embedded/man/files/modules/base64/base64.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -276,35 +275,26 @@ 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 @@ -317,7 +307,6 @@ Text processing .SH COPYRIGHT .nf Copyright (c) 2000, Eric Melski Copyright (c) 2001, Miguel Sofer - .fi Index: embedded/man/files/modules/base64/uuencode.n ================================================================== --- embedded/man/files/modules/base64/uuencode.n +++ embedded/man/files/modules/base64/uuencode.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -298,42 +297,30 @@ 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 - - -% 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 @@ -345,7 +332,6 @@ .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts - .fi Index: embedded/man/files/modules/base64/yencode.n ================================================================== --- embedded/man/files/modules/base64/yencode.n +++ embedded/man/files/modules/base64/yencode.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -302,17 +301,14 @@ 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- +-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 @@ -328,7 +324,6 @@ .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts - .fi Index: embedded/man/files/modules/bee/bee.n ================================================================== --- embedded/man/files/modules/bee/bee.n +++ embedded/man/files/modules/bee/bee.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -538,7 +537,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2004 Andreas Kupries - .fi Index: embedded/man/files/modules/bench/bench.n ================================================================== --- embedded/man/files/modules/bench/bench.n +++ embedded/man/files/modules/bench/bench.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -480,7 +479,6 @@ .SH CATEGORY Benchmark tools .SH COPYRIGHT .nf Copyright (c) 2007-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/bench/bench_intro.n ================================================================== --- embedded/man/files/modules/bench/bench_intro.n +++ embedded/man/files/modules/bench/bench_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -290,7 +289,6 @@ .SH CATEGORY Benchmark tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/bench/bench_lang_intro.n ================================================================== --- embedded/man/files/modules/bench/bench_lang_intro.n +++ embedded/man/files/modules/bench/bench_lang_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -256,16 +255,13 @@ 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 +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" @@ -278,20 +274,17 @@ 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] +set key [aes::Init ecb $k $i] } -body { - aes::Encrypt $key $p +aes::Encrypt $key $p } \fB-post\fR { - aes::Final $key +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 @@ -335,21 +328,18 @@ 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 +set A $sx($times,$n) +set B $A } -body { - struct::set include A x +struct::set include A x } \fB-ipost\fR { - unset A B +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 @@ -368,7 +358,6 @@ .SH CATEGORY Benchmark tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/bench/bench_lang_spec.n ================================================================== --- embedded/man/files/modules/bench/bench_lang_spec.n +++ embedded/man/files/modules/bench/bench_lang_spec.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -358,7 +357,6 @@ .SH CATEGORY Benchmark tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/bench/bench_read.n ================================================================== --- embedded/man/files/modules/bench/bench_read.n +++ embedded/man/files/modules/bench/bench_read.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -298,7 +297,6 @@ .SH CATEGORY Benchmark tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/bench/bench_wcsv.n ================================================================== --- embedded/man/files/modules/bench/bench_wcsv.n +++ embedded/man/files/modules/bench/bench_wcsv.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,7 +285,6 @@ .SH CATEGORY Benchmark tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/bench/bench_wtext.n ================================================================== --- embedded/man/files/modules/bench/bench_wtext.n +++ embedded/man/files/modules/bench/bench_wtext.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,7 +285,6 @@ .SH CATEGORY Benchmark tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/bibtex/bibtex.n ================================================================== --- embedded/man/files/modules/bibtex/bibtex.n +++ embedded/man/files/modules/bibtex/bibtex.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -391,7 +390,6 @@ .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 2005 for documentation, Andreas Kupries - .fi Index: embedded/man/files/modules/blowfish/blowfish.n ================================================================== --- embedded/man/files/modules/blowfish/blowfish.n +++ embedded/man/files/modules/blowfish/blowfish.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -342,24 +341,18 @@ 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 - +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. @@ -380,7 +373,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2003, Pat Thoyts - .fi Index: embedded/man/files/modules/cache/async.n ================================================================== --- embedded/man/files/modules/cache/async.n +++ embedded/man/files/modules/cache/async.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -369,7 +368,6 @@ .SH KEYWORDS asynchronous, cache, callback, synchronous .SH COPYRIGHT .nf Copyright (c) 2008 Andreas Kupries - .fi Index: embedded/man/files/modules/clock/iso8601.n ================================================================== --- embedded/man/files/modules/clock/iso8601.n +++ embedded/man/files/modules/clock/iso8601.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/clock/rfc2822.n ================================================================== --- embedded/man/files/modules/clock/rfc2822.n +++ embedded/man/files/modules/clock/rfc2822.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/cmdline/cmdline.n ================================================================== --- embedded/man/files/modules/cmdline/cmdline.n +++ embedded/man/files/modules/cmdline/cmdline.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -357,31 +356,27 @@ 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} { - ... - } - +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 Index: embedded/man/files/modules/comm/comm.n ================================================================== --- embedded/man/files/modules/comm/comm.n +++ embedded/man/files/modules/comm/comm.n @@ -222,11 +222,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -298,15 +297,12 @@ 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 - +::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 @@ -366,17 +362,14 @@ 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" - +% ::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" @@ -398,23 +391,17 @@ .PP .PP The default configuration parameters for a new channel are: .PP .CS - - - "-port 0 -local 1 -listen 0 -silent 0" - +"-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" - +"::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. @@ -549,14 +536,11 @@ \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" - +"::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. @@ -601,21 +585,18 @@ 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 - % - +% ::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. @@ -637,18 +618,15 @@ \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" - } - } - +::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. @@ -675,89 +653,71 @@ .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 - +% ::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 - +% ::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 - +% ::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 - +% 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]} - +% ::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 - +% ::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: @@ -804,20 +764,17 @@ 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 - } - } - +::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. @@ -832,23 +789,20 @@ 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] - } - +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 @@ -857,20 +811,16 @@ .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 - ... - +# 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 @@ -955,35 +905,26 @@ 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 -} - +# 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 @@ -1010,14 +951,11 @@ 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 - +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: @@ -1149,16 +1087,13 @@ 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 - +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 @@ -1259,14 +1194,11 @@ 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" - +"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 @@ -1303,7 +1235,6 @@ .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 Index: embedded/man/files/modules/comm/comm_wire.n ================================================================== --- embedded/man/files/modules/comm/comm_wire.n +++ embedded/man/files/modules/comm/comm_wire.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -324,37 +323,28 @@ 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 - +(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] - +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. @@ -380,15 +370,12 @@ 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}}} - +{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. @@ -403,7 +390,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2005 Docs. Andreas Kupries - .fi Index: embedded/man/files/modules/control/control.n ================================================================== --- embedded/man/files/modules/control/control.n +++ embedded/man/files/modules/control/control.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -316,21 +315,18 @@ \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 @@ -358,20 +354,17 @@ 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 Index: embedded/man/files/modules/coroutine/coro_auto.n ================================================================== --- embedded/man/files/modules/coroutine/coro_auto.n +++ embedded/man/files/modules/coroutine/coro_auto.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,7 +285,6 @@ .SH CATEGORY Coroutine .SH COPYRIGHT .nf Copyright (c) 2010-2011 Andreas Kupries - .fi Index: embedded/man/files/modules/coroutine/coroutine.n ================================================================== --- embedded/man/files/modules/coroutine/coroutine.n +++ embedded/man/files/modules/coroutine/coroutine.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -344,7 +343,6 @@ .SH CATEGORY Coroutine .SH COPYRIGHT .nf Copyright (c) 2010-2011 Andreas Kupries - .fi Index: embedded/man/files/modules/counter/counter.n ================================================================== --- embedded/man/files/modules/counter/counter.n +++ embedded/man/files/modules/counter/counter.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/crc/cksum.n ================================================================== --- embedded/man/files/modules/crc/cksum.n +++ embedded/man/files/modules/crc/cksum.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -310,42 +309,30 @@ 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 - - +% 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 @@ -361,7 +348,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts - .fi Index: embedded/man/files/modules/crc/crc16.n ================================================================== --- embedded/man/files/modules/crc/crc16.n +++ embedded/man/files/modules/crc/crc16.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -331,39 +330,27 @@ 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 - +% 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 @@ -379,7 +366,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts - .fi Index: embedded/man/files/modules/crc/crc32.n ================================================================== --- embedded/man/files/modules/crc/crc32.n +++ embedded/man/files/modules/crc/crc32.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -326,42 +325,30 @@ 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 - - +% 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 @@ -377,7 +364,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts - .fi Index: embedded/man/files/modules/crc/sum.n ================================================================== --- embedded/man/files/modules/crc/sum.n +++ embedded/man/files/modules/crc/sum.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -292,31 +291,22 @@ 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 -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 @@ -332,7 +322,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts - .fi Index: embedded/man/files/modules/csv/csv.n ================================================================== --- embedded/man/files/modules/csv/csv.n +++ embedded/man/files/modules/csv/csv.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -422,38 +421,29 @@ \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 @@ -469,7 +459,6 @@ .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 2002-2013 Andreas Kupries - .fi Index: embedded/man/files/modules/des/des.n ================================================================== --- embedded/man/files/modules/des/des.n +++ embedded/man/files/modules/des/des.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -366,27 +365,21 @@ 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, @@ -413,7 +406,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2005, Pat Thoyts - .fi Index: embedded/man/files/modules/dns/tcllib_dns.n ================================================================== --- embedded/man/files/modules/dns/tcllib_dns.n +++ embedded/man/files/modules/dns/tcllib_dns.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -420,43 +419,34 @@ 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. @@ -499,7 +489,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts - .fi Index: embedded/man/files/modules/dns/tcllib_ip.n ================================================================== --- embedded/man/files/modules/dns/tcllib_ip.n +++ embedded/man/files/modules/dns/tcllib_ip.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -351,15 +350,12 @@ (/ 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 - +% 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. @@ -377,104 +373,78 @@ 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 - +% 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 - +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 - +% ::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 - +% ::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 - +::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 - +::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 - +::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 - +::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 @@ -491,18 +461,14 @@ 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 - +% ::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 @@ -529,61 +495,47 @@ 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 - +% ::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 - +% ::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 - +%::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 - +% ::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 @@ -591,15 +543,12 @@ 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 - +% ::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 @@ -609,15 +558,12 @@ 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 @@ -627,40 +573,31 @@ 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) @@ -687,7 +624,6 @@ Networking .SH COPYRIGHT .nf Copyright (c) 2004, Pat Thoyts Copyright (c) 2005 Aamer Akhter - .fi Index: embedded/man/files/modules/docstrip/docstrip.n ================================================================== --- embedded/man/files/modules/docstrip/docstrip.n +++ embedded/man/files/modules/docstrip/docstrip.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -318,35 +317,29 @@ 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] {} - +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 - +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 @@ -365,28 +358,22 @@ 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 - +\'%' '<' 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 } - +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 @@ -399,59 +386,53 @@ 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] - +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 - +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 @@ -463,91 +444,79 @@ 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 {#}] - +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 - +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 {}] - +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 - +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 @@ -639,21 +608,18 @@ 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 - +% \\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, @@ -680,13 +646,12 @@ 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 +\\.dtx, LaTeX, docstrip, documentation, literate programming, source .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2003–2010 Lars Hellström - .fi Index: embedded/man/files/modules/docstrip/docstrip_util.n ================================================================== --- embedded/man/files/modules/docstrip/docstrip_util.n +++ embedded/man/files/modules/docstrip/docstrip_util.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -331,12 +330,10 @@ 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 @@ -345,32 +342,29 @@ %% 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 ... +# ... 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 [file rootname [info script]][info sharedlibextension] % %<*!load> - # ... even more clever scripted counterpart of the extension - # also elided ... +# ... 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 @@ -380,27 +374,26 @@ % \\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 ... +# ... 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 [file rootname [info script]][info sharedlibextension] % %<*!load> - # ... even more clever scripted counterpart of the extension - # also elided ... +# ... 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" @@ -543,12 +536,10 @@ .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: @@ -556,20 +547,16 @@ ## 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} - +"\\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. @@ -576,27 +563,21 @@ .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} - +"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 @@ -623,12 +604,11 @@ 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]] +$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 @@ -669,12 +649,10 @@ .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] % @@ -684,26 +662,25 @@ % 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)}] +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] }] } +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. @@ -832,21 +809,18 @@ 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 {#}] +[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". @@ -879,13 +853,12 @@ 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 +\\.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 Index: embedded/man/files/modules/doctools/changelog.n ================================================================== --- embedded/man/files/modules/doctools/changelog.n +++ embedded/man/files/modules/doctools/changelog.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -275,27 +274,24 @@ 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 - } - ... - } - } - {...} - } - +{ +{ +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 @@ -330,7 +326,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2003-2013 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/cvs.n ================================================================== --- embedded/man/files/modules/doctools/cvs.n +++ embedded/man/files/modules/doctools/cvs.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -327,7 +326,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2003-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/docidx.n ================================================================== --- embedded/man/files/modules/doctools/docidx.n +++ embedded/man/files/modules/doctools/docidx.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -561,7 +560,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2003-2010 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/docidx_intro.n ================================================================== --- embedded/man/files/modules/doctools/docidx_intro.n +++ embedded/man/files/modules/doctools/docidx_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -313,7 +312,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/docidx_lang_cmdref.n ================================================================== --- embedded/man/files/modules/doctools/docidx_lang_cmdref.n +++ embedded/man/files/modules/doctools/docidx_lang_cmdref.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -356,7 +355,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/docidx_lang_faq.n ================================================================== --- embedded/man/files/modules/doctools/docidx_lang_faq.n +++ embedded/man/files/modules/doctools/docidx_lang_faq.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/docidx_lang_intro.n ================================================================== --- embedded/man/files/modules/doctools/docidx_lang_intro.n +++ embedded/man/files/modules/doctools/docidx_lang_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -260,49 +259,37 @@ \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}] ... - +\... [key {markup language}] ... .CE .CS - - - ... [manpage thefile \\\\ - {file description}] ... - +\... [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] - +[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 @@ -309,12 +296,10 @@ 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] @@ -327,11 +312,10 @@ [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. @@ -349,31 +333,25 @@ 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 @@ -387,18 +365,15 @@ 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. - ... - +\... +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 @@ -428,7 +403,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/docidx_lang_syntax.n ================================================================== --- embedded/man/files/modules/doctools/docidx_lang_syntax.n +++ embedded/man/files/modules/doctools/docidx_lang_syntax.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -288,24 +287,19 @@ .IP [2] The construct [ X ] stands for zero or one occurrence of X. .PP The syntax: .CS - - index = defs - INDEX_BEGIN - [ contents ] - INDEX_END - { } - +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] @@ -332,7 +326,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/docidx_plugin_apiref.n ================================================================== --- embedded/man/files/modules/doctools/docidx_plugin_apiref.n +++ embedded/man/files/modules/doctools/docidx_plugin_apiref.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -429,31 +428,27 @@ .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 - ... - +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 @@ -610,7 +605,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctoc.n ================================================================== --- embedded/man/files/modules/doctools/doctoc.n +++ embedded/man/files/modules/doctools/doctoc.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -561,7 +560,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2003-2010 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctoc_intro.n ================================================================== --- embedded/man/files/modules/doctools/doctoc_intro.n +++ embedded/man/files/modules/doctools/doctoc_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -312,7 +311,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctoc_lang_cmdref.n ================================================================== --- embedded/man/files/modules/doctools/doctoc_lang_cmdref.n +++ embedded/man/files/modules/doctools/doctoc_lang_cmdref.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -363,7 +362,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctoc_lang_faq.n ================================================================== --- embedded/man/files/modules/doctools/doctoc_lang_faq.n +++ embedded/man/files/modules/doctools/doctoc_lang_faq.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctoc_lang_intro.n ================================================================== --- embedded/man/files/modules/doctools/doctoc_lang_intro.n +++ embedded/man/files/modules/doctools/doctoc_lang_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -260,30 +259,21 @@ \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}] ... - +\... [division_start {Appendix 1}] ... .CE .CS - - - ... [item thefile \\\\ - label {file description}] ... - +\... [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] - +[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 @@ -305,20 +295,17 @@ 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 @@ -347,28 +334,23 @@ 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] @@ -384,17 +366,14 @@ [\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] @@ -408,11 +387,10 @@ [\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. @@ -420,31 +398,25 @@ 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 @@ -458,18 +430,15 @@ 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. - ... - +\... +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 @@ -499,7 +468,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctoc_lang_syntax.n ================================================================== --- embedded/man/files/modules/doctools/doctoc_lang_syntax.n +++ embedded/man/files/modules/doctools/doctoc_lang_syntax.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -288,27 +287,21 @@ .IP [2] The construct [ X ] stands for zero or one occurrence of X. .PP The syntax: .CS - - toc = defs - TOC_BEGIN - contents - TOC_END - { } - +TOC_BEGIN +contents +TOC_END +{ } defs = { INCLUDE | VSET | } contents = { defs entry } [ defs ] - entry = ITEM | division - division = DIVISION_START - contents - DIVISION_END - +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]. @@ -320,7 +313,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctoc_plugin_apiref.n ================================================================== --- embedded/man/files/modules/doctools/doctoc_plugin_apiref.n +++ embedded/man/files/modules/doctools/doctoc_plugin_apiref.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -429,31 +428,27 @@ .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 - ... - +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 @@ -610,7 +605,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctools.n ================================================================== --- embedded/man/files/modules/doctools/doctools.n +++ embedded/man/files/modules/doctools/doctools.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -669,7 +668,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2003-2013 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctools_intro.n ================================================================== --- embedded/man/files/modules/doctools/doctools_intro.n +++ embedded/man/files/modules/doctools/doctools_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -311,7 +310,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctools_lang_cmdref.n ================================================================== --- embedded/man/files/modules/doctools/doctools_lang_cmdref.n +++ embedded/man/files/modules/doctools/doctools_lang_cmdref.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -776,7 +775,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007-2010 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctools_lang_faq.n ================================================================== --- embedded/man/files/modules/doctools/doctools_lang_faq.n +++ embedded/man/files/modules/doctools/doctools_lang_faq.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -283,7 +282,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctools_lang_intro.n ================================================================== --- embedded/man/files/modules/doctools/doctools_lang_intro.n +++ embedded/man/files/modules/doctools/doctools_lang_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -259,43 +258,28 @@ \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]"] ... - +\... [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] - +[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 @@ -328,42 +312,34 @@ 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] - +[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] @@ -370,11 +346,10 @@ [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. @@ -382,31 +357,25 @@ 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 @@ -425,21 +394,18 @@ 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 @@ -451,23 +417,20 @@ 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 @@ -476,27 +439,24 @@ 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 @@ -581,21 +541,17 @@ 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. - ... - +\... +[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 @@ -606,18 +562,15 @@ 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. - ... - +\... +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 @@ -647,21 +600,18 @@ .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] - +\... +[\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 @@ -677,25 +627,19 @@ \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] ... - }] - +[\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] - +[\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 @@ -751,52 +695,40 @@ 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] - ... - +\... +[\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] - ... - +\... +[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 @@ -822,7 +754,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctools_lang_syntax.n ================================================================== --- embedded/man/files/modules/doctools/doctools_lang_syntax.n +++ embedded/man/files/modules/doctools/doctools_lang_syntax.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -292,60 +291,46 @@ 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 - { } - +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 - +| FUN | LB | METHOD | NAMESPACE | OPT | OPTION +| PACKAGE | RB | SECTREF | STRONG | SYSCMD | TERM +| TYPE | URI | USAGE | VAR | WIDGET example = EXAMPLE - | EXAMPLE_BEGIN extext EXAMPLE_END - +| 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 - +| 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]. @@ -357,7 +342,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/doctools_plugin_apiref.n ================================================================== --- embedded/man/files/modules/doctools/doctools_plugin_apiref.n +++ embedded/man/files/modules/doctools/doctools_plugin_apiref.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -497,31 +496,27 @@ .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 - ... - +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 @@ -678,7 +673,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2007-2010 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools/mpexpand.n ================================================================== --- embedded/man/files/modules/doctools/mpexpand.n +++ embedded/man/files/modules/doctools/mpexpand.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -313,7 +312,6 @@ Documentation tools .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries Copyright (c) 2003 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2base/html_cssdefaults.n ================================================================== --- embedded/man/files/modules/doctools2base/html_cssdefaults.n +++ embedded/man/files/modules/doctools2base/html_cssdefaults.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -276,7 +275,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2base/nroff_manmacros.n ================================================================== --- embedded/man/files/modules/doctools2base/nroff_manmacros.n +++ embedded/man/files/modules/doctools2base/nroff_manmacros.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -276,7 +275,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2base/tcl_parse.n ================================================================== --- embedded/man/files/modules/doctools2base/tcl_parse.n +++ embedded/man/files/modules/doctools2base/tcl_parse.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -402,7 +401,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2base/tcllib_msgcat.n ================================================================== --- embedded/man/files/modules/doctools2base/tcllib_msgcat.n +++ embedded/man/files/modules/doctools2base/tcllib_msgcat.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -297,7 +296,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/container.n ================================================================== --- embedded/man/files/modules/doctools2idx/container.n +++ embedded/man/files/modules/doctools2idx/container.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -620,7 +619,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/export.n ================================================================== --- embedded/man/files/modules/doctools2idx/export.n +++ embedded/man/files/modules/doctools2idx/export.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -634,7 +633,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/export_docidx.n ================================================================== --- embedded/man/files/modules/doctools2idx/export_docidx.n +++ embedded/man/files/modules/doctools2idx/export_docidx.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -428,7 +427,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/export_html.n ================================================================== --- embedded/man/files/modules/doctools2idx/export_html.n +++ embedded/man/files/modules/doctools2idx/export_html.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -513,7 +512,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/export_json.n ================================================================== --- embedded/man/files/modules/doctools2idx/export_json.n +++ embedded/man/files/modules/doctools2idx/export_json.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -279,57 +278,51 @@ 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 {} -} - +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" : "" - } -} - +{ +"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 @@ -445,7 +438,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/export_nroff.n ================================================================== --- embedded/man/files/modules/doctools2idx/export_nroff.n +++ embedded/man/files/modules/doctools2idx/export_nroff.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -396,7 +395,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/export_text.n ================================================================== --- embedded/man/files/modules/doctools2idx/export_text.n +++ embedded/man/files/modules/doctools2idx/export_text.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -380,7 +379,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/export_wiki.n ================================================================== --- embedded/man/files/modules/doctools2idx/export_wiki.n +++ embedded/man/files/modules/doctools2idx/export_wiki.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -393,7 +392,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/import.n ================================================================== --- embedded/man/files/modules/doctools2idx/import.n +++ embedded/man/files/modules/doctools2idx/import.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -713,7 +712,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/import_docidx.n ================================================================== --- embedded/man/files/modules/doctools2idx/import_docidx.n +++ embedded/man/files/modules/doctools2idx/import_docidx.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -404,7 +403,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/import_json.n ================================================================== --- embedded/man/files/modules/doctools2idx/import_json.n +++ embedded/man/files/modules/doctools2idx/import_json.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -281,57 +280,51 @@ 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 {} -} - +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" : "" - } -} - +{ +"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. @@ -422,7 +415,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/introduction.n ================================================================== --- embedded/man/files/modules/doctools2idx/introduction.n +++ embedded/man/files/modules/doctools2idx/introduction.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -332,44 +331,40 @@ 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::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. - - +| | | | | +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 @@ -383,7 +378,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/msgcat_c.n ================================================================== --- embedded/man/files/modules/doctools2idx/msgcat_c.n +++ embedded/man/files/modules/doctools2idx/msgcat_c.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/msgcat_de.n ================================================================== --- embedded/man/files/modules/doctools2idx/msgcat_de.n +++ embedded/man/files/modules/doctools2idx/msgcat_de.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/msgcat_en.n ================================================================== --- embedded/man/files/modules/doctools2idx/msgcat_en.n +++ embedded/man/files/modules/doctools2idx/msgcat_en.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/msgcat_fr.n ================================================================== --- embedded/man/files/modules/doctools2idx/msgcat_fr.n +++ embedded/man/files/modules/doctools2idx/msgcat_fr.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/parse.n ================================================================== --- embedded/man/files/modules/doctools2idx/parse.n +++ embedded/man/files/modules/doctools2idx/parse.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -501,7 +500,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2idx/structure.n ================================================================== --- embedded/man/files/modules/doctools2idx/structure.n +++ embedded/man/files/modules/doctools2idx/structure.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -429,7 +428,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/container.n ================================================================== --- embedded/man/files/modules/doctools2toc/container.n +++ embedded/man/files/modules/doctools2toc/container.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -703,7 +702,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/export.n ================================================================== --- embedded/man/files/modules/doctools2toc/export.n +++ embedded/man/files/modules/doctools2toc/export.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -651,7 +650,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/export_doctoc.n ================================================================== --- embedded/man/files/modules/doctools2toc/export_doctoc.n +++ embedded/man/files/modules/doctools2toc/export_doctoc.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -455,7 +454,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/export_html.n ================================================================== --- embedded/man/files/modules/doctools2toc/export_html.n +++ embedded/man/files/modules/doctools2toc/export_html.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -505,7 +504,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/export_json.n ================================================================== --- embedded/man/files/modules/doctools2toc/export_json.n +++ embedded/man/files/modules/doctools2toc/export_json.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -279,77 +278,71 @@ 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 -} - +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" - } -} - +{ +"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 @@ -493,7 +486,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/export_nroff.n ================================================================== --- embedded/man/files/modules/doctools2toc/export_nroff.n +++ embedded/man/files/modules/doctools2toc/export_nroff.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -424,7 +423,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/export_text.n ================================================================== --- embedded/man/files/modules/doctools2toc/export_text.n +++ embedded/man/files/modules/doctools2toc/export_text.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -407,7 +406,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/export_wiki.n ================================================================== --- embedded/man/files/modules/doctools2toc/export_wiki.n +++ embedded/man/files/modules/doctools2toc/export_wiki.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -413,7 +412,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/import.n ================================================================== --- embedded/man/files/modules/doctools2toc/import.n +++ embedded/man/files/modules/doctools2toc/import.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -732,7 +731,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/import_doctoc.n ================================================================== --- embedded/man/files/modules/doctools2toc/import_doctoc.n +++ embedded/man/files/modules/doctools2toc/import_doctoc.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -432,7 +431,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/import_json.n ================================================================== --- embedded/man/files/modules/doctools2toc/import_json.n +++ embedded/man/files/modules/doctools2toc/import_json.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -281,77 +280,71 @@ 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 -} - +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" - } -} - +{ +"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. @@ -470,7 +463,6 @@ .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/introduction.n ================================================================== --- embedded/man/files/modules/doctools2toc/introduction.n +++ embedded/man/files/modules/doctools2toc/introduction.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -332,44 +331,40 @@ 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::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. - - +| | | | | +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 @@ -383,7 +378,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/msgcat_c.n ================================================================== --- embedded/man/files/modules/doctools2toc/msgcat_c.n +++ embedded/man/files/modules/doctools2toc/msgcat_c.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/msgcat_de.n ================================================================== --- embedded/man/files/modules/doctools2toc/msgcat_de.n +++ embedded/man/files/modules/doctools2toc/msgcat_de.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/msgcat_en.n ================================================================== --- embedded/man/files/modules/doctools2toc/msgcat_en.n +++ embedded/man/files/modules/doctools2toc/msgcat_en.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/msgcat_fr.n ================================================================== --- embedded/man/files/modules/doctools2toc/msgcat_fr.n +++ embedded/man/files/modules/doctools2toc/msgcat_fr.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -285,7 +284,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/parse.n ================================================================== --- embedded/man/files/modules/doctools2toc/parse.n +++ embedded/man/files/modules/doctools2toc/parse.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -529,7 +528,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/doctools2toc/structure.n ================================================================== --- embedded/man/files/modules/doctools2toc/structure.n +++ embedded/man/files/modules/doctools2toc/structure.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -474,7 +473,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi ADDED embedded/man/files/modules/dtplite/dtplite.n Index: embedded/man/files/modules/dtplite/dtplite.n ================================================================== --- /dev/null +++ embedded/man/files/modules/dtplite/dtplite.n @@ -0,0 +1,554 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/dtplite/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 +.. +'\" # CS - begin code excerpt +.de 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 Index: embedded/man/files/modules/exif/exif.n ================================================================== --- embedded/man/files/modules/exif/exif.n +++ embedded/man/files/modules/exif/exif.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/fileutil/fileutil.n ================================================================== --- embedded/man/files/modules/fileutil/fileutil.n +++ embedded/man/files/modules/fileutil/fileutil.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -309,18 +308,14 @@ 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 - +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. @@ -483,17 +478,14 @@ 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] - +# 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 Index: embedded/man/files/modules/fileutil/multi.n ================================================================== --- embedded/man/files/modules/fileutil/multi.n +++ embedded/man/files/modules/fileutil/multi.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/fileutil/multiop.n ================================================================== --- embedded/man/files/modules/fileutil/multiop.n +++ embedded/man/files/modules/fileutil/multiop.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -601,64 +600,48 @@ .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 - +$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 * - +$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, @@ -666,21 +649,18 @@ \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 - +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 Index: embedded/man/files/modules/fileutil/traverse.n ================================================================== --- embedded/man/files/modules/fileutil/traverse.n +++ embedded/man/files/modules/fileutil/traverse.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/ftp/ftp.n ================================================================== --- embedded/man/files/modules/ftp/ftp.n +++ embedded/man/files/modules/ftp/ftp.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/ftp/ftp_geturl.n ================================================================== --- embedded/man/files/modules/ftp/ftp_geturl.n +++ embedded/man/files/modules/ftp/ftp_geturl.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/ftpd/ftpd.n ================================================================== --- embedded/man/files/modules/ftpd/ftpd.n +++ embedded/man/files/modules/ftpd/ftpd.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/fumagic/cfront.n ================================================================== --- embedded/man/files/modules/fumagic/cfront.n +++ embedded/man/files/modules/fumagic/cfront.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/fumagic/cgen.n ================================================================== --- embedded/man/files/modules/fumagic/cgen.n +++ embedded/man/files/modules/fumagic/cgen.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/fumagic/filetypes.n ================================================================== --- embedded/man/files/modules/fumagic/filetypes.n +++ embedded/man/files/modules/fumagic/filetypes.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/fumagic/mimetypes.n ================================================================== --- embedded/man/files/modules/fumagic/mimetypes.n +++ embedded/man/files/modules/fumagic/mimetypes.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/fumagic/rtcore.n ================================================================== --- embedded/man/files/modules/fumagic/rtcore.n +++ embedded/man/files/modules/fumagic/rtcore.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -356,22 +355,16 @@ .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 - +& number .CE .IP For example: .CS - - - Nv lelong 0 &0x8080ffff - +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? @@ -381,14 +374,11 @@ comparison. .sp The argument \fIcomp\fR has to contain one of Tcl's comparison operators, and the comparison made will be .CS - - - - + .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. Index: embedded/man/files/modules/generator/generator.n ================================================================== --- embedded/man/files/modules/generator/generator.n +++ embedded/man/files/modules/generator/generator.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -363,19 +362,16 @@ 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" - } - +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 @@ -384,19 +380,16 @@ 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 } - } - +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 @@ -467,41 +460,35 @@ 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 - +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] } - } - +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 @@ -513,16 +500,12 @@ \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 - - +[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 @@ -537,18 +520,15 @@ 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 } - } - +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 @@ -556,15 +536,12 @@ 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] - +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 @@ -577,49 +554,40 @@ 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] - # = ((((0+1)+2)+3)+4)+5 - # = 15 - proc + {a b} { expr {$a + $b} } - proc sum gen { generator reduce + 0 $gen } - puts [sum [range 1 10]] - +# sum xs = reduce + 0 xs +# sum [range 1 5] = reduce + 0 [range 1 5] +# = reduce + [+ 0 1] [range 2 5] +# = reduce + [+ 1 2] [range 3 5] +# = ... +# = reduce + [+ 10 5] +# = ((((0+1)+2)+3)+4)+5 +# = 15 +proc + {a b} { expr {$a + $b} } +proc sum gen { generator reduce + 0 $gen } +puts [sum [range 1 10]] .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] } - +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 - +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 @@ -695,17 +663,14 @@ \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}] } - +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 @@ -734,15 +699,12 @@ 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 - +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 Index: embedded/man/files/modules/gpx/gpx.n ================================================================== --- embedded/man/files/modules/gpx/gpx.n +++ embedded/man/files/modules/gpx/gpx.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -359,23 +358,20 @@ 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" - } +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) @@ -398,7 +394,6 @@ .SH CATEGORY File formats .SH COPYRIGHT .nf Copyright (c) 2010, Keith Vetter - .fi Index: embedded/man/files/modules/grammar_aycock/aycock.n ================================================================== --- embedded/man/files/modules/grammar_aycock/aycock.n +++ embedded/man/files/modules/grammar_aycock/aycock.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -339,24 +338,21 @@ 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} +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 @@ -365,7 +361,6 @@ Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2006 by Kevin B. Kenny Redistribution permitted under the terms of the Open Publication License - .fi Index: embedded/man/files/modules/grammar_fa/dacceptor.n ================================================================== --- embedded/man/files/modules/grammar_fa/dacceptor.n +++ embedded/man/files/modules/grammar_fa/dacceptor.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -326,7 +325,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2004 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_fa/dexec.n ================================================================== --- embedded/man/files/modules/grammar_fa/dexec.n +++ embedded/man/files/modules/grammar_fa/dexec.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -397,7 +396,6 @@ Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2004 Andreas Kupries Copyright (c) 2007 Bogdan - .fi Index: embedded/man/files/modules/grammar_fa/fa.n ================================================================== --- embedded/man/files/modules/grammar_fa/fa.n +++ embedded/man/files/modules/grammar_fa/fa.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -435,14 +434,11 @@ deleted by this operation. .sp This operation is in effect equivalent to .sp .CS - - - \fIfaName\fR \fBdeserialize\fR [\fIsrcFA\fR \fBserialize\fR] - +\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 @@ -450,14 +446,11 @@ 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] - +\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 @@ -504,29 +497,23 @@ .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. - +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}}} - +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 @@ -735,14 +722,11 @@ \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] - +[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. @@ -756,14 +740,11 @@ \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] - +[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. @@ -839,11 +820,11 @@ 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 +\... 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. @@ -891,7 +872,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2004-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_fa/faop.n ================================================================== --- embedded/man/files/modules/grammar_fa/faop.n +++ embedded/man/files/modules/grammar_fa/faop.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -655,7 +654,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2004-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_me/gasm.n ================================================================== --- embedded/man/files/modules/grammar_me/gasm.n +++ embedded/man/files/modules/grammar_me/gasm.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -638,7 +637,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_me/me_ast.n ================================================================== --- embedded/man/files/modules/grammar_me/me_ast.n +++ embedded/man/files/modules/grammar_me/me_ast.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -338,7 +337,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_me/me_cpu.n ================================================================== --- embedded/man/files/modules/grammar_me/me_cpu.n +++ embedded/man/files/modules/grammar_me/me_cpu.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -524,7 +523,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005-2006 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_me/me_cpucore.n ================================================================== --- embedded/man/files/modules/grammar_me/me_cpucore.n +++ embedded/man/files/modules/grammar_me/me_cpucore.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -637,7 +636,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005-2006 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_me/me_intro.n ================================================================== --- embedded/man/files/modules/grammar_me/me_intro.n +++ embedded/man/files/modules/grammar_me/me_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -303,7 +302,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_me/me_tcl.n ================================================================== --- embedded/man/files/modules/grammar_me/me_tcl.n +++ embedded/man/files/modules/grammar_me/me_tcl.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -591,7 +590,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_me/me_util.n ================================================================== --- embedded/man/files/modules/grammar_me/me_util.n +++ embedded/man/files/modules/grammar_me/me_util.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -320,7 +319,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_me/me_vm.n ================================================================== --- embedded/man/files/modules/grammar_me/me_vm.n +++ embedded/man/files/modules/grammar_me/me_vm.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -720,7 +719,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_peg/peg.n ================================================================== --- embedded/man/files/modules/grammar_peg/peg.n +++ embedded/man/files/modules/grammar_peg/peg.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -337,21 +336,16 @@ 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 - +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. @@ -452,14 +446,11 @@ deleted by this operation. .sp This operation is in effect equivalent to .sp .CS - - - \fIpegName\fR \fBdeserialize\fR [\fIsrcPEG\fR \fBserialize\fR] - +\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 @@ -467,14 +458,11 @@ 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] - +\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 @@ -507,45 +495,39 @@ .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 - +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 - +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 @@ -813,7 +795,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/modules/grammar_peg/peg_interp.n ================================================================== --- embedded/man/files/modules/grammar_peg/peg_interp.n +++ embedded/man/files/modules/grammar_peg/peg_interp.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -333,7 +332,6 @@ .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005-2011 Andreas Kupries - .fi Index: embedded/man/files/modules/hook/hook.n ================================================================== --- embedded/man/files/modules/hook/hook.n +++ embedded/man/files/modules/hook/hook.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -373,22 +372,16 @@ 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 - +hook bind $s $h $o $binding .CE .IP is called during the execution of .CS - - - hook call $s $h - +hook call $s $h .CE .RS .IP [1] No binding is ever called after it is deleted. .IP [2] @@ -404,39 +397,30 @@ .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 - +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 - +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 - +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 @@ -486,11 +470,10 @@ 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. @@ -543,34 +526,25 @@ .PP .SH EXAMPLE The \fB::model\fR module calls the hook in response to commands that change the model's data: .CS - - - hook call ::model - +hook call ::model .CE The \fB.view\fR megawidget displays the model state, and needs to know about model updates. Consequently, it subscribes to the ::model's hook. .CS - - - hook bind ::model .view [list .view ModelUpdate] - +hook bind ::model .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 - +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" @@ -587,7 +561,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2010, by William H. Duquette - .fi Index: embedded/man/files/modules/html/html.n ================================================================== --- embedded/man/files/modules/html/html.n +++ embedded/man/files/modules/html/html.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -461,14 +460,11 @@ \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" - +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 Index: embedded/man/files/modules/htmlparse/htmlparse.n ================================================================== --- embedded/man/files/modules/htmlparse/htmlparse.n +++ embedded/man/files/modules/htmlparse/htmlparse.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/http/autoproxy.n ================================================================== --- embedded/man/files/modules/http/autoproxy.n +++ embedded/man/files/modules/http/autoproxy.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -379,29 +378,23 @@ 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", Index: embedded/man/files/modules/ident/ident.n ================================================================== --- embedded/man/files/modules/ident/ident.n +++ embedded/man/files/modules/ident/ident.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -292,7 +291,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2004 Reinhard Max - .fi Index: embedded/man/files/modules/imap4/imap4.n ================================================================== --- embedded/man/files/modules/imap4/imap4.n +++ embedded/man/files/modules/imap4/imap4.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -323,15 +322,13 @@ .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 +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. @@ -357,11 +354,10 @@ .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 @@ -435,14 +431,11 @@ \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 @@ -488,14 +481,12 @@ \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" +::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. @@ -581,11 +572,10 @@ 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 @@ -648,14 +638,11 @@ message. .RE .IP For example: .CS - - - ::imap4::store $chan $start_msgid:$end_msgid +FLAGS "Deleted" - +::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 @@ -686,43 +673,37 @@ .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 - +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 Index: embedded/man/files/modules/inifile/ini.n ================================================================== --- embedded/man/files/modules/inifile/ini.n +++ embedded/man/files/modules/inifile/ini.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/interp/deleg_method.n ================================================================== --- embedded/man/files/modules/interp/deleg_method.n +++ embedded/man/files/modules/interp/deleg_method.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,7 +285,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/interp/deleg_proc.n ================================================================== --- embedded/man/files/modules/interp/deleg_proc.n +++ embedded/man/files/modules/interp/deleg_proc.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -284,7 +283,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/interp/tcllib_interp.n ================================================================== --- embedded/man/files/modules/interp/tcllib_interp.n +++ embedded/man/files/modules/interp/tcllib_interp.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -305,7 +304,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/irc/irc.n ================================================================== --- embedded/man/files/modules/irc/irc.n +++ embedded/man/files/modules/irc/irc.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/irc/picoirc.n ================================================================== --- embedded/man/files/modules/irc/picoirc.n +++ embedded/man/files/modules/irc/picoirc.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -299,15 +298,12 @@ 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 Index: embedded/man/files/modules/javascript/javascript.n ================================================================== --- embedded/man/files/modules/javascript/javascript.n +++ embedded/man/files/modules/javascript/javascript.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/jpeg/jpeg.n ================================================================== --- embedded/man/files/modules/jpeg/jpeg.n +++ embedded/man/files/modules/jpeg/jpeg.n @@ -223,11 +223,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -314,34 +313,28 @@ 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 - +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} - } - +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? @@ -357,24 +350,18 @@ \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" - } - +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)]] - +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. @@ -445,7 +432,6 @@ .nf Copyright (c) 2004-2005, Code: Aaron Faupell Copyright (c) 2007, Code: Andreas Kupries Copyright (c) 2004-2009, Doc: Andreas Kupries Copyright (c) 2011, Code: Pat Thoyts - .fi Index: embedded/man/files/modules/json/json.n ================================================================== --- embedded/man/files/modules/json/json.n +++ embedded/man/files/modules/json/json.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -270,59 +269,55 @@ .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" - } +[ +{ +"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": { +"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 @@ -335,7 +330,6 @@ CGI programming .SH COPYRIGHT .nf Copyright (c) 2006 ActiveState Software Inc. Copyright (c) 2009 Thomas Maeder, Glue Software Engineering AG - .fi Index: embedded/man/files/modules/json/json_write.n ================================================================== --- embedded/man/files/modules/json/json_write.n +++ embedded/man/files/modules/json/json_write.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -325,7 +324,6 @@ .SH CATEGORY CGI programming .SH COPYRIGHT .nf Copyright (c) 2009-2013 Andreas Kupries - .fi Index: embedded/man/files/modules/lambda/lambda.n ================================================================== --- embedded/man/files/modules/lambda/lambda.n +++ embedded/man/files/modules/lambda/lambda.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -256,44 +255,32 @@ .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} { - .... - }}} - +set f {::apply {{x} { +\.... +}}} .CE with its deep nesting of braces, or .CS - - - set f [list ::apply {{x y} { - .... - }} $value_for_x] - +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} { - .... - }] - +set f [lambda {x} { +\.... +}] .CE and .CS - - - set f [lambda {x y} { - .... - } $value_for_x] - +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 @@ -330,7 +317,6 @@ .SH CATEGORY Utility .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries, BSD licensed - .fi Index: embedded/man/files/modules/ldap/ldap.n ================================================================== --- embedded/man/files/modules/ldap/ldap.n +++ embedded/man/files/modules/ldap/ldap.n @@ -222,11 +222,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -375,25 +374,19 @@ 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*)" - +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 ...} ...}} ... - +{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 @@ -412,14 +405,11 @@ 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 ... } - +{-option1 value1 -option2 value2 ... } .CE .sp Following options are available: .RS .TP @@ -461,14 +451,11 @@ 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...} ...} - +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 @@ -516,14 +503,11 @@ 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...} ... - +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. @@ -624,108 +608,84 @@ .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 - +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 - +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 @@ -741,7 +701,6 @@ .SH COPYRIGHT .nf Copyright (c) 2004 Andreas Kupries Copyright (c) 2004 Jochen Loewer Copyright (c) 2006 Michael Schlenker - .fi Index: embedded/man/files/modules/ldap/ldapx.n ================================================================== --- embedded/man/files/modules/ldap/ldapx.n +++ embedded/man/files/modules/ldap/ldapx.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -547,74 +546,56 @@ 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 - +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 @@ -748,62 +729,52 @@ 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 - +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 @@ -881,59 +852,47 @@ 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 - +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. @@ -946,7 +905,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2006 Pierre David - .fi Index: embedded/man/files/modules/log/log.n ================================================================== --- embedded/man/files/modules/log/log.n +++ embedded/man/files/modules/log/log.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -299,15 +298,12 @@ operation and state. .PP To use the package just execute .PP .CS - - - package require log - log::log notice "Some message" - +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 @@ -314,16 +310,13 @@ 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 - +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 @@ -330,16 +323,13 @@ 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" - +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 @@ -348,16 +338,13 @@ 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\\"" - +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 @@ -527,7 +514,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2001-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/log/logger.n ================================================================== --- embedded/man/files/modules/log/logger.n +++ embedded/man/files/modules/log/logger.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -331,21 +330,16 @@ 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 - +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 @@ -446,17 +440,14 @@ 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 - +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 @@ -472,19 +463,15 @@ 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 - +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 @@ -528,14 +515,11 @@ \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] - +${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. @@ -545,43 +529,34 @@ 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 - +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 @@ -646,34 +621,30 @@ 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 - } 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 - +# Print caller and current vars in the calling proc +proc log_local_var {txt} { +set caller [info level -1] +set vars [uplevel 1 info vars] +foreach var [lsort $vars] { +if {[uplevel 1 [list array exists $var]] == 1} { +lappend val $var +} else { +lappend val $var [uplevel 1 [list set $var]] +} +} +puts "$txt" +puts "Caller: $caller" +puts "Variables in callers scope:" +foreach {var value} $val { +puts "$var = $value" +} +} +# install as logproc +${log}::logproc debug log_local_var .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 Index: embedded/man/files/modules/log/loggerAppender.n ================================================================== --- embedded/man/files/modules/log/loggerAppender.n +++ embedded/man/files/modules/log/loggerAppender.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -295,7 +294,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2005 Aamer Akhter - .fi Index: embedded/man/files/modules/log/loggerUtils.n ================================================================== --- embedded/man/files/modules/log/loggerUtils.n +++ embedded/man/files/modules/log/loggerUtils.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -333,11 +332,10 @@ \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 @@ -347,18 +345,15 @@ .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 - +% 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 @@ -367,16 +362,13 @@ 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" - +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. @@ -389,7 +381,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2005 Aamer Akhter - .fi Index: embedded/man/files/modules/map/map_geocode_nominatim.n ================================================================== --- embedded/man/files/modules/map/map_geocode_nominatim.n +++ embedded/man/files/modules/map/map_geocode_nominatim.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/map/map_slippy.n ================================================================== --- embedded/man/files/modules/map/map_slippy.n +++ embedded/man/files/modules/map/map_slippy.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -281,14 +280,11 @@ \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] } - +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. Index: embedded/man/files/modules/map/map_slippy_cache.n ================================================================== --- embedded/man/files/modules/map/map_slippy_cache.n +++ embedded/man/files/modules/map/map_slippy_cache.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/map/map_slippy_fetcher.n ================================================================== --- embedded/man/files/modules/map/map_slippy_fetcher.n +++ embedded/man/files/modules/map/map_slippy_fetcher.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/mapproj/mapproj.n ================================================================== --- embedded/man/files/modules/mapproj/mapproj.n +++ embedded/man/files/modules/mapproj/mapproj.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -678,7 +677,6 @@ .SH KEYWORDS geodesy, map, projection .SH COPYRIGHT .nf Copyright (c) 2007 Kevin B. Kenny - .fi Index: embedded/man/files/modules/math/bigfloat.n ================================================================== --- embedded/man/files/modules/math/bigfloat.n +++ embedded/man/files/modules/math/bigfloat.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -357,12 +356,10 @@ 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 @@ -369,11 +366,10 @@ # 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]. @@ -382,16 +378,13 @@ 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, @@ -398,16 +391,13 @@ 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 @@ -416,17 +406,14 @@ 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. @@ -440,18 +427,15 @@ \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 @@ -494,26 +478,21 @@ 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 @@ -603,76 +582,58 @@ 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 @@ -679,16 +640,13 @@ 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. @@ -697,12 +655,10 @@ 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 @@ -715,50 +671,41 @@ # 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] +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) @@ -767,11 +714,10 @@ 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 @@ -783,7 +729,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004-2008, by Stephane Arnold - .fi Index: embedded/man/files/modules/math/bignum.n ================================================================== --- embedded/man/files/modules/math/bignum.n +++ embedded/man/files/modules/math/bignum.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -344,38 +343,31 @@ 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]] - +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, @@ -534,7 +526,6 @@ Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Salvatore Sanfilippo Copyright (c) 2004 Arjen Markus - .fi Index: embedded/man/files/modules/math/calculus.n ================================================================== --- embedded/man/files/modules/math/calculus.n +++ embedded/man/files/modules/math/calculus.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -420,38 +419,29 @@ \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 - +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 - +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) - +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 @@ -500,14 +490,11 @@ .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 - +func(x) = 0 .CE .IP using the method of Newton-Raphson. The procedure takes the following arguments: .RS @@ -572,34 +559,31 @@ 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] - } - } - +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) @@ -610,96 +594,72 @@ .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 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 +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 - +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] - +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 @@ -713,7 +673,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2002,2003,2004 Arjen Markus - .fi Index: embedded/man/files/modules/math/combinatorics.n ================================================================== --- embedded/man/files/modules/math/combinatorics.n +++ embedded/man/files/modules/math/combinatorics.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -266,25 +265,19 @@ \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 - +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) ) - +exp( ln_Gamma( x) ) .CE .IP is computed is expected to be precise to better than nine significant figures. .TP @@ -309,14 +302,11 @@ 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)! - +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 @@ -324,14 +314,11 @@ 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) - +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. Index: embedded/man/files/modules/math/constants.n ================================================================== --- embedded/man/files/modules/math/constants.n +++ embedded/man/files/modules/math/constants.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -269,14 +268,11 @@ The motivation for this package is that quite often, with (mathematical) computations, you need a good approximation to, say, the ratio of degrees to radians. You can, of course, define this like: .CS - - - variable radtodeg [expr {180.0/(4.0*atan(1.0))}] - +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 @@ -287,15 +283,12 @@ 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 - +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 @@ -307,14 +300,11 @@ 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}] - +set value [expr {3.0*$onethird}] .CE .IP give \fIexactly\fR the value you expect (if IEEE arithmetic is available). .PP @@ -342,7 +332,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus - .fi Index: embedded/man/files/modules/math/decimal.n ================================================================== --- embedded/man/files/modules/math/decimal.n +++ embedded/man/files/modules/math/decimal.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -348,36 +347,28 @@ 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. - +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. @@ -519,7 +510,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2011 Mark Alston - .fi Index: embedded/man/files/modules/math/fourier.n ================================================================== --- embedded/man/files/modules/math/fourier.n +++ embedded/man/files/modules/math/fourier.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -291,21 +290,18 @@ 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} - +% 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 Index: embedded/man/files/modules/math/fuzzy.n ================================================================== --- embedded/man/files/modules/math/fuzzy.n +++ embedded/man/files/modules/math/fuzzy.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -329,24 +328,20 @@ 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 Index: embedded/man/files/modules/math/interpolate.n ================================================================== --- embedded/man/files/modules/math/interpolate.n +++ embedded/man/files/modules/math/interpolate.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -411,17 +410,14 @@ 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}} - ... - } - +{ {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 @@ -464,34 +460,26 @@ \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 - +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]" - } - +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 @@ -498,11 +486,10 @@ 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. @@ -516,7 +503,6 @@ Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus Copyright (c) 2004 Kevn B. Kenny - .fi Index: embedded/man/files/modules/math/linalg.n ================================================================== --- embedded/man/files/modules/math/linalg.n +++ embedded/man/files/modules/math/linalg.n @@ -222,11 +222,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -1265,14 +1264,11 @@ 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 - +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. @@ -1370,14 +1366,11 @@ 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 - +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 @@ -1405,36 +1398,29 @@ .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 ... +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 ... +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 @@ -1448,7 +1434,6 @@ .SH COPYRIGHT .nf Copyright (c) 2004-2008 Arjen Markus Copyright (c) 2004 Ed Hume Copyright (c) 2008 Michael Buadin - .fi Index: embedded/man/files/modules/math/machineparameters.n ================================================================== --- embedded/man/files/modules/math/machineparameters.n +++ embedded/man/files/modules/math/machineparameters.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -266,21 +265,15 @@ 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 @@ -293,12 +286,10 @@ 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 @@ -305,66 +296,53 @@ tcl_platform(platform) = unix tcl_platform(tip,268) = 1 tcl_platform(tip,280) = 1 tcl_platform(user) = 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 - +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 - +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 - +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 - +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 @@ -436,7 +414,6 @@ Print machine parameters on standard output. .PP .SH COPYRIGHT .nf Copyright (c) 2008 Michael Baudin - .fi Index: embedded/man/files/modules/math/math.n ================================================================== --- embedded/man/files/modules/math/math.n +++ embedded/man/files/modules/math/math.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/math/math_geometry.n ================================================================== --- embedded/man/files/modules/math/math_geometry.n +++ embedded/man/files/modules/math/math_geometry.n @@ -223,11 +223,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -372,14 +371,11 @@ .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] - +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. @@ -750,7 +746,6 @@ .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 Index: embedded/man/files/modules/math/numtheory.n ================================================================== --- embedded/man/files/modules/math/numtheory.n +++ embedded/man/files/modules/math/numtheory.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -292,7 +291,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2010 Lars Hellström - .fi Index: embedded/man/files/modules/math/optimize.n ================================================================== --- embedded/man/files/modules/math/optimize.n +++ embedded/man/files/modules/math/optimize.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -485,30 +484,27 @@ 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] - } - +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 @@ -515,15 +511,12 @@ .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. @@ -530,43 +523,29 @@ .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 - +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 } } ] - +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 - +x + y >= 1 .CE can be turned into standard form using: .CS - - - -x -y <= -1 - +-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. @@ -583,7 +562,6 @@ Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus Copyright (c) 2004,2005 Kevn B. Kenny - .fi Index: embedded/man/files/modules/math/polynomials.n ================================================================== --- embedded/man/files/modules/math/polynomials.n +++ embedded/man/files/modules/math/polynomials.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -288,22 +287,16 @@ 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 - +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] - +set f [::math::polynomials::polynomial [list $a $b $c $d] .CE .RS .TP list \fIcoeffs\fR Coefficients of the polynomial (in ascending @@ -472,7 +465,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus - .fi Index: embedded/man/files/modules/math/qcomplex.n ================================================================== --- embedded/man/files/modules/math/qcomplex.n +++ embedded/man/files/modules/math/qcomplex.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -301,24 +300,18 @@ 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] - +set z [complex 0 1] +puts "z = [tostring $z]" +puts "z**2 = [* $z $z] .CE would result in: .CS - - - z = i - z**2 = -1 - +z = i +z**2 = -1 .CE .SH "AVAILABLE PROCEDURES" The package implements all or most basic operations and elementary functions. .PP @@ -531,7 +524,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus - .fi Index: embedded/man/files/modules/math/rational_funcs.n ================================================================== --- embedded/man/files/modules/math/rational_funcs.n +++ embedded/man/files/modules/math/rational_funcs.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -283,24 +282,18 @@ .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 - +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]] - +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 @@ -441,7 +434,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2005 Arjen Markus - .fi Index: embedded/man/files/modules/math/roman.n ================================================================== --- embedded/man/files/modules/math/roman.n +++ embedded/man/files/modules/math/roman.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -300,7 +299,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2005 Kenneth Green - .fi Index: embedded/man/files/modules/math/romberg.n ================================================================== --- embedded/man/files/modules/math/romberg.n +++ embedded/man/files/modules/math/romberg.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -487,54 +486,41 @@ 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) }] +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) }]]] +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 ) } +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 @@ -546,7 +532,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Kevin B. Kenny . All rights reserved. Redistribution permitted under the terms of the Open Publication License - .fi Index: embedded/man/files/modules/math/special.n ================================================================== --- embedded/man/files/modules/math/special.n +++ embedded/man/files/modules/math/special.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -341,51 +340,48 @@ .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) +| 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 +| 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 | | | - | | | | +| 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 - | | | | +| 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 - | | | | +| 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 - +| 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. @@ -686,15 +682,12 @@ .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]" - +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" @@ -736,7 +729,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus - .fi Index: embedded/man/files/modules/math/statistics.n ================================================================== --- embedded/man/files/modules/math/statistics.n +++ embedded/man/files/modules/math/statistics.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -898,28 +897,22 @@ \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 - +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) - +( 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 @@ -938,22 +931,16 @@ 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 - +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 - +yi = b0 + b1 * xi1 + b2 * xi2 + ... + bN * xiN + Residual_i .CE .sp The procedure returns a list with the following elements: .RS .IP \(bu @@ -989,40 +976,34 @@ 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}} - +{ 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\\]" +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 @@ -1400,16 +1381,13 @@ .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 - +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) @@ -1725,122 +1703,102 @@ .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 +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] - } - } -} - +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 {} -} - +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 "$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 +\.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 - +\.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 - +\.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. Index: embedded/man/files/modules/math/symdiff.n ================================================================== --- embedded/man/files/modules/math/symdiff.n +++ embedded/man/files/modules/math/symdiff.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -308,18 +307,15 @@ .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}} +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 @@ -330,7 +326,6 @@ math::calculus, math::interpolate .SH COPYRIGHT .nf Copyright (c) 2010 by Kevin B. Kenny Redistribution permitted under the terms of the Open Publication License - .fi Index: embedded/man/files/modules/md4/md4.n ================================================================== --- embedded/man/files/modules/md4/md4.n +++ embedded/man/files/modules/md4/md4.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -335,34 +334,25 @@ \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 - - +% 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) @@ -393,7 +383,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2003, Pat Thoyts - .fi Index: embedded/man/files/modules/md5/md5.n ================================================================== --- embedded/man/files/modules/md5/md5.n +++ embedded/man/files/modules/md5/md5.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -345,34 +344,25 @@ \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 - - +% 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. @@ -399,7 +389,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2003, Pat Thoyts - .fi Index: embedded/man/files/modules/md5crypt/md5crypt.n ================================================================== --- embedded/man/files/modules/md5crypt/md5crypt.n +++ embedded/man/files/modules/md5crypt/md5crypt.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -291,29 +290,20 @@ .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. - +% 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 @@ -327,7 +317,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2003, Pat Thoyts - .fi Index: embedded/man/files/modules/mime/mime.n ================================================================== --- embedded/man/files/modules/mime/mime.n +++ embedded/man/files/modules/mime/mime.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -374,33 +373,24 @@ 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] - +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" - +uplevel #0 $callback "end" .CE .sp Alternatively, if an error occurs, the callback is invoked as: .CS - - - uplevel #0 $callback [list "error" reason] - +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 @@ -563,7 +553,6 @@ .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 1999-2000 Marshall T. Rose - .fi Index: embedded/man/files/modules/mime/smtp.n ================================================================== --- embedded/man/files/modules/mime/smtp.n +++ embedded/man/files/modules/mime/smtp.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -352,27 +351,22 @@ 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." - +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) @@ -402,7 +396,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 1999-2000 Marshall T. Rose and others - .fi Index: embedded/man/files/modules/multiplexer/multiplexer.n ================================================================== --- embedded/man/files/modules/multiplexer/multiplexer.n +++ embedded/man/files/modules/multiplexer/multiplexer.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -277,17 +276,15 @@ .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. Index: embedded/man/files/modules/namespacex/namespacex.n ================================================================== --- embedded/man/files/modules/namespacex/namespacex.n +++ embedded/man/files/modules/namespacex/namespacex.n @@ -222,11 +222,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -320,7 +319,6 @@ .SH COPYRIGHT .nf Copyright (c) 200? Neil Madden (http://wiki.tcl.tk/12790) Copyright (c) 200? Various (http://wiki.tcl.tk/1489) Copyright (c) 2010 Documentation, Andreas Kupries - .fi Index: embedded/man/files/modules/ncgi/ncgi.n ================================================================== --- embedded/man/files/modules/ncgi/ncgi.n +++ embedded/man/files/modules/ncgi/ncgi.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -514,36 +513,28 @@ The second element is the form value. .PP .SH EXAMPLES Uploading a file .CS - - HTML:
Path:
Name:
- TCL: upload.cgi #!/usr/local/bin/tclsh - ::ncgi::parse set filedata [::ncgi::value filedata] set filedesc [::ncgi::value filedesc] - puts " File uploaded at $filedesc " - set filename /www/images/$filedesc - set fh [open $filename w] puts -nonewline $fh $filedata close $fh - .CE .PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems. Index: embedded/man/files/modules/nmea/nmea.n ================================================================== --- embedded/man/files/modules/nmea/nmea.n +++ embedded/man/files/modules/nmea/nmea.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -283,15 +282,12 @@ .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. @@ -344,23 +340,18 @@ 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" -} - +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. @@ -373,7 +364,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2006-2009, Aaron Faupell - .fi Index: embedded/man/files/modules/nns/nns_auto.n ================================================================== --- embedded/man/files/modules/nns/nns_auto.n +++ embedded/man/files/modules/nns/nns_auto.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -335,7 +334,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2007-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/nns/nns_client.n ================================================================== --- embedded/man/files/modules/nns/nns_client.n +++ embedded/man/files/modules/nns/nns_client.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -550,7 +549,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2007-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/nns/nns_common.n ================================================================== --- embedded/man/files/modules/nns/nns_common.n +++ embedded/man/files/modules/nns/nns_common.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -284,7 +283,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2007-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/nns/nns_intro.n ================================================================== --- embedded/man/files/modules/nns/nns_intro.n +++ embedded/man/files/modules/nns/nns_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -331,7 +330,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2008 Andreas Kupries - .fi Index: embedded/man/files/modules/nns/nns_protocol.n ================================================================== --- embedded/man/files/modules/nns/nns_protocol.n +++ embedded/man/files/modules/nns/nns_protocol.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -391,7 +390,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2007-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/nns/nns_server.n ================================================================== --- embedded/man/files/modules/nns/nns_server.n +++ embedded/man/files/modules/nns/nns_server.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -376,7 +375,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2007-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/nntp/nntp.n ================================================================== --- embedded/man/files/modules/nntp/nntp.n +++ embedded/man/files/modules/nntp/nntp.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -393,14 +392,11 @@ .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 - +group last first p .CE .IP where is the name of the newsgroup, is the number of the last known article currently in that newsgroup, is the number of the first article currently in the newsgroup, and

is @@ -425,14 +421,11 @@ 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 - +group last first p .CE .IP where is the name of the newsgroup, is the number of the last known article currently in that newsgroup, is the number of the first article currently in the newsgroup, and

is @@ -483,14 +476,11 @@ 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 @@ -499,14 +489,11 @@ 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 - +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 @@ -526,14 +513,11 @@ \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 - +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 @@ -555,14 +539,11 @@ 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 - +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 @@ -581,25 +562,21 @@ .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" - +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 Index: embedded/man/files/modules/ntp/ntp_time.n ================================================================== --- embedded/man/files/modules/ntp/ntp_time.n +++ embedded/man/files/modules/ntp/ntp_time.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -348,38 +347,29 @@ .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 +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 @@ -395,7 +385,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts - .fi Index: embedded/man/files/modules/ooutil/ooutil.n ================================================================== --- embedded/man/files/modules/ooutil/ooutil.n +++ embedded/man/files/modules/ooutil/ooutil.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -283,24 +282,21 @@ 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" } +classmethod find args { puts "[self] called with arguments: $args" } } oo::class create Table { - superclass ActiveRecord +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 @@ -313,17 +309,15 @@ 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] - } +method bar {z} { +classvariable x y +return [incr x $z],[incr y] +} } ::Foo % Foo create a ::a % Foo create b @@ -336,11 +330,10 @@ 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 @@ -348,22 +341,19 @@ .sp Syntax and results are like for \fBoo::class\fR. .sp Example: .CS - - % oo::class create example { - self mixin singleton - method foo {} {self} +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" @@ -380,7 +370,6 @@ .SH CATEGORY Utility .SH COPYRIGHT .nf Copyright (c) 2011-2013 Andreas Kupries, BSD licensed - .fi Index: embedded/man/files/modules/otp/otp.n ================================================================== --- embedded/man/files/modules/otp/otp.n +++ embedded/man/files/modules/otp/otp.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -279,19 +278,16 @@ .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 @@ -325,7 +321,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2006, Pat Thoyts - .fi Index: embedded/man/files/modules/page/page_intro.n ================================================================== --- embedded/man/files/modules/page/page_intro.n +++ embedded/man/files/modules/page/page_intro.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -269,7 +268,6 @@ .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/page/page_pluginmgr.n ================================================================== --- embedded/man/files/modules/page/page_pluginmgr.n +++ embedded/man/files/modules/page/page_pluginmgr.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -1009,7 +1008,6 @@ .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/page/page_util_flow.n ================================================================== --- embedded/man/files/modules/page/page_util_flow.n +++ embedded/man/files/modules/page/page_util_flow.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -321,7 +320,6 @@ .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/page/page_util_norm_lemon.n ================================================================== --- embedded/man/files/modules/page/page_util_norm_lemon.n +++ embedded/man/files/modules/page/page_util_norm_lemon.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -277,7 +276,6 @@ .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/page/page_util_norm_peg.n ================================================================== --- embedded/man/files/modules/page/page_util_norm_peg.n +++ embedded/man/files/modules/page/page_util_norm_peg.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -326,7 +325,6 @@ .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/page/page_util_peg.n ================================================================== --- embedded/man/files/modules/page/page_util_peg.n +++ embedded/man/files/modules/page/page_util_peg.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -287,19 +286,15 @@ .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. - +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 @@ -348,7 +343,6 @@ .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/page/page_util_quote.n ================================================================== --- embedded/man/files/modules/page/page_util_quote.n +++ embedded/man/files/modules/page/page_util_quote.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -302,7 +301,6 @@ .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries - .fi Index: embedded/man/files/modules/pki/pki.n ================================================================== --- embedded/man/files/modules/pki/pki.n +++ embedded/man/files/modules/pki/pki.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -430,18 +429,12 @@ 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 @@ -460,7 +453,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries - .fi Index: embedded/man/files/modules/pluginmgr/pluginmgr.n ================================================================== --- embedded/man/files/modules/pluginmgr/pluginmgr.n +++ embedded/man/files/modules/pluginmgr/pluginmgr.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -372,30 +371,24 @@ 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 - +::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 @@ -593,7 +586,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries - .fi Index: embedded/man/files/modules/png/png.n ================================================================== --- embedded/man/files/modules/png/png.n +++ embedded/man/files/modules/png/png.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -395,7 +394,6 @@ File formats .SH COPYRIGHT .nf Copyright (c) 2004, Code: Aaron Faupell Copyright (c) 2004, Doc: Andreas Kupries - .fi Index: embedded/man/files/modules/pop3/pop3.n ================================================================== --- embedded/man/files/modules/pop3/pop3.n +++ embedded/man/files/modules/pop3/pop3.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -436,39 +435,29 @@ 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 - - ... - +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 - - ... - +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 Index: embedded/man/files/modules/pop3d/pop3d.n ================================================================== --- embedded/man/files/modules/pop3d/pop3d.n +++ embedded/man/files/modules/pop3d/pop3d.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -458,19 +457,15 @@ 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 - ... - +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 @@ -483,7 +478,6 @@ Networking .SH COPYRIGHT .nf Copyright (c) 2002-2009 Andreas Kupries Copyright (c) 2005 Reinhard Max - .fi Index: embedded/man/files/modules/pop3d/pop3d_dbox.n ================================================================== --- embedded/man/files/modules/pop3d/pop3d_dbox.n +++ embedded/man/files/modules/pop3d/pop3d_dbox.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -402,7 +401,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries - .fi Index: embedded/man/files/modules/pop3d/pop3d_udb.n ================================================================== --- embedded/man/files/modules/pop3d/pop3d_udb.n +++ embedded/man/files/modules/pop3d/pop3d_udb.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -351,7 +350,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries - .fi Index: embedded/man/files/modules/profiler/profiler.n ================================================================== --- embedded/man/files/modules/profiler/profiler.n +++ embedded/man/files/modules/profiler/profiler.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/pt/pt.n ================================================================== --- embedded/man/files/modules/pt/pt.n +++ embedded/man/files/modules/pt/pt.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -315,21 +314,21 @@ 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 +\.PS +\.nf + --- C ---> critcl, c | + --- specialized -+ | | ---+ + --- Tcl -> snit, oo | + --- interpreted (Tcl) ------> container .fi -.PE +\.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 @@ -791,86 +790,70 @@ 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 ; +Digit <- '0'/'1'/'2'/'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 ... - +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} - } - } - } -} - +{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 +120+5 .CE A more graphical representation of the tree would be .PP -.PS -.nf +\.PS +\.nf +- Digit 0 0 | 1 | | +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 | | | | +- Digit 2 2 | 0 @@ -877,11 +860,11 @@ | | Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + | | +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 .fi -.PE +\.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. @@ -914,7 +897,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_astree.n ================================================================== --- embedded/man/files/modules/pt/pt_astree.n +++ embedded/man/files/modules/pt/pt_astree.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -445,59 +444,52 @@ .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 ; +Digit <- '0'/'1'/'2'/'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 +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} - } - } - } -} - +{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 +\.PS +\.nf +- Digit 0 0 | 1 | | +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 | | | | +- Digit 2 2 | 0 @@ -504,11 +496,11 @@ | | Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + | | +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 .fi -.PE +\.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 @@ -520,7 +512,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_cparam_config_critcl.n ================================================================== --- embedded/man/files/modules/pt/pt_cparam_config_critcl.n +++ embedded/man/files/modules/pt/pt_cparam_config_critcl.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -296,7 +295,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_from_api.n ================================================================== --- embedded/man/files/modules/pt/pt_from_api.n +++ embedded/man/files/modules/pt/pt_from_api.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -398,34 +397,24 @@ 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 ... - +# 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 ... - +# 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. @@ -516,44 +505,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -704,23 +687,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -733,7 +710,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_introduction.n ================================================================== --- embedded/man/files/modules/pt/pt_introduction.n +++ embedded/man/files/modules/pt/pt_introduction.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -405,7 +404,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_json_language.n ================================================================== --- embedded/man/files/modules/pt/pt_json_language.n +++ embedded/man/files/modules/pt/pt_json_language.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -332,91 +331,82 @@ 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 ; +Digit <- '0'/'1'/'2'/'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" - } -} - +{ +"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} -} - +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 @@ -509,44 +499,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -697,23 +681,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -726,7 +704,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_param.n ================================================================== --- embedded/man/files/modules/pt/pt_param.n +++ embedded/man/files/modules/pt/pt_param.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -688,12 +687,10 @@ 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 @@ -735,11 +732,10 @@ ======================= ======================= ==================== 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 @@ -751,7 +747,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_parser_api.n ================================================================== --- embedded/man/files/modules/pt/pt_parser_api.n +++ embedded/man/files/modules/pt/pt_parser_api.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -350,36 +349,25 @@ 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 ... - +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 ... - +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. @@ -439,59 +427,52 @@ .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 ; +Digit <- '0'/'1'/'2'/'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 +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} - } - } - } -} - +{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 +\.PS +\.nf +- Digit 0 0 | 1 | | +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 | | | | +- Digit 2 2 | 0 @@ -498,11 +479,11 @@ | | Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + | | +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 .fi -.PE +\.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. @@ -652,23 +633,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -681,7 +656,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_container.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_container.n +++ embedded/man/files/modules/pt/pt_peg_container.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -414,14 +413,11 @@ operator for grammars. .sp This operation is in effect equivalent to .sp .CS - - - \fIobjectName\fR \fBdeserialize =\fR [\fIsource\fR \fBserialize\fR] - +\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 @@ -428,14 +424,11 @@ operator for grammars. .sp This operation is in effect equivalent to .sp .CS - - - \fIdestination\fR \fBdeserialize =\fR [\fIobjectName\fR \fBserialize\fR] - +\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 @@ -697,44 +690,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -885,23 +872,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -914,7 +895,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_container_peg.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_container_peg.n +++ embedded/man/files/modules/pt/pt_peg_container_peg.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -279,7 +278,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_export.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_export.n +++ embedded/man/files/modules/pt/pt_peg_export.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -518,44 +517,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -706,23 +699,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -735,7 +722,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_export_container.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_export_container.n +++ embedded/man/files/modules/pt/pt_peg_export_container.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -371,62 +370,55 @@ 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 ; +Digit <- '0'/'1'/'2'/'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 -} - +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, @@ -518,44 +510,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -706,23 +692,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -735,7 +715,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_export_json.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_export_json.n +++ embedded/man/files/modules/pt/pt_peg_export_json.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -400,91 +399,82 @@ 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 ; +Digit <- '0'/'1'/'2'/'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" - } -} - +{ +"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} -} - +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 @@ -577,44 +567,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -765,23 +749,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -794,7 +772,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_export_peg.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_export_peg.n +++ embedded/man/files/modules/pt/pt_peg_export_peg.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -344,60 +343,49 @@ 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 ; +# -------------------------------------------------------------------- +# 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 ; +# -------------------------------------------------------------------- +# Lexing constructs +Identifier <- Ident WHITESPACE ; leaf: Ident <- ('_' / ':' / ) ('_' / ':' / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - +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 <- '"' ; @@ -415,11 +403,10 @@ leaf: STAR <- "*" WHITESPACE ; leaf: PLUS <- "+" WHITESPACE ; void: OPEN <- "(" WHITESPACE ; void: CLOSE <- ")" WHITESPACE ; leaf: DOT <- "." WHITESPACE ; - leaf: ALNUM <- "" WHITESPACE ; leaf: ALPHA <- "" WHITESPACE ; leaf: ASCII <- "" WHITESPACE ; leaf: CONTROL <- "" WHITESPACE ; leaf: DDIGIT <- "" WHITESPACE ; @@ -430,55 +417,46 @@ leaf: PUNCT <- "" WHITESPACE ; leaf: SPACE <- "" WHITESPACE ; leaf: UPPER <- "" WHITESPACE ; leaf: WORDCHAR <- "" WHITESPACE ; leaf: XDIGIT <- "" WHITESPACE ; - void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; void: COMMENT <- '#' (!EOL .)* EOL ; void: EOL <- "\\n\\r" / "\\n" / "\\r" ; void: EOF <- !. ; - - # -------------------------------------------------------------------- +# -------------------------------------------------------------------- END; - .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 ; +Digit <- '0'/'1'/'2'/'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? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; +Sign <- [-+] ; +Number <- Sign? + ; +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, @@ -570,44 +548,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -758,23 +730,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -787,7 +753,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_from_container.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_from_container.n +++ embedded/man/files/modules/pt/pt_peg_from_container.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -273,7 +272,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_from_json.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_from_json.n +++ embedded/man/files/modules/pt/pt_peg_from_json.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -366,91 +365,82 @@ 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 ; +Digit <- '0'/'1'/'2'/'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" - } -} - +{ +"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} -} - +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 @@ -543,44 +533,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -731,23 +715,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -760,7 +738,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_from_peg.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_from_peg.n +++ embedded/man/files/modules/pt/pt_peg_from_peg.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -294,60 +293,49 @@ 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 ; +# -------------------------------------------------------------------- +# 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 ; +# -------------------------------------------------------------------- +# Lexing constructs +Identifier <- Ident WHITESPACE ; leaf: Ident <- ('_' / ':' / ) ('_' / ':' / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - +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 <- '"' ; @@ -365,11 +353,10 @@ leaf: STAR <- "*" WHITESPACE ; leaf: PLUS <- "+" WHITESPACE ; void: OPEN <- "(" WHITESPACE ; void: CLOSE <- ")" WHITESPACE ; leaf: DOT <- "." WHITESPACE ; - leaf: ALNUM <- "" WHITESPACE ; leaf: ALPHA <- "" WHITESPACE ; leaf: ASCII <- "" WHITESPACE ; leaf: CONTROL <- "" WHITESPACE ; leaf: DDIGIT <- "" WHITESPACE ; @@ -380,55 +367,46 @@ leaf: PUNCT <- "" WHITESPACE ; leaf: SPACE <- "" WHITESPACE ; leaf: UPPER <- "" WHITESPACE ; leaf: WORDCHAR <- "" WHITESPACE ; leaf: XDIGIT <- "" WHITESPACE ; - void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; void: COMMENT <- '#' (!EOL .)* EOL ; void: EOL <- "\\n\\r" / "\\n" / "\\r" ; void: EOF <- !. ; - - # -------------------------------------------------------------------- +# -------------------------------------------------------------------- END; - .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 ; +Digit <- '0'/'1'/'2'/'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? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; +Sign <- [-+] ; +Number <- Sign? + ; +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, @@ -520,44 +498,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -708,23 +680,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -737,7 +703,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_import.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_import.n +++ embedded/man/files/modules/pt/pt_peg_import.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -538,44 +537,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -726,23 +719,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -755,7 +742,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_import_container.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_import_container.n +++ embedded/man/files/modules/pt/pt_peg_import_container.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -273,7 +272,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_import_json.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_import_json.n +++ embedded/man/files/modules/pt/pt_peg_import_json.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -375,91 +374,82 @@ 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 ; +Digit <- '0'/'1'/'2'/'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" - } -} - +{ +"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} -} - +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 @@ -552,44 +542,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -740,23 +724,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -769,7 +747,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_import_peg.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_import_peg.n +++ embedded/man/files/modules/pt/pt_peg_import_peg.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -307,60 +306,49 @@ 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 ; +# -------------------------------------------------------------------- +# 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 ; +# -------------------------------------------------------------------- +# Lexing constructs +Identifier <- Ident WHITESPACE ; leaf: Ident <- ('_' / ':' / ) ('_' / ':' / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - +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 <- '"' ; @@ -378,11 +366,10 @@ leaf: STAR <- "*" WHITESPACE ; leaf: PLUS <- "+" WHITESPACE ; void: OPEN <- "(" WHITESPACE ; void: CLOSE <- ")" WHITESPACE ; leaf: DOT <- "." WHITESPACE ; - leaf: ALNUM <- "" WHITESPACE ; leaf: ALPHA <- "" WHITESPACE ; leaf: ASCII <- "" WHITESPACE ; leaf: CONTROL <- "" WHITESPACE ; leaf: DDIGIT <- "" WHITESPACE ; @@ -393,55 +380,46 @@ leaf: PUNCT <- "" WHITESPACE ; leaf: SPACE <- "" WHITESPACE ; leaf: UPPER <- "" WHITESPACE ; leaf: WORDCHAR <- "" WHITESPACE ; leaf: XDIGIT <- "" WHITESPACE ; - void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; void: COMMENT <- '#' (!EOL .)* EOL ; void: EOL <- "\\n\\r" / "\\n" / "\\r" ; void: EOF <- !. ; - - # -------------------------------------------------------------------- +# -------------------------------------------------------------------- END; - .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 ; +Digit <- '0'/'1'/'2'/'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? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; +Sign <- [-+] ; +Number <- Sign? + ; +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, @@ -533,44 +511,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -721,23 +693,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -750,7 +716,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_interp.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_interp.n +++ embedded/man/files/modules/pt/pt_peg_interp.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -431,59 +430,52 @@ .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 ; +Digit <- '0'/'1'/'2'/'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 +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} - } - } - } -} - +{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 +\.PS +\.nf +- Digit 0 0 | 1 | | +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 | | | | +- Digit 2 2 | 0 @@ -490,11 +482,11 @@ | | Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + | | +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 .fi -.PE +\.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. @@ -644,23 +636,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -673,7 +659,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_introduction.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_introduction.n +++ embedded/man/files/modules/pt/pt_peg_introduction.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -403,7 +402,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_language.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_language.n +++ embedded/man/files/modules/pt/pt_peg_language.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -268,16 +267,13 @@ not lend themselves too. .SH "THE ELEMENTS OF THE LANGUAGE" .SS "BASIC STRUCTURE" The general outline of a textual PEG is .CS - - PEG <> (<>) - <> +<> 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 @@ -291,43 +287,31 @@ .IP [2] zero or more letters, digits, underscores, or colons. .PP Or, in formal textual notation: .CS - - - ([_:] / ) ([_:] / )* - +([_:] / ) ([_:] / )* .CE Examples of names: .CS - - - Hello - ::world - _:submarine55_ - +Hello +::world +_:submarine55_ .CE Examples of text which are \fInot\fR names: .CS - - - 12 - .bogus - 0wrong - @location - +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 - - - <> <- <> ; - +<> <- <> ; .CE The specifies the nonterminal symbol to be defined, the after the arrow (<-) then declares its structure. .PP Note that each rule ends in a single semicolon, even the last. @@ -350,63 +334,45 @@ 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. - - <> <> # sequence. parse 1, then 2. - <> / <> # alternative. try to parse 1, and parse 2 if 1 failed to parse. - - # Prefix operators. Lookahead constraints. Same priority. - - & <> # Parse expression, ok on successful parse. - ! <> # Ditto, except ok on failure to parse. - - # Suffix operators. Repetition. Same priority. - - <> ? # Parse expression none, or once (repeat 0 or 1). - <> * # Parse expression zero or more times. - <> + # Parse expression one or more times. - - # Expression nesting - - ( <> ) # Put an expression in parens to change its priority. - +# Binary operators. +<> <> # sequence. parse 1, then 2. +<> / <> # alternative. try to parse 1, and parse 2 if 1 failed to parse. +# Prefix operators. Lookahead constraints. Same priority. +& <> # Parse expression, ok on successful parse. +! <> # Ditto, except ok on failure to parse. +# Suffix operators. Repetition. Same priority. +<> ? # Parse expression none, or once (repeat 0 or 1). +<> * # Parse expression zero or more times. +<> + # Parse expression one or more times. +# Expression nesting +( <> ) # Put an expression in parens to change its priority. .CE With this we can now deconstruct the formal expression for names given in section \fBNames\fR: .CS - - - ([_:] / ) ([_:] / )* - +([_:] / ) ([_:] / )* .CE It is a sequence of two parts, .CS - - [_:] / +[_:] / .CE and .CS - - ([_:] / )* +([_:] / )* .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 - - - [_:] - - - +[_:] + + .CE And \fIatomic expressions\fR are our next topic. They fall into three classes: .IP [1] names, i.e. nonterminal symbols, @@ -421,69 +387,54 @@ 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" - "'" - '"' - +\'' +"" +\'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 - - - # Any unicode alphabet or digit character (string is alnum). - # Any unicode alphabet character (string is alpha). - # Any unicode character below codepoint 0x80 (string is ascii). - # Any unicode control character (string is control). - # The digit characters [0-9]. - # Any unicode digit character (string is digit). - # Any unicode printing character, except space (string is graph). - # Any unicode lower-case alphabet character (string is lower). - # Any unicode printing character, incl. space (string is print). - # Any unicode punctuation character (string is punct). - # Any unicode space character (string is space). - # Any unicode upper-case alphabet character (string is upper). - # Any unicode word character (string is wordchar). - # The hexadecimal digit characters [0-9a-fA-F]. - . # Any character, except end of input. - + # Any unicode alphabet or digit character (string is alnum). + # Any unicode alphabet character (string is alpha). + # Any unicode character below codepoint 0x80 (string is ascii). + # Any unicode control character (string is control). + # The digit characters [0-9]. + # Any unicode digit character (string is digit). + # Any unicode printing character, except space (string is graph). + # Any unicode lower-case alphabet character (string is lower). + # Any unicode printing character, incl. space (string is print). + # Any unicode punctuation character (string is punct). + # Any unicode space character (string is space). + # Any unicode upper-case alphabet character (string is upper). + # Any unicode word character (string is wordchar). + # The hexadecimal digit characters [0-9a-fA-F]. +\. # Any character, except end of input. .CE And the syntax of custom-defined character classes is .CS - - - [ <>* ] - +[ <>* ] .CE where each range is either a single character, or of the form .CS - - - <> - > - +<> - > .CE Examples for character classes we have seen already in the course of this introduction are .CS - - - [_:] - [0-9] - [0-9a-fA-F] - +[_:] +[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 @@ -495,17 +446,14 @@ All the escaped forms are started with a backslash character ('\\', unicode codepoint 0x5C). This is then followed by a series of octal digits, or 'u' and hexedecimal digits, or a regular character from a fixed set for various control characters. Some examples: .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 - +\\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 @@ -519,23 +467,17 @@ etc. .SS "NONTERMINAL ATTRIBUTES" Lastly, a more advanced topic. In the section \fBRules\fR we gave the structure of a rule as .CS - - - <> <- <> ; - +<> <- <> ; .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 - - - <> : <> <- <> ; - +<> : <> <- <> ; .CE is also allowed. This mode is optional. The known modes and their meanings are: .TP \fBvalue\fR @@ -571,60 +513,49 @@ 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 ; +# -------------------------------------------------------------------- +# 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 ; +# -------------------------------------------------------------------- +# Lexing constructs +Identifier <- Ident WHITESPACE ; leaf: Ident <- ('_' / ':' / ) ('_' / ':' / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - +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 <- '"' ; @@ -642,11 +573,10 @@ leaf: STAR <- "*" WHITESPACE ; leaf: PLUS <- "+" WHITESPACE ; void: OPEN <- "(" WHITESPACE ; void: CLOSE <- ")" WHITESPACE ; leaf: DOT <- "." WHITESPACE ; - leaf: ALNUM <- "" WHITESPACE ; leaf: ALPHA <- "" WHITESPACE ; leaf: ASCII <- "" WHITESPACE ; leaf: CONTROL <- "" WHITESPACE ; leaf: DDIGIT <- "" WHITESPACE ; @@ -657,55 +587,46 @@ leaf: PUNCT <- "" WHITESPACE ; leaf: SPACE <- "" WHITESPACE ; leaf: UPPER <- "" WHITESPACE ; leaf: WORDCHAR <- "" WHITESPACE ; leaf: XDIGIT <- "" WHITESPACE ; - void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; void: COMMENT <- '#' (!EOL .)* EOL ; void: EOL <- "\\n\\r" / "\\n" / "\\r" ; void: EOF <- !. ; - - # -------------------------------------------------------------------- +# -------------------------------------------------------------------- END; - .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 ; +Digit <- '0'/'1'/'2'/'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? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; +Sign <- [-+] ; +Number <- Sign? + ; +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. @@ -718,7 +639,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_to_container.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_to_container.n +++ embedded/man/files/modules/pt/pt_peg_to_container.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -394,62 +393,55 @@ 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 ; +Digit <- '0'/'1'/'2'/'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 -} - +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, @@ -541,44 +533,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -729,23 +715,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -758,7 +738,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_to_cparam.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_to_cparam.n +++ embedded/man/files/modules/pt/pt_peg_to_cparam.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -561,44 +560,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -749,23 +742,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -778,7 +765,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_to_json.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_to_json.n +++ embedded/man/files/modules/pt/pt_peg_to_json.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -428,91 +427,82 @@ 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 ; +Digit <- '0'/'1'/'2'/'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" - } -} - +{ +"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} -} - +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 @@ -605,44 +595,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -793,23 +777,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -822,7 +800,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_to_param.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_to_param.n +++ embedded/man/files/modules/pt/pt_peg_to_param.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -367,104 +366,80 @@ 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 ; +Digit <- '0'/'1'/'2'/'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 # - <

>: - call sym_Expression - halt - +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 - +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 - +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 - +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 +loc_pop_discard +return # # value Symbol 'Digit' # - sym_Digit: # / # '0' # '1' # '2' @@ -473,27 +448,22 @@ # '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 - +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 - +ok! ast_value_push +return choice_20: # / # '0' # '1' # '2' @@ -502,123 +472,89 @@ # '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 - +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 +loc_pop_discard +return # # value Symbol 'Expression' # - sym_Expression: # / # x # '\\(' # (Expression) @@ -627,29 +563,24 @@ # (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 - +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 - +ok! ast_value_push +return choice_44: # / # x # '\\(' # (Expression) @@ -658,496 +589,371 @@ # (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 - +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 - +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 - +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 - +ast_pop_rewind failednoast_29: - loc_pop_rewind - return - +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 - +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 - +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 - +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 - +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 - +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 +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 - +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 - +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 - +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 - +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 - +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 - +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 - +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 +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 - +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 - +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 - +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 +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 - +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 - +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 - +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 - +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 - +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 - +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 - +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 +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 - +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 +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 - -# -# - +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, @@ -1239,44 +1045,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -1427,23 +1227,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -1456,7 +1250,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_to_peg.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_to_peg.n +++ embedded/man/files/modules/pt/pt_peg_to_peg.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -366,60 +365,49 @@ 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 ; +# -------------------------------------------------------------------- +# 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 ; +# -------------------------------------------------------------------- +# Lexing constructs +Identifier <- Ident WHITESPACE ; leaf: Ident <- ('_' / ':' / ) ('_' / ':' / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - +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 <- '"' ; @@ -437,11 +425,10 @@ leaf: STAR <- "*" WHITESPACE ; leaf: PLUS <- "+" WHITESPACE ; void: OPEN <- "(" WHITESPACE ; void: CLOSE <- ")" WHITESPACE ; leaf: DOT <- "." WHITESPACE ; - leaf: ALNUM <- "" WHITESPACE ; leaf: ALPHA <- "" WHITESPACE ; leaf: ASCII <- "" WHITESPACE ; leaf: CONTROL <- "" WHITESPACE ; leaf: DDIGIT <- "" WHITESPACE ; @@ -452,55 +439,46 @@ leaf: PUNCT <- "" WHITESPACE ; leaf: SPACE <- "" WHITESPACE ; leaf: UPPER <- "" WHITESPACE ; leaf: WORDCHAR <- "" WHITESPACE ; leaf: XDIGIT <- "" WHITESPACE ; - void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; void: COMMENT <- '#' (!EOL .)* EOL ; void: EOL <- "\\n\\r" / "\\n" / "\\r" ; void: EOF <- !. ; - - # -------------------------------------------------------------------- +# -------------------------------------------------------------------- END; - .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 ; +Digit <- '0'/'1'/'2'/'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? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; +Sign <- [-+] ; +Number <- Sign? + ; +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, @@ -592,44 +570,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -780,23 +752,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -809,7 +775,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_peg_to_tclparam.n ================================================================== --- embedded/man/files/modules/pt/pt_peg_to_tclparam.n +++ embedded/man/files/modules/pt/pt_peg_to_tclparam.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -545,44 +544,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -733,23 +726,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -762,7 +749,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_pegrammar.n ================================================================== --- embedded/man/files/modules/pt/pt_pegrammar.n +++ embedded/man/files/modules/pt/pt_pegrammar.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -455,44 +454,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -643,23 +636,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -672,7 +659,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_pexpr_op.n ================================================================== --- embedded/man/files/modules/pt/pt_pexpr_op.n +++ embedded/man/files/modules/pt/pt_pexpr_op.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -474,23 +473,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -503,7 +496,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_pexpression.n ================================================================== --- embedded/man/files/modules/pt/pt_pexpression.n +++ embedded/man/files/modules/pt/pt_pexpression.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -669,23 +668,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -698,7 +691,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_pgen.n ================================================================== --- embedded/man/files/modules/pt/pt_pgen.n +++ embedded/man/files/modules/pt/pt_pgen.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -335,99 +334,81 @@ 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 ; +Digit <- '0'/'1'/'2'/'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 +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 ... - +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} - } - } - } -} - +{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 +120+5 .CE A more graphical representation of the tree would be .PP -.PS -.nf +\.PS +\.nf +- Digit 0 0 | 1 | | +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 | | | | +- Digit 2 2 | 0 @@ -434,11 +415,11 @@ | | Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + | | +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 .fi -.PE +\.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. @@ -464,7 +445,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_rdengine.n ================================================================== --- embedded/man/files/modules/pt/pt_rdengine.n +++ embedded/man/files/modules/pt/pt_rdengine.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -807,405 +806,324 @@ .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 @@ -1238,15 +1156,12 @@ \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 @@ -1263,7 +1178,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_tclparam_config_snit.n ================================================================== --- embedded/man/files/modules/pt/pt_tclparam_config_snit.n +++ embedded/man/files/modules/pt/pt_tclparam_config_snit.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -296,7 +295,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_tclparam_config_tcloo.n ================================================================== --- embedded/man/files/modules/pt/pt_tclparam_config_tcloo.n +++ embedded/man/files/modules/pt/pt_tclparam_config_tcloo.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -296,7 +295,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/pt/pt_to_api.n ================================================================== --- embedded/man/files/modules/pt/pt_to_api.n +++ embedded/man/files/modules/pt/pt_to_api.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -408,40 +407,28 @@ 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 ... - +# 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 ... - +# 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. @@ -532,44 +519,38 @@ .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 ; +Digit <- '0'/'1'/'2'/'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} -} - +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, @@ -720,23 +701,17 @@ .SS EXAMPLE Assuming the parsing expression shown on the right-hand side of the rule .PP .CS - - - Expression <- Term (AddOp Term)* - +Expression <- Term (AddOp Term)* .CE .PP then its canonical serialization (except for whitespace) is .PP .CS - - - {x {n Term} {* {x {n AddOp} {n Term}}}} - +{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. @@ -749,7 +724,6 @@ .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/rc4/rc4.n ================================================================== --- embedded/man/files/modules/rc4/rc4.n +++ embedded/man/files/modules/rc4/rc4.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -303,36 +302,27 @@ 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 +.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 @@ -348,7 +338,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2003, Pat Thoyts - .fi Index: embedded/man/files/modules/rcs/rcs.n ================================================================== --- embedded/man/files/modules/rcs/rcs.n +++ embedded/man/files/modules/rcs/rcs.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -355,34 +354,30 @@ 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 @@ -450,16 +445,14 @@ 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 @@ -490,13 +483,11 @@ .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" @@ -514,7 +505,6 @@ Text processing .SH COPYRIGHT .nf Copyright (c) 2005, Andreas Kupries Copyright (c) 2005, Colin McCormack - .fi Index: embedded/man/files/modules/report/report.n ================================================================== --- embedded/man/files/modules/report/report.n +++ embedded/man/files/modules/report/report.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -595,62 +594,53 @@ .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 - } - +::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 - } - +::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 - +% ::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 @@ -662,7 +652,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries - .fi Index: embedded/man/files/modules/rest/rest.n ================================================================== --- embedded/man/files/modules/rest/rest.n +++ embedded/man/files/modules/rest/rest.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -299,28 +298,22 @@ .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] - +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 - } - ] - +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 @@ -329,24 +322,18 @@ 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] - +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 @@ -379,30 +366,24 @@ 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 } +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 +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 @@ -421,38 +402,28 @@ 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 - +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 -} - +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 Index: embedded/man/files/modules/ripemd/ripemd128.n ================================================================== --- embedded/man/files/modules/ripemd/ripemd128.n +++ embedded/man/files/modules/ripemd/ripemd128.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -344,34 +343,25 @@ \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 - - +% 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" @@ -409,7 +399,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2004, Pat Thoyts - .fi Index: embedded/man/files/modules/ripemd/ripemd160.n ================================================================== --- embedded/man/files/modules/ripemd/ripemd160.n +++ embedded/man/files/modules/ripemd/ripemd160.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -335,34 +334,25 @@ \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 - - +% 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" @@ -396,7 +386,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2004, Pat Thoyts - .fi Index: embedded/man/files/modules/sasl/sasl.n ================================================================== --- embedded/man/files/modules/sasl/sasl.n +++ embedded/man/files/modules/sasl/sasl.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -464,35 +463,31 @@ 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 } - } -} - +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 -} - +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. @@ -533,7 +528,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2005-2006, Pat Thoyts - .fi Index: embedded/man/files/modules/sha1/sha1.n ================================================================== --- embedded/man/files/modules/sha1/sha1.n +++ embedded/man/files/modules/sha1/sha1.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -347,34 +346,25 @@ \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 - - +% 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. @@ -401,7 +391,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2005, Pat Thoyts - .fi Index: embedded/man/files/modules/sha1/sha256.n ================================================================== --- embedded/man/files/modules/sha1/sha256.n +++ embedded/man/files/modules/sha1/sha256.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -360,34 +359,25 @@ \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 - - +% 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. @@ -414,7 +404,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2008, Andreas Kupries - .fi Index: embedded/man/files/modules/simulation/annealing.n ================================================================== --- embedded/man/files/modules/simulation/annealing.n +++ embedded/man/files/modules/simulation/annealing.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -278,23 +277,17 @@ .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)}] - +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 @@ -403,20 +396,17 @@ 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 - } - }] - +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 @@ -428,40 +418,34 @@ 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 -} - +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]}] +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 @@ -474,7 +458,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2008 Arjen Markus - .fi Index: embedded/man/files/modules/simulation/montecarlo.n ================================================================== --- embedded/man/files/modules/simulation/montecarlo.n +++ embedded/man/files/modules/simulation/montecarlo.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -289,41 +288,36 @@ 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] +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] +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]" - +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. @@ -456,7 +450,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2008 Arjen Markus - .fi Index: embedded/man/files/modules/simulation/simulation_random.n ================================================================== --- embedded/man/files/modules/simulation/simulation_random.n +++ embedded/man/files/modules/simulation/simulation_random.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,14 +285,11 @@ .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] - +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 @@ -386,14 +382,11 @@ \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))) - +P(v) = exp( -exp(f*(v-min))) .CE .RS .TP float \fImin\fR Minimum number that will be generated @@ -478,7 +471,6 @@ .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus - .fi Index: embedded/man/files/modules/smtpd/smtpd.n ================================================================== --- embedded/man/files/modules/smtpd/smtpd.n +++ embedded/man/files/modules/smtpd/smtpd.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -290,14 +289,11 @@ 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] - +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 @@ -371,28 +367,22 @@ 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!" - } - } - +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. - +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. @@ -402,20 +392,17 @@ 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 - } - +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 @@ -431,37 +418,31 @@ 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 - } - +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" - } - +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 @@ -490,7 +471,6 @@ .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) Pat Thoyts - .fi Index: embedded/man/files/modules/snit/snit.n ================================================================== --- embedded/man/files/modules/snit/snit.n +++ embedded/man/files/modules/snit/snit.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -492,21 +491,17 @@ 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" } - +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!" - +$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. @@ -519,14 +514,12 @@ 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!" - +$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 @@ -577,40 +570,34 @@ 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} {} { ... } - +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!" - +$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"} +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. @@ -623,14 +610,12 @@ 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!" - +$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? @@ -643,25 +628,21 @@ 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} - +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} - +option -font {Courier 12} .CE .IP See \fBThe Tk Option Database\fR for more information about resource and class names. .sp @@ -668,13 +649,11 @@ 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) - +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. @@ -698,21 +677,17 @@ 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 - +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} - +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 @@ -734,16 +709,14 @@ .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) - } - +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 @@ -757,16 +730,14 @@ .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 - } - +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 @@ -780,18 +751,16 @@ .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." - } - } - +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 @@ -809,26 +778,22 @@ 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 - } - +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 {} {} - +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 @@ -877,34 +842,28 @@ 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 - +delegate method wag to tail .CE .IP is roughly equivalent to this explicitly defined method: .CS - - method wag {args} { - uplevel $tail wag $args - } - +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" - +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 @@ -920,14 +879,12 @@ 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" - +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 @@ -977,13 +934,11 @@ \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 - +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 @@ -1000,19 +955,16 @@ 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] - } - +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 @@ -1036,60 +988,50 @@ 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 - +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 - +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 - +delegate typemethod lostdogs to pound .CE .IP is roughly equivalent to this explicitly defined method: .CS - - typemethod lostdogs {args} { - uplevel $pound lostdogs $args - } - +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" - +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 @@ -1102,14 +1044,12 @@ 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" - +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 @@ -1156,13 +1096,11 @@ 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 - +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 @@ -1175,27 +1113,23 @@ 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 - +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 - +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 @@ -1279,50 +1213,42 @@ \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 - } - +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 - } - +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 - } - +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 - } - +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 @@ -1450,17 +1376,14 @@ 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 @@ -1701,15 +1624,12 @@ 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] - +$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 @@ -1719,15 +1639,12 @@ 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] - +$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. @@ -1738,15 +1655,12 @@ 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] - +$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 @@ -1778,15 +1692,12 @@ \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...] - +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. @@ -1880,53 +1791,44 @@ \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."} - } - +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 - } - } - +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 @@ -1936,20 +1838,17 @@ 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 - } - } - +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 @@ -1958,23 +1857,18 @@ .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!" } - } - +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, @@ -2037,12 +1931,11 @@ 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 { ... } +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. @@ -2071,16 +1964,14 @@ 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 - +-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 @@ -2089,18 +1980,16 @@ 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 - # ... - } - +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 @@ -2108,15 +1997,13 @@ \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 - +-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 @@ -2125,18 +2012,16 @@ 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 - # ... - } - +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 @@ -2143,20 +2028,18 @@ \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 - # ... - } - +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 @@ -2170,20 +2053,16 @@ 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 - +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 @@ -2194,30 +2073,25 @@ 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] - +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 @@ -2252,30 +2126,26 @@ 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 - # - } - #... - } - +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] - +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 @@ -2293,35 +2163,29 @@ 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] - } - } - +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 - } - } - +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 @@ -2357,49 +2221,39 @@ 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 - } - } - +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" - } - +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 - } - +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 @@ -2407,17 +2261,14 @@ 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 - } - +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 @@ -2428,14 +2279,12 @@ 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!) - +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 @@ -2443,40 +2292,32 @@ 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 - +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 - +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 - } - +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 @@ -2577,34 +2418,27 @@ 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} - +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} - } - +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} - } - +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 @@ -2679,90 +2513,70 @@ 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 - } - +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 - } - } - +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 @@ -2843,7 +2657,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2003-2009, by William H. Duquette - .fi Index: embedded/man/files/modules/snit/snitfaq.n ================================================================== --- embedded/man/files/modules/snit/snitfaq.n +++ embedded/man/files/modules/snit/snitfaq.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -357,30 +356,24 @@ 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?" @@ -397,15 +390,13 @@ .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 @@ -418,11 +409,10 @@ .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. @@ -431,26 +421,21 @@ 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 @@ -516,11 +501,10 @@ .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 @@ -561,15 +545,13 @@ 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!" - +# 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 @@ -589,17 +571,15 @@ 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 @@ -620,19 +600,17 @@ 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 @@ -639,103 +617,90 @@ 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." } +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 @@ -761,25 +726,19 @@ 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] - +\.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] - +\.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. @@ -809,11 +768,10 @@ 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 @@ -820,17 +778,15 @@ ::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 @@ -839,11 +795,10 @@ % 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 @@ -853,23 +808,20 @@ 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." - } +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, @@ -880,19 +832,17 @@ .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 @@ -900,29 +850,26 @@ .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]" - } +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, @@ -939,33 +886,28 @@ 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} {...} +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 % .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 @@ -977,28 +919,25 @@ 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]" - } +# 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 @@ -1013,23 +952,21 @@ .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 - } +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. @@ -1038,15 +975,14 @@ 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 - } +method myself {} { +return $self +} } ::thing % thing mutt ::mutt % mutt myself @@ -1053,11 +989,10 @@ ::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 @@ -1064,15 +999,14 @@ \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 - } +method myNameSpace {} { +return $selfns +} } ::thing % thing jeff ::jeff % jeff myNameSpace @@ -1079,11 +1013,10 @@ ::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. @@ -1110,33 +1043,29 @@ 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] - +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] - #... - } +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; @@ -1151,21 +1080,19 @@ 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] - #... - } +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 @@ -1188,33 +1115,29 @@ 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!" +# 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!" - } +# 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 @@ -1256,31 +1179,24 @@ .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 - } -} - +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?" @@ -1295,23 +1211,18 @@ 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] - - # ... - } -} - +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. @@ -1332,18 +1243,16 @@ 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 +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 @@ -1352,18 +1261,16 @@ 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 +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 @@ -1374,17 +1281,15 @@ 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 @@ -1393,83 +1298,73 @@ 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 - } +option -weight 10 +method gainWeight {} { +set wt [$self cget -weight] +incr wt +$self configure -weight $wt +} } ::dog % dog fido ::fido % fido cget -weight @@ -1476,25 +1371,21 @@ 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) - } - +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 @@ -1513,23 +1404,21 @@ 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 +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?" @@ -1540,19 +1429,16 @@ .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) - } +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?" @@ -1566,19 +1452,16 @@ .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 - } +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 @@ -1596,27 +1479,24 @@ 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\\"" - } - } +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 @@ -1631,17 +1511,14 @@ 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!" +# 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?" @@ -1648,19 +1525,17 @@ 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!" - } +# 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 @@ -1690,23 +1565,18 @@ 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] - - # ... - } -} - +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. @@ -1715,17 +1585,14 @@ 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 +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 @@ -1734,20 +1601,17 @@ .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 - } -} - +# 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. @@ -1760,29 +1624,22 @@ 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 - } - - # ... -} - +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. @@ -1810,20 +1667,16 @@ .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] { ... } - } -} - +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 @@ -1830,15 +1683,12 @@ 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?" @@ -1853,19 +1703,16 @@ .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} { ... } - - # ... +# 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. @@ -1878,24 +1725,20 @@ 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] - } -} - +# 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. @@ -1912,19 +1755,16 @@ 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...} - } +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 @@ -1943,52 +1783,44 @@ 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 - } +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 - } +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 @@ -1999,30 +1831,25 @@ Yes, you can. For example, suppose we wanted to be sure that the breed was explicitly stated for every dog at creation time, and couldn't be changed thereafter. One way to do that is as follows: .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 } +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 @@ -2050,37 +1877,29 @@ .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 - } -} - +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?" @@ -2111,25 +1930,20 @@ 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} - } -} - +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 @@ -2149,25 +1963,21 @@ .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 - } -} - +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 @@ -2201,48 +2011,38 @@ 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 - } - } - +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 @@ -2250,21 +2050,18 @@ .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 - } -} - +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 @@ -2290,21 +2087,17 @@ 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 - } +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 @@ -2319,24 +2112,18 @@ 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% - +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 - +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 @@ -2369,22 +2156,18 @@ 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 .... - } +component listbox -public listbox +constructor {args} { +install listbox using listbox $win.listbox .... } - +} combobox .mycombo -.mycombo listbox configure -width 30 - +\.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. @@ -2409,19 +2192,15 @@ 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 - - # ... +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 @@ -2429,21 +2208,17 @@ 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%] - } +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 @@ -2453,36 +2228,27 @@ 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 - } - -} - +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 @@ -2499,28 +2265,25 @@ .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% - } +delegate method wag to mytail +constructor {} { +install mytail using tail %AUTO% +} } ::dog % snit::type tail { - method wag {} { return "Wag, wag, wag."} +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. @@ -2537,20 +2300,17 @@ 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 - } -} - +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 @@ -2557,23 +2317,20 @@ \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} - # ... +delegate method wagtail to mytail as {wag 3} +# ... } - snit::type tail { - method wag {count} { - return [string repeat "Wag " $count] - } - # ... +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 @@ -2589,15 +2346,13 @@ 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} +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 @@ -2627,30 +2382,27 @@ 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 - } +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 +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 @@ -2666,20 +2418,17 @@ 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 - } -} - +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, @@ -2692,27 +2441,22 @@ 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" - } -} - +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 @@ -2733,25 +2477,20 @@ 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 - } - - # ... -} - +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 @@ -2759,45 +2498,35 @@ 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"} +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 - } - - # ... -} - +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 - - # ... +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 @@ -2853,17 +2582,14 @@ \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 - - # ... +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 @@ -2873,19 +2599,15 @@ \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 - - # ... +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 @@ -2900,25 +2622,19 @@ 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 - - } -} - +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" @@ -2944,37 +2660,30 @@ 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 -} - +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 @@ -3000,20 +2709,17 @@ 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 - - # ... - } -} - +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 @@ -3083,28 +2789,23 @@ 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 - - # ... +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 @@ -3135,16 +2836,14 @@ 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 - +-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?" @@ -3153,28 +2852,24 @@ 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 - # ... - } - - # ... +delegate option * to text +constructor {args} { +install text using text .text +# ... +} +# ... } ::mytext % mytext .text -.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. @@ -3182,73 +2877,61 @@ 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 - # ... - } - - # ... +option -myvalue 5 +delegate option -padx to text +delegate option * to text +constructor {args} { +install text using text .text +# ... +} +# ... } ::mytext % mytext .text -.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 - - # ... +delegate option {-padx padX Pad} to text +# ... } ::mytext % mytext .text -.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 - # ... +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 @@ -3261,30 +2944,25 @@ 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 - +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 @@ -3318,42 +2996,36 @@ 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 - +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 - # ... - } - # ... -} - +# ... +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] - +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. @@ -3362,13 +3034,11 @@ .PP In earlier versions of Snit, \fBsnit::widgetadaptor\fRs were expected to call \fBinstallhull\fR like this: .PP .CS - - installhull [text $win -foreground white] - +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?" @@ -3388,35 +3058,29 @@ 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] - } +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 - } +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 @@ -3467,21 +3131,17 @@ 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 - +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 @@ -3494,19 +3154,16 @@ 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 - } +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 @@ -3517,23 +3174,19 @@ 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 - } -} - +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 @@ -3548,38 +3201,32 @@ 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 - # ... +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 - # ... +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 - # ... +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 @@ -3592,47 +3239,38 @@ 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 - #... +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 - # ... +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 @@ -3668,80 +3306,64 @@ 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} +snit::macro fastcode {} {return 1} } else { - snit::macro fastcode {} {return 0} +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 {} {...} - } -} - +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 - } -} - +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 -} - +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} +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. @@ -3754,21 +3376,17 @@ .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} +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 @@ -3780,7 +3398,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2003-2006, by William H. Duquette - .fi Index: embedded/man/files/modules/soundex/soundex.n ================================================================== --- embedded/man/files/modules/soundex/soundex.n +++ embedded/man/files/modules/soundex/soundex.n @@ -222,11 +222,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -265,15 +264,12 @@ Knuth's algorithm and returns it as the result of the command. .PP .SH EXAMPLES .CS - - - % ::soundex::knuth Knuth - K530 - +% ::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 @@ -287,7 +283,6 @@ .SH COPYRIGHT .nf Copyright (c) ????, Algorithm: Donald E. Knuth Copyright (c) 2003, Documentation: Andreas Kupries Copyright (c) 1998, Tcl port: Evan Rempel - .fi Index: embedded/man/files/modules/stooop/stooop.n ================================================================== --- embedded/man/files/modules/stooop/stooop.n +++ embedded/man/files/modules/stooop/stooop.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -303,25 +302,19 @@ \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 - +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 - +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 Index: embedded/man/files/modules/string/token.n ================================================================== --- embedded/man/files/modules/string/token.n +++ embedded/man/files/modules/string/token.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/string/token_shell.n ================================================================== --- embedded/man/files/modules/string/token_shell.n +++ embedded/man/files/modules/string/token_shell.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/stringprep/stringprep.n ================================================================== --- embedded/man/files/modules/stringprep/stringprep.n +++ embedded/man/files/modules/stringprep/stringprep.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -311,23 +310,16 @@ 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) @@ -352,7 +344,6 @@ .SH KEYWORDS stringprep, unicode .SH COPYRIGHT .nf Copyright (c) 2007-2009, Sergei Golovan - .fi Index: embedded/man/files/modules/stringprep/stringprep_data.n ================================================================== --- embedded/man/files/modules/stringprep/stringprep_data.n +++ embedded/man/files/modules/stringprep/stringprep_data.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -265,7 +264,6 @@ .SH KEYWORDS stringprep, unicode .SH COPYRIGHT .nf Copyright (c) 2007-2009, Sergei Golovan - .fi Index: embedded/man/files/modules/stringprep/unicode.n ================================================================== --- embedded/man/files/modules/stringprep/unicode.n +++ embedded/man/files/modules/stringprep/unicode.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -280,28 +279,22 @@ ::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) @@ -320,7 +313,6 @@ .SH KEYWORDS normalization, unicode .SH COPYRIGHT .nf Copyright (c) 2007, Sergei Golovan - .fi Index: embedded/man/files/modules/stringprep/unicode_data.n ================================================================== --- embedded/man/files/modules/stringprep/unicode_data.n +++ embedded/man/files/modules/stringprep/unicode_data.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -265,7 +264,6 @@ .SH KEYWORDS stringprep, unicode .SH COPYRIGHT .nf Copyright (c) 2007, Sergei Golovan - .fi Index: embedded/man/files/modules/struct/disjointset.n ================================================================== --- embedded/man/files/modules/struct/disjointset.n +++ embedded/man/files/modules/struct/disjointset.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -297,26 +296,23 @@ \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. - | / * \\ | - | / * / | - | * /\\ * / | - | / \\ / | - | / \\/ * | - | / * \\ | - | / * \\ | - +-----------------+ - ++-----------------+ 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 Index: embedded/man/files/modules/struct/graph.n ================================================================== --- embedded/man/files/modules/struct/graph.n +++ embedded/man/files/modules/struct/graph.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -452,43 +451,31 @@ serialized graph object and \fBdeserialize\fR will be executed. .sp In other words .sp .CS - - - ::struct::graph mygraph = b - +::struct::graph mygraph = b .CE .sp is equivalent to .sp .CS - - - ::struct::graph mygraph - mygraph = b - +::struct::graph mygraph +mygraph = b .CE .sp and .sp .CS - - - ::struct::graph mygraph deserialize $b - +::struct::graph mygraph deserialize $b .CE .sp is equivalent to .sp .CS - - - ::struct::graph mygraph - mygraph deserialize $b - +::struct::graph mygraph +mygraph deserialize $b .CE .PP .PP The following commands are possible for graph objects: .TP @@ -499,14 +486,11 @@ deleted by this operation. .sp This operation is in effect equivalent to .sp .CS - - - \fIgraphName\fR \fBdeserialize\fR [\fIsourcegraph\fR \fBserialize\fR] - +\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. @@ -518,14 +502,11 @@ 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] - +\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 @@ -997,31 +978,28 @@ 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. - +# 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 @@ -1124,7 +1102,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/struct/graph1.n ================================================================== --- embedded/man/files/modules/struct/graph1.n +++ embedded/man/files/modules/struct/graph1.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -614,7 +613,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries - .fi Index: embedded/man/files/modules/struct/graphops.n ================================================================== --- embedded/man/files/modules/struct/graphops.n +++ embedded/man/files/modules/struct/graphops.n @@ -222,11 +222,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -1471,7 +1470,6 @@ .SH COPYRIGHT .nf Copyright (c) 2008 Alejandro Paz Copyright (c) 2008 (docs) Andreas Kupries Copyright (c) 2009 Michal Antoniewski - .fi Index: embedded/man/files/modules/struct/matrix.n ================================================================== --- embedded/man/files/modules/struct/matrix.n +++ embedded/man/files/modules/struct/matrix.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -381,43 +380,31 @@ matrix object and \fBdeserialize\fR will be executed. .sp In other words .sp .CS - - - ::struct::matrix mymatrix = b - +::struct::matrix mymatrix = b .CE .sp is equivalent to .sp .CS - - - ::struct::matrix mymatrix - mymatrix = b - +::struct::matrix mymatrix +mymatrix = b .CE .sp and .sp .CS - - - ::struct::matrix mymatrix deserialize $b - +::struct::matrix mymatrix deserialize $b .CE .sp is equivalent to .sp .CS - - - ::struct::matrix mymatrix - mymatrix deserialize $b - +::struct::matrix mymatrix +mymatrix deserialize $b .CE .PP .PP The following commands are possible for matrix objects: .TP @@ -428,14 +415,11 @@ this operation. .sp This operation is in effect equivalent to .sp .CS - - - \fImatrixName\fR \fBdeserialize\fR [\fIsourcematrix\fR \fBserialize\fR] - +\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 @@ -443,14 +427,11 @@ 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] - +\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 @@ -664,22 +645,19 @@ \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}} - +# 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 @@ -748,53 +726,44 @@ 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}} - +% 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}} - +% 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 - +% ::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 @@ -806,7 +775,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries - .fi Index: embedded/man/files/modules/struct/matrix1.n ================================================================== --- embedded/man/files/modules/struct/matrix1.n +++ embedded/man/files/modules/struct/matrix1.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -588,53 +587,44 @@ 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}} - +% 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}} - +% 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 - +% ::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 @@ -646,7 +636,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries - .fi Index: embedded/man/files/modules/struct/pool.n ================================================================== --- embedded/man/files/modules/struct/pool.n +++ embedded/man/files/modules/struct/pool.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -505,87 +504,67 @@ 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 - +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." - } - +# 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." - } - +# 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 - +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 @@ -597,33 +576,29 @@ 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. - } - +# 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 @@ -635,7 +610,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002, Erik Leunissen - .fi Index: embedded/man/files/modules/struct/prioqueue.n ================================================================== --- embedded/man/files/modules/struct/prioqueue.n +++ embedded/man/files/modules/struct/prioqueue.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -353,7 +352,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2003 Michael Schlenker - .fi Index: embedded/man/files/modules/struct/queue.n ================================================================== --- embedded/man/files/modules/struct/queue.n +++ embedded/man/files/modules/struct/queue.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/struct/record.n ================================================================== --- embedded/man/files/modules/struct/record.n +++ embedded/man/files/modules/struct/record.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -335,40 +334,30 @@ 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 +nest1 +nest2 } - # This is the main record record define myrecord { - mem1 - mem2 - {record mynestedrecord mem3} +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} +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 @@ -421,12 +410,10 @@ .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): @@ -450,12 +437,10 @@ -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 @@ -501,38 +486,33 @@ 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 +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} +first +middle +last +{record locations home} +{record locations work} } ::contacts % # Create an instance for the contacts record. % contacts cont1 ::cont1 @@ -557,25 +537,21 @@ % 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 +value +next } ::llist % llist lstart ::lstart % lstart config -value 1 -next [llist #auto] @@ -595,12 +571,10 @@ % 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. @@ -613,7 +587,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002, Brett Schwarz - .fi Index: embedded/man/files/modules/struct/skiplist.n ================================================================== --- embedded/man/files/modules/struct/skiplist.n +++ embedded/man/files/modules/struct/skiplist.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -324,7 +323,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2000 Keith Vetter - .fi Index: embedded/man/files/modules/struct/stack.n ================================================================== --- embedded/man/files/modules/struct/stack.n +++ embedded/man/files/modules/struct/stack.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/struct/struct_list.n ================================================================== --- embedded/man/files/modules/struct/struct_list.n +++ embedded/man/files/modules/struct/struct_list.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -397,22 +396,18 @@ 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}}} - +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 @@ -438,25 +433,21 @@ 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}}} - +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 @@ -485,19 +476,16 @@ .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 - +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 @@ -505,17 +493,14 @@ 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 - +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 @@ -525,25 +510,19 @@ 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 - +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 @@ -552,27 +531,21 @@ 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 - +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 @@ -586,18 +559,14 @@ 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 - +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. @@ -614,17 +583,13 @@ 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 - +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 @@ -659,31 +624,30 @@ 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 +\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 +\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 - +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. @@ -721,21 +685,18 @@ 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 - +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 @@ -755,19 +716,16 @@ 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}} - +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 @@ -903,45 +861,32 @@ .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 - +(...((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} - +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 @@ -965,7 +910,6 @@ Data structures .SH COPYRIGHT .nf Copyright (c) 2003-2005 by Kevin B. Kenny. All rights reserved Copyright (c) 2003-2012 Andreas Kupries - .fi Index: embedded/man/files/modules/struct/struct_set.n ================================================================== --- embedded/man/files/modules/struct/struct_set.n +++ embedded/man/files/modules/struct/struct_set.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -376,7 +375,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2004-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/struct/struct_tree.n ================================================================== --- embedded/man/files/modules/struct/struct_tree.n +++ embedded/man/files/modules/struct/struct_tree.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -394,43 +393,31 @@ \fBdeserialize\fR will be executed. .sp In other words .sp .CS - - - ::struct::tree mytree = b - +::struct::tree mytree = b .CE .sp is equivalent to .sp .CS - - - ::struct::tree mytree - mytree = b - +::struct::tree mytree +mytree = b .CE .sp and .sp .CS - - - ::struct::tree mytree deserialize $b - +::struct::tree mytree deserialize $b .CE .sp is equivalent to .sp .CS - - - ::struct::tree mytree - mytree deserialize $b - +::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 @@ -466,14 +453,11 @@ operation. .sp This operation is in effect equivalent to .sp .CS - - - \fItreeName\fR \fBdeserialize\fR [\fIsourcetree\fR \fBserialize\fR] - +\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 @@ -481,14 +465,11 @@ operation. .sp This operation is in effect equivalent to .sp .CS - - - \fIdesttree\fR \fBdeserialize\fR [\fItreeName\fR \fBserialize\fR] - +\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 @@ -546,40 +527,32 @@ 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]]) - () - +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 @@ -747,24 +720,18 @@ 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. - +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 @@ -851,25 +818,22 @@ .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 - ----- ---- ----- ----- - +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 @@ -948,19 +912,16 @@ 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. - +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 @@ -972,7 +933,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002-2004,2012 Andreas Kupries - .fi Index: embedded/man/files/modules/struct/struct_tree1.n ================================================================== --- embedded/man/files/modules/struct/struct_tree1.n +++ embedded/man/files/modules/struct/struct_tree1.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -528,7 +527,6 @@ .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries - .fi Index: embedded/man/files/modules/tar/tar.n ================================================================== --- embedded/man/files/modules/tar/tar.n +++ embedded/man/files/modules/tar/tar.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -276,15 +275,12 @@ 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. @@ -322,28 +318,22 @@ 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. @@ -363,16 +353,13 @@ 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. @@ -400,16 +387,13 @@ \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. Index: embedded/man/files/modules/tepam/tepam_argument_dialogbox.n ================================================================== --- embedded/man/files/modules/tepam/tepam_argument_dialogbox.n +++ embedded/man/files/modules/tepam/tepam_argument_dialogbox.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -263,111 +262,101 @@ .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}] +\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] +\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" - ... +-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-\fR \fIstring\fR \\ - ... +\fB-\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" \\ - ... +\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 \\ - ... +\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 \\ - ... +\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 \\ - ... +\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-\fR { \fI - ?- ? - ?- ? - ?...?\fR - } - ... +\... +\fB-\fR { \fI +?- ? +?- ? +?...?\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: @@ -377,428 +366,386 @@ 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} - ... +\... +\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 {} - ... +\... +\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 {} - ... +\... +\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} - ... +\... +\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 - ... +\... +\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-\fR { \fI - ?- ? - ?- ? - ?...?\fR - } - ... +\... +\fB-\fR { \fI +?- ? +?- ? +?...?\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} +\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} +\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} +\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} +\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} +\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} +\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} +\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} +\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} +\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} +\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} +\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}} +\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"} +\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"} +\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} +\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} +\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} +\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}} +\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} +-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} +-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} +-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} +-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} \\ +-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} \\ +\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} +-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"} ] +-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 +-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 +-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} +-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} +-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} +-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} +-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" +-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} +-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() {W Command {Par ""}} { - \fIupvar Option Option; # if required\fR - \fIvariable argument_dialogbox; # if required\fR - switch $Command { - "create" - "set_choice" - "set" - "get" - } +\fIupvar Option Option; # if required\fR +\fIvariable argument_dialogbox; # if required\fR +switch $Command { +"create" +"set_choice" +"set" +"get" +} } .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: @@ -823,29 +770,27 @@ .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]} - } +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 +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: @@ -865,7 +810,6 @@ .SH CATEGORY Argument entry form, mega widget .SH COPYRIGHT .nf Copyright (c) 2009/2010, Andreas Drollinger - .fi Index: embedded/man/files/modules/tepam/tepam_introduction.n ================================================================== --- embedded/man/files/modules/tepam/tepam_introduction.n +++ embedded/man/files/modules/tepam/tepam_introduction.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -281,32 +280,31 @@ .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"} - } +-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]" - } - } +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. @@ -321,111 +319,100 @@ .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 +display message - Displays a simple message box SYNOPSYS - display message - [-mtype ] : - Message type, default: "Warning", choices: {Info Warning Error} - [-font ] : - Message text font, type: font, default: Arial 10 italic - [-level ] : - Message level, type: integer, range: 1..10 - [-fg ] : - Message color, type: color, default: black - [-bg ] : - Background color, type: color - [-no_border ] : - Use a splash window style (no border) - [-log_file ] : - Optional message log file, type: file - : - Multiple text lines to display, type: string +display message +[-mtype ] : +Message type, default: "Warning", choices: {Info Warning Error} +[-font ] : +Message text font, type: font, default: Arial 10 italic +[-level ] : +Message level, type: integer, range: 1..10 +[-fg ] : +Message color, type: color, default: black +[-bg ] : +Background color, type: color +[-no_border ] : +Use a splash window style (no border) +[-log_file ] : +Optional message log file, type: file + : +Multiple text lines to display, type: string DESCRIPTION - This procedure allows displaying a configurable message box.\fR +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 - +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 - +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 - +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!" +"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 +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 +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 +following elements: Info, Warning, Error\fR .CE -... as well as valid value ranges: +\... 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. @@ -434,15 +421,14 @@ .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} +\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 @@ -450,82 +436,79 @@ .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}}] +\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" +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]'" - } +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 +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 @@ -532,7 +515,6 @@ .SH CATEGORY Procedures, arguments, parameters, options .SH COPYRIGHT .nf Copyright (c) 2009/2010, Andreas Drollinger - .fi Index: embedded/man/files/modules/tepam/tepam_procedure.n ================================================================== --- embedded/man/files/modules/tepam/tepam_procedure.n +++ embedded/man/files/modules/tepam/tepam_procedure.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -262,24 +261,22 @@ \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 @@ -286,11 +283,10 @@ \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 @@ -316,11 +312,10 @@ 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 @@ -329,41 +324,39 @@ .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"} - } +-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" +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 {} {} @@ -385,30 +378,27 @@ \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} - } +-args { +{-\fBmtype\fR -default Warning -choices {Warning Error}} +{\fBtext\fR -type string} +} } { - puts "Message type: \fB$mtype\fR" - puts "Message: \fB$text\fR" +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 { - ... +-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 @@ -453,34 +443,32 @@ 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 +-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 { - -args \fB{ - { \\ - ...} - { \\ - ...} - ... - }\fR +-args \fB{ +{ \\ + ...} +{ \\ + ...} +\... +}\fR } .CE The argument names and attributes have to be used in the following way: .TP Argument name (\fI>\fR) @@ -488,35 +476,31 @@ .RS .TP \fI""\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\fR. .CS - tepam::procedure {print_string} { - -args { - {\fBtext\fR -type string -description "This is an unnamed argument"} - } +-args { +{\fBtext\fR -type string -description "This is an unnamed argument"} +} } { - puts \fB$text\fR +puts \fB$text\fR } - print_string \fB"Hello"\fR \fI -> Hello\fR .CE .TP \fI"-"\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\fR (not \fI-\fR). .CS - tepam::procedure {print_string} { - -args { - {\fB-text\fR -type string -description "This is a named argument"} - } +-args { +{\fB-text\fR -type string -description "This is a named argument"} +} } { - puts \fB$text\fR +puts \fB$text\fR } - print_string \fB-text "Hello"\fR \fI -> Hello\fR .CE .TP \fI"--"\fR @@ -525,23 +509,21 @@ 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"} - } +-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]" +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 @@ -548,24 +530,22 @@ \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"} - } +-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] +return [expr $r0*$r1 - $i0*$i1] } .CE .RE .TP Argument attributes (\fI> >\fR) @@ -610,15 +590,14 @@ .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} +-args { +{text -type string -description "Message text" \\ +\fB-validatecommand "IllegalWordDetector %P"\fR} } { } .CE .TP -widget \fIstring\fR @@ -626,36 +605,33 @@ .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 {- \\ - - - ... +- +\... } .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} - } +-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 {- \\ - - - ... +- +\... } .CE .RE .PP .SH VARIABLES @@ -664,11 +640,10 @@ \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 @@ -675,11 +650,10 @@ \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 @@ -686,21 +660,19 @@ \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 @@ -721,40 +693,36 @@ .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"} - } +-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 - } +-args { +\fB{-flag -type none -description "This is a flag"}\fR +} } { - puts \fB$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. @@ -772,11 +740,10 @@ 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 -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\fR -strict \fI\fR .CE .IP \(bu \fIboolean\fR .sp @@ -787,11 +754,10 @@ \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\fR \fI\fR .CE .IP \(bu \fIalnum\fR .sp @@ -837,45 +803,40 @@ .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\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\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 ""}] .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 ]>0 && ![regexp {[\\"*?<>:]} ] .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 .CE .IP \(bu \fIdirectory\fR .sp @@ -883,11 +844,10 @@ .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 .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()\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. @@ -894,208 +854,179 @@ .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 +display message - Displays a simple message box SYNOPSIS - display message - [-mtype ] - Message type, default: "Warning", choices: {Info, Warning, Error} - - Multiple text lines to display, type: string +display message +[-mtype ] +Message type, default: "Warning", choices: {Info, Warning, Error} + +Multiple text lines to display, type: string DESCRIPTION - This procedure allows displaying a configurable message box. The default - message type that is created is a warning, but also errors and info can - be generated. - The procedure accepts multiple text lines. +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 +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} - } +-args { +{mtype -choices {Info Warning Error}} +{text -type string -multiple} +} } { - puts "$mtype: [join $text]" +puts "$mtype: [join $text]" } .CE -... can for example be called in the following ways: +\... 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} - } +-args { +{-mtype -choices {Info Warning Error}} +{-text -type string -multiple} +} } { - puts "$mtype: [join $text]" +puts "$mtype: [join $text]" } .CE -... can be called in the following ways: +\... 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 ""} - } +-args { +{-n1 -default ""} +{-n2 -default ""} +{u1 -default ""} +{u2 -default ""} +} } { - puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" +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} - } +-args { +{-n1 -default ""} +{-n2 -default ""} +{u1} +{u2 -default "" -multiple} +} } { - puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" +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 @@ -1105,77 +1036,65 @@ .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} - - } +-args { +{-mtype -choices {Warning Error} -default Warning} +{text -type string -multiple} +} } { - puts "args: \fB$args\fR" +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" @@ -1185,7 +1104,6 @@ .SH CATEGORY Procedures, arguments, parameters, options .SH COPYRIGHT .nf Copyright (c) 2009/2010, Andreas Drollinger - .fi Index: embedded/man/files/modules/term/ansi_cattr.n ================================================================== --- embedded/man/files/modules/term/ansi_cattr.n +++ embedded/man/files/modules/term/ansi_cattr.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -459,7 +458,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/term/ansi_cctrl.n ================================================================== --- embedded/man/files/modules/term/ansi_cctrl.n +++ embedded/man/files/modules/term/ansi_cctrl.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -750,7 +749,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/term/ansi_cmacros.n ================================================================== --- embedded/man/files/modules/term/ansi_cmacros.n +++ embedded/man/files/modules/term/ansi_cmacros.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -306,7 +305,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/term/ansi_code.n ================================================================== --- embedded/man/files/modules/term/ansi_code.n +++ embedded/man/files/modules/term/ansi_code.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -290,7 +289,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/term/ansi_ctrlu.n ================================================================== --- embedded/man/files/modules/term/ansi_ctrlu.n +++ embedded/man/files/modules/term/ansi_ctrlu.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -314,7 +313,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006-2011 Andreas Kupries - .fi Index: embedded/man/files/modules/term/ansi_send.n ================================================================== --- embedded/man/files/modules/term/ansi_send.n +++ embedded/man/files/modules/term/ansi_send.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -742,7 +741,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/term/imenu.n ================================================================== --- embedded/man/files/modules/term/imenu.n +++ embedded/man/files/modules/term/imenu.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -381,7 +380,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/term/ipager.n ================================================================== --- embedded/man/files/modules/term/ipager.n +++ embedded/man/files/modules/term/ipager.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -382,7 +381,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/term/receive.n ================================================================== --- embedded/man/files/modules/term/receive.n +++ embedded/man/files/modules/term/receive.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -310,7 +309,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/term/term.n ================================================================== --- embedded/man/files/modules/term/term.n +++ embedded/man/files/modules/term/term.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -265,7 +264,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/term/term_bind.n ================================================================== --- embedded/man/files/modules/term/term_bind.n +++ embedded/man/files/modules/term/term_bind.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -354,7 +353,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/term/term_send.n ================================================================== --- embedded/man/files/modules/term/term_send.n +++ embedded/man/files/modules/term/term_send.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -280,7 +279,6 @@ .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/textutil/adjust.n ================================================================== --- embedded/man/files/modules/textutil/adjust.n +++ embedded/man/files/modules/textutil/adjust.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/textutil/expander.n ================================================================== --- embedded/man/files/modules/textutil/expander.n +++ embedded/man/files/modules/textutil/expander.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -292,19 +291,16 @@ 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! - % - +% 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 @@ -341,14 +337,11 @@ 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 @@ -480,79 +473,66 @@ .SH TUTORIAL .SS BASICS To begin, create an expander object: .PP .CS - - - % package require expander - 1.2 - % ::expander::expander myexp - ::myexp - % - +% 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! - % - +% 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! - % - +% 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 ""} - % proc /bold {} {return ""} - % ::myexp expand {Some of this text is in [bold]boldface[/bold]} - Some of this text is in boldface - % - +% proc bold {} {return ""} +% proc /bold {} {return ""} +% ::myexp expand {Some of this text is in [bold]boldface[/bold]} +Some of this text is in boldface +% .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. @@ -567,29 +547,23 @@ 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 {This is boldface} - This is boldface - +% ::myexp setbrackets < > +% ::myexp expand {This is boldface} +This is boldface .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 {This is boldface} {< >} - This is boldface - % - +% ::myexp setbrackets "\\\\[" "\\\\]" +% ::myexp expand {This is boldface} {< >} +This is boldface +% .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 @@ -600,42 +574,33 @@ .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 - +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"] - +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] - +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; @@ -647,23 +612,18 @@ 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. - } - +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 @@ -677,26 +637,21 @@ 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. - } - +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 @@ -718,7 +673,6 @@ .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) William H. Duquette, http://www.wjduquette.com/expand - .fi Index: embedded/man/files/modules/textutil/repeat.n ================================================================== --- embedded/man/files/modules/textutil/repeat.n +++ embedded/man/files/modules/textutil/repeat.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/textutil/tabify.n ================================================================== --- embedded/man/files/modules/textutil/tabify.n +++ embedded/man/files/modules/textutil/tabify.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/textutil/textutil.n ================================================================== --- embedded/man/files/modules/textutil/textutil.n +++ embedded/man/files/modules/textutil/textutil.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/textutil/textutil_split.n ================================================================== --- embedded/man/files/modules/textutil/textutil_split.n +++ embedded/man/files/modules/textutil/textutil_split.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/textutil/textutil_string.n ================================================================== --- embedded/man/files/modules/textutil/textutil_string.n +++ embedded/man/files/modules/textutil/textutil_string.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/textutil/trim.n ================================================================== --- embedded/man/files/modules/textutil/trim.n +++ embedded/man/files/modules/textutil/trim.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/tie/tie.n ================================================================== --- embedded/man/files/modules/tie/tie.n +++ embedded/man/files/modules/tie/tie.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -646,25 +645,22 @@ .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 - ----------- ----------- - +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 @@ -676,7 +672,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2004-2008 Andreas Kupries - .fi Index: embedded/man/files/modules/tie/tie_std.n ================================================================== --- embedded/man/files/modules/tie/tie_std.n +++ embedded/man/files/modules/tie/tie_std.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -279,7 +278,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2008 Andreas Kupries - .fi Index: embedded/man/files/modules/tiff/tiff.n ================================================================== --- embedded/man/files/modules/tiff/tiff.n +++ embedded/man/files/modules/tiff/tiff.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -314,19 +313,15 @@ \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 {} - +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. @@ -339,28 +334,22 @@ \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]" - +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"}} - +::tiff::addEntry photo.tif {{010e 2 "an example photo"} {013b 2 "Aaron F"}} .CE .IP The data types are defined as follows .RS .TP @@ -452,7 +441,6 @@ .SH CATEGORY File formats .SH COPYRIGHT .nf Copyright (c) 2005-2006, Aaron Faupell - .fi Index: embedded/man/files/modules/transfer/connect.n ================================================================== --- embedded/man/files/modules/transfer/connect.n +++ embedded/man/files/modules/transfer/connect.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -410,20 +409,16 @@ 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 ... - ... - +# 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 @@ -435,7 +430,6 @@ .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/transfer/copyops.n ================================================================== --- embedded/man/files/modules/transfer/copyops.n +++ embedded/man/files/modules/transfer/copyops.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -386,7 +385,6 @@ .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/transfer/ddest.n ================================================================== --- embedded/man/files/modules/transfer/ddest.n +++ embedded/man/files/modules/transfer/ddest.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -369,7 +368,6 @@ .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/transfer/dsource.n ================================================================== --- embedded/man/files/modules/transfer/dsource.n +++ embedded/man/files/modules/transfer/dsource.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -407,7 +406,6 @@ .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/transfer/receiver.n ================================================================== --- embedded/man/files/modules/transfer/receiver.n +++ embedded/man/files/modules/transfer/receiver.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -459,20 +458,16 @@ 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 ... - ... - +# 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 @@ -484,7 +479,6 @@ .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/transfer/tqueue.n ================================================================== --- embedded/man/files/modules/transfer/tqueue.n +++ embedded/man/files/modules/transfer/tqueue.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -291,14 +290,11 @@ error message about the queue abort, and 0 bytes transfered. .PP All transfer requests are of the form .PP .CS - - - {type data options...} - +{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 @@ -392,7 +388,6 @@ .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries - .fi Index: embedded/man/files/modules/transfer/transmitter.n ================================================================== --- embedded/man/files/modules/transfer/transmitter.n +++ embedded/man/files/modules/transfer/transmitter.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -469,20 +468,16 @@ 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 ... - ... - +# 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 @@ -494,7 +489,6 @@ .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries - .fi Index: embedded/man/files/modules/treeql/treeql.n ================================================================== --- embedded/man/files/modules/treeql/treeql.n +++ embedded/man/files/modules/treeql/treeql.n @@ -221,11 +221,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -356,34 +355,27 @@ 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 - +# 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. @@ -564,11 +556,10 @@ 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. @@ -577,11 +568,10 @@ 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 @@ -589,11 +579,10 @@ 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 @@ -804,11 +793,10 @@ .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 @@ -822,11 +810,11 @@ 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 ... +\... 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 @@ -845,7 +833,6 @@ Data structures .SH COPYRIGHT .nf Copyright (c) 2004 Colin McCormack Copyright (c) 2004 Andreas Kupries - .fi Index: embedded/man/files/modules/try/tcllib_try.n ================================================================== --- embedded/man/files/modules/try/tcllib_try.n +++ embedded/man/files/modules/try/tcllib_try.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -318,35 +317,29 @@ .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" - # ... +puts \\$f "some message" +# ... } \fBfinally\fR { - close \\$f +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] +set f [open /some/file/name] } \fBtrap\fR {POSIX EISDIR} {} { - puts "failed to open /some/file/name: it's a directory" +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" +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 @@ -360,7 +353,6 @@ .SH CATEGORY Utility .SH COPYRIGHT .nf Copyright (c) 2008 Donal K. Fellows, BSD licensed - .fi Index: embedded/man/files/modules/uev/uevent.n ================================================================== --- embedded/man/files/modules/uev/uevent.n +++ embedded/man/files/modules/uev/uevent.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -430,7 +429,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2007-2012 Andreas Kupries - .fi Index: embedded/man/files/modules/uev/uevent_onidle.n ================================================================== --- embedded/man/files/modules/uev/uevent_onidle.n +++ embedded/man/files/modules/uev/uevent_onidle.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -295,7 +294,6 @@ .SH KEYWORDS callback, deferal, event, idle, merge, on-idle .SH COPYRIGHT .nf Copyright (c) 2008 Andreas Kupries - .fi Index: embedded/man/files/modules/units/units.n ================================================================== --- embedded/man/files/modules/units/units.n +++ embedded/man/files/modules/units/units.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -287,21 +286,18 @@ 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 @@ -308,15 +304,12 @@ 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. @@ -327,17 +320,14 @@ 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. @@ -372,12 +362,10 @@ 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 @@ -387,11 +375,10 @@ 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 @@ -398,27 +385,22 @@ 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 @@ -438,11 +420,10 @@ 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 @@ -461,12 +442,10 @@ 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 @@ -476,11 +455,10 @@ 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 @@ -487,11 +465,10 @@ 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 @@ -506,12 +483,10 @@ 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 @@ -543,11 +518,10 @@ 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 @@ -602,7 +576,6 @@ .SH KEYWORDS angle, constants, conversion, distance, radians, unit .SH COPYRIGHT .nf Copyright (c) 2000-2005 Mayo Foundation - .fi Index: embedded/man/files/modules/uri/uri.n ================================================================== --- embedded/man/files/modules/uri/uri.n +++ embedded/man/files/modules/uri/uri.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/uri/urn-scheme.n ================================================================== --- embedded/man/files/modules/uri/urn-scheme.n +++ embedded/man/files/modules/uri/urn-scheme.n @@ -219,11 +219,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf Index: embedded/man/files/modules/uuid/uuid.n ================================================================== --- embedded/man/files/modules/uuid/uuid.n +++ embedded/man/files/modules/uuid/uuid.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -268,15 +267,12 @@ \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) @@ -293,7 +289,6 @@ .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2004, Pat Thoyts - .fi Index: embedded/man/files/modules/virtchannel_base/cat.n ================================================================== --- embedded/man/files/modules/virtchannel_base/cat.n +++ embedded/man/files/modules/virtchannel_base/cat.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -289,7 +288,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/facade.n ================================================================== --- embedded/man/files/modules/virtchannel_base/facade.n +++ embedded/man/files/modules/virtchannel_base/facade.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -313,7 +312,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/fifo.n ================================================================== --- embedded/man/files/modules/virtchannel_base/fifo.n +++ embedded/man/files/modules/virtchannel_base/fifo.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -283,7 +282,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/fifo2.n ================================================================== --- embedded/man/files/modules/virtchannel_base/fifo2.n +++ embedded/man/files/modules/virtchannel_base/fifo2.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -289,7 +288,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/halfpipe.n ================================================================== --- embedded/man/files/modules/virtchannel_base/halfpipe.n +++ embedded/man/files/modules/virtchannel_base/halfpipe.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -315,7 +314,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/memchan.n ================================================================== --- embedded/man/files/modules/virtchannel_base/memchan.n +++ embedded/man/files/modules/virtchannel_base/memchan.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,7 +285,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/null.n ================================================================== --- embedded/man/files/modules/virtchannel_base/null.n +++ embedded/man/files/modules/virtchannel_base/null.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,7 +285,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/nullzero.n ================================================================== --- embedded/man/files/modules/virtchannel_base/nullzero.n +++ embedded/man/files/modules/virtchannel_base/nullzero.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -283,7 +282,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/random.n ================================================================== --- embedded/man/files/modules/virtchannel_base/random.n +++ embedded/man/files/modules/virtchannel_base/random.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,7 +285,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/randseed.n ================================================================== --- embedded/man/files/modules/virtchannel_base/randseed.n +++ embedded/man/files/modules/virtchannel_base/randseed.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -281,7 +280,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/std.n ================================================================== --- embedded/man/files/modules/virtchannel_base/std.n +++ embedded/man/files/modules/virtchannel_base/std.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -283,7 +282,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/string.n ================================================================== --- embedded/man/files/modules/virtchannel_base/string.n +++ embedded/man/files/modules/virtchannel_base/string.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,7 +285,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/textwindow.n ================================================================== --- embedded/man/files/modules/virtchannel_base/textwindow.n +++ embedded/man/files/modules/virtchannel_base/textwindow.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -280,7 +279,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/variable.n ================================================================== --- embedded/man/files/modules/virtchannel_base/variable.n +++ embedded/man/files/modules/virtchannel_base/variable.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -287,7 +286,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_base/zero.n ================================================================== --- embedded/man/files/modules/virtchannel_base/zero.n +++ embedded/man/files/modules/virtchannel_base/zero.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -286,7 +285,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_core/core.n ================================================================== --- embedded/man/files/modules/virtchannel_core/core.n +++ embedded/man/files/modules/virtchannel_core/core.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -312,7 +311,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_core/events.n ================================================================== --- embedded/man/files/modules/virtchannel_core/events.n +++ embedded/man/files/modules/virtchannel_core/events.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -321,7 +320,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_core/transformcore.n ================================================================== --- embedded/man/files/modules/virtchannel_core/transformcore.n +++ embedded/man/files/modules/virtchannel_core/transformcore.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -312,7 +311,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/adler32.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/adler32.n +++ embedded/man/files/modules/virtchannel_transform/adler32.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -306,7 +305,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/base64.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/base64.n +++ embedded/man/files/modules/virtchannel_transform/base64.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -282,7 +281,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/counter.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/counter.n +++ embedded/man/files/modules/virtchannel_transform/counter.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -305,7 +304,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/crc32.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/crc32.n +++ embedded/man/files/modules/virtchannel_transform/crc32.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -306,7 +305,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/hex.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/hex.n +++ embedded/man/files/modules/virtchannel_transform/hex.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -282,7 +281,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/identity.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/identity.n +++ embedded/man/files/modules/virtchannel_transform/identity.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -289,7 +288,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/limitsize.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/limitsize.n +++ embedded/man/files/modules/virtchannel_transform/limitsize.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -284,7 +283,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/observe.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/observe.n +++ embedded/man/files/modules/virtchannel_transform/observe.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -288,7 +287,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/otp.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/otp.n +++ embedded/man/files/modules/virtchannel_transform/otp.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -287,7 +286,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/rot.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/rot.n +++ embedded/man/files/modules/virtchannel_transform/rot.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -291,7 +290,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/spacer.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/spacer.n +++ embedded/man/files/modules/virtchannel_transform/spacer.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -284,7 +283,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/virtchannel_transform/zlib.n ================================================================== --- embedded/man/files/modules/virtchannel_transform/zlib.n +++ embedded/man/files/modules/virtchannel_transform/zlib.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -282,7 +281,6 @@ .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries - .fi Index: embedded/man/files/modules/wip/wip.n ================================================================== --- embedded/man/files/modules/wip/wip.n +++ embedded/man/files/modules/wip/wip.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -557,20 +556,18 @@ \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 @@ -602,7 +599,6 @@ .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2007-2010 Andreas Kupries - .fi Index: embedded/man/files/modules/yaml/huddle.n ================================================================== --- embedded/man/files/modules/yaml/huddle.n +++ embedded/man/files/modules/yaml/huddle.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -314,26 +313,23 @@ 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 {huddle-node}} huddle-node: > - {tag content} +{tag content} each content of tag means: - s: (content is a) string - L: list, each sub node is a huddle-node - D: dict, each sub node is a huddle-node +s: (content is a) string +L: list, each sub node is a huddle-node +D: dict, each sub node is a huddle-node confirmed: - - JSON - - YAML(generally, but cannot discribe YAML-tags) +- JSON +- YAML(generally, but cannot discribe YAML-tags) limitation: - - cannot discribe aliases from a node to other node. - +- cannot discribe aliases from a node to other node. .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. @@ -364,52 +360,43 @@ \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 @@ -430,19 +417,16 @@ .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 @@ -453,33 +437,31 @@ .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" +[ +"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: @@ -506,16 +488,14 @@ 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 @@ -525,35 +505,29 @@ \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 @@ -620,194 +594,176 @@ .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" - } - } -} - +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] - } - } -} - +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" -] - +{ +"bb": { +"a": "b", +"c": "kkk" +}, +"cc": [ +"e", +"f", +"g", +"h" +] +}, +"p", +[ +"q", +"r" +], +"s" +] .CE .SH LIMITATIONS .PP now printing. .SH "BUGS, IDEAS, FEEDBACK" @@ -822,7 +778,6 @@ .SH KEYWORDS data exchange, exchange format, huddle, json, parsing, text processing, yaml .SH COPYRIGHT .nf Copyright (c) 2008 KATO Kanryu - .fi Index: embedded/man/files/modules/yaml/yaml.n ================================================================== --- embedded/man/files/modules/yaml/yaml.n +++ embedded/man/files/modules/yaml/yaml.n @@ -220,11 +220,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -284,47 +283,41 @@ \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} +-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}} +-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}} +-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 "" ~}} +-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. @@ -353,41 +346,40 @@ .PP An example of a yaml stream converted to Tcl. A yaml stream is returned as a single item with multiple elements. .PP .CS - { --- ! 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 +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 +- 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. +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. @@ -397,23 +389,21 @@ .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} +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 @@ -434,7 +424,6 @@ .SH KEYWORDS data exchange, huddle, parsing, text processing, yaml .SH COPYRIGHT .nf Copyright (c) 2008 KATO Kanryu - .fi Index: embedded/man/index.n ================================================================== --- embedded/man/index.n +++ embedded/man/index.n @@ -218,11 +218,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -239,17 +238,17 @@ .TH "Keyword Index" n .BS .SH INDEX tcllib .RS -.ddt +\.ddt .RS .TP \fBfiles/modules/docstrip/docstrip_util.n\fR docstrip_util .RE -.dtx +\.dtx .RS .TP \fBfiles/modules/docstrip/docstrip.n\fR docstrip .TP @@ -1582,10 +1581,13 @@ \fBfiles/modules/doctools2toc/export.n\fR doctools::toc::export .TP \fBfiles/modules/doctools2toc/import.n\fR doctools::toc::import +.TP +\fBfiles/modules/dtplite/dtplite.n\fR +dtplite .TP \fBfiles/apps/dtplite.n\fR dtplite .TP \fBfiles/modules/math/roman.n\fR @@ -2164,10 +2166,13 @@ \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/dtplite/dtplite.n\fR +dtplite .TP \fBfiles/apps/dtplite.n\fR dtplite .RE docidx commands @@ -2278,10 +2283,13 @@ \fBfiles/modules/doctools2toc/parse.n\fR doctools::toc::parse .TP \fBfiles/modules/doctools2toc/structure.n\fR doctools::toc::structure +.TP +\fBfiles/modules/dtplite/dtplite.n\fR +dtplite .TP \fBfiles/apps/dtplite.n\fR dtplite .RE doctoc commands @@ -2446,10 +2454,13 @@ \fBfiles/modules/doctools2toc/parse.n\fR doctools::toc::parse .TP \fBfiles/modules/doctools2toc/structure.n\fR doctools::toc::structure +.TP +\fBfiles/modules/dtplite/dtplite.n\fR +dtplite .TP \fBfiles/apps/dtplite.n\fR dtplite .RE doctools commands @@ -3904,10 +3915,13 @@ \fBfiles/modules/doctools2toc/export.n\fR doctools::toc::export .TP \fBfiles/modules/doctools2toc/export_html.n\fR doctools::toc::export::html +.TP +\fBfiles/modules/dtplite/dtplite.n\fR +dtplite .TP \fBfiles/apps/dtplite.n\fR dtplite .TP \fBfiles/modules/doctools/mpexpand.n\fR @@ -4999,10 +5013,13 @@ \fBfiles/modules/doctools2toc/import.n\fR doctools::toc::import .TP \fBfiles/modules/doctools/doctools_plugin_apiref.n\fR doctools_plugin_apiref +.TP +\fBfiles/modules/dtplite/dtplite.n\fR +dtplite .TP \fBfiles/apps/dtplite.n\fR dtplite .TP \fBfiles/modules/doctools/mpexpand.n\fR @@ -5119,10 +5136,13 @@ \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/modules/dtplite/dtplite.n\fR +dtplite .TP \fBfiles/apps/dtplite.n\fR dtplite .TP \fBfiles/modules/doctools/mpexpand.n\fR @@ -5857,10 +5877,13 @@ \fBfiles/modules/doctools2toc/export.n\fR doctools::toc::export .TP \fBfiles/modules/doctools2toc/export_nroff.n\fR doctools::toc::export::nroff +.TP +\fBfiles/modules/dtplite/dtplite.n\fR +dtplite .TP \fBfiles/apps/dtplite.n\fR dtplite .TP \fBfiles/modules/doctools/mpexpand.n\fR @@ -9517,10 +9540,13 @@ \fBfiles/modules/doctools2toc/container.n\fR doctools::toc .TP \fBfiles/modules/doctools/doctoc.n\fR doctools::toc +.TP +\fBfiles/modules/dtplite/dtplite.n\fR +dtplite .TP \fBfiles/apps/dtplite.n\fR dtplite .TP \fBfiles/modules/doctools/mpexpand.n\fR Index: embedded/man/toc.n ================================================================== --- embedded/man/toc.n +++ embedded/man/toc.n @@ -218,11 +218,10 @@ .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi -.IP .. '\" # CS - begin code excerpt .de CS .RS .nf @@ -543,10 +542,13 @@ \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/modules/dtplite/dtplite.n\fR: Lightweight DocTools Markup Processor +.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 Index: embedded/www/index.html ================================================================== --- embedded/www/index.html +++ embedded/www/index.html @@ -6,13 +6,16 @@ Keyword Index
[ - Table Of Contents -| Home -]
+ Tcllib Home +| Table Of Contents +| Categories +| Modules +| Applications + ]

Keyword Index

. · / · 3 · A · B · C · D · E · F · G · H · I · J · K · L · M · N · O · P · Q · R · S · T · U · V · W · X · Y · Z
@@ -127,16 +130,16 @@ - + - + @@ -232,11 +235,11 @@ - + @@ -282,11 +285,11 @@ - + - + @@ -483,11 +486,11 @@ - + @@ -518,11 +521,11 @@ - + @@ -688,11 +691,11 @@ - + @@ -713,41 +716,41 @@ - + - + - + - + @@ -758,21 +761,21 @@ - + - + @@ -831,11 +834,11 @@ - + @@ -861,11 +864,11 @@ - + @@ -921,11 +924,11 @@ - + @@ -986,11 +989,11 @@ - + @@ -1001,11 +1004,11 @@ - + @@ -1021,18 +1024,18 @@ - + - + - + @@ -1134,16 +1137,16 @@ - + - + @@ -1164,11 +1167,11 @@ - + @@ -1209,11 +1212,11 @@ - + @@ -1284,11 +1287,11 @@ - + - + @@ -1337,21 +1340,21 @@ - + - + @@ -1387,11 +1390,11 @@ - + @@ -1402,31 +1405,31 @@ - + - + - + - + @@ -1442,11 +1445,11 @@ - + @@ -1462,16 +1465,16 @@ - + - + @@ -1495,26 +1498,26 @@ - + - + - + @@ -1555,11 +1558,11 @@ - + @@ -1570,11 +1573,11 @@ - + - + - + - + - + @@ -1726,11 +1729,11 @@ - + @@ -1741,11 +1744,11 @@ - + @@ -1761,11 +1764,11 @@ - + @@ -1821,11 +1824,11 @@ - + - + - + - + - + @@ -1935,11 +1938,11 @@ - + @@ -1960,11 +1963,11 @@ - + @@ -2015,11 +2018,11 @@ - + @@ -2040,11 +2043,11 @@ - + @@ -2058,11 +2061,11 @@ - + @@ -2080,21 +2083,21 @@ doctools::nroff::man_macros - + - + @@ -2168,11 +2171,11 @@ - + @@ -2268,16 +2271,16 @@ - + - + @@ -2291,16 +2294,16 @@ - + - + @@ -2311,11 +2314,11 @@ - + @@ -2341,11 +2344,11 @@ - + @@ -2363,14 +2366,14 @@ bench · page_util_norm_lemon · page_util_norm_peg · unicode - + @@ -2414,11 +2417,11 @@ - + @@ -2442,11 +2445,11 @@ - + @@ -2472,11 +2475,11 @@ - + @@ -2497,26 +2500,26 @@ - + - + - + @@ -2547,21 +2550,21 @@ - + - + @@ -2582,11 +2585,11 @@ - + @@ -2632,11 +2635,11 @@ - + @@ -2647,31 +2650,31 @@ - + - + - + @@ -2682,11 +2685,11 @@ - + @@ -2700,11 +2703,11 @@ - + - + @@ -2788,11 +2791,11 @@ - + @@ -2848,11 +2851,11 @@ - + @@ -2883,21 +2886,21 @@ - + - + - + @@ -2948,91 +2951,91 @@ - + - + - + - + - + - + - + - + - + - + - + - + @@ -3048,11 +3051,11 @@ - + @@ -3106,11 +3109,11 @@ - + @@ -3146,11 +3149,11 @@ - + @@ -3161,11 +3164,11 @@ - + @@ -3201,11 +3204,11 @@ - + @@ -3221,21 +3224,21 @@ - + - + - + @@ -3246,21 +3249,21 @@ - + - + @@ -3321,21 +3324,21 @@ - + - + - + @@ -3376,21 +3379,21 @@ - + - + - + @@ -3406,21 +3409,21 @@ - + - + @@ -3459,11 +3462,11 @@ - + @@ -3489,11 +3492,11 @@ - + @@ -3519,11 +3522,11 @@ - + @@ -3564,11 +3567,11 @@ - + @@ -3589,16 +3592,16 @@ - + - + @@ -3619,26 +3622,26 @@ - + - + - + @@ -3669,18 +3672,18 @@ - + - + - + - + @@ -3777,11 +3780,11 @@ - + @@ -3802,21 +3805,21 @@ - + - + @@ -3837,26 +3840,26 @@ - + - + - + - + - + - + - + - +
amazon S3
ambiguous ambiguous grammar::aycock
angle angle math::geometry · units
anonymous procedure assembler grammar::me::cpu::gasm
assert assert control
assign automaton grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op
aycock aycock grammar::aycock
Keywords: B @@ -345,11 +348,11 @@ bibtex bibtex
bignums bignums math::bignum
bind CFL grammar::me_intro
CGI CGI ncgi
cgraph character output term::ansi::send · term::send
chat chat irc · multiplexer · picoirc
checkbox constants math::constants · units
CONTAINER CONTAINER pt::peg::export::container · pt::peg::to::container
contents 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 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 + doctools · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · dtplite · dtplite · math::roman · mpexpand · pt::peg::from::json · pt::peg::from::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · tcldocstrip · units
cooked term::ansi::ctrl::unix
cookie 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 · coroutine::auto · generator
Cost Cost treeql
counter counting counter
CPARAM CPARAM pt::peg::to::cparam
crc cksum · crc16 · crc32 · sum
crc16 crc16 crc16
crc32
Keywords: D
data analysis data analysis math::statistics
data destination data source transfer::data::source · transfer::transmitter
data structures data structures struct::record
database degree constrained spanning tree struct::graph::op
degrees degrees math::constants
delegation dijkstra struct::graph::op
directory access directory access ldap · ldapx
directory traversal discrete items struct::pool
disjoint set disjoint set struct::disjointset
dispatcher DNS dns
do 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 + doctools::idx · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::import · doctools::idx::import::docidx · doctools::idx::parse · doctools::idx::structure · doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · dtplite · dtplite
docidx commands docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax @@ -1058,11 +1061,11 @@ 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 + doctools::msgcat · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr · doctools::toc · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::parse · doctools::toc::structure · dtplite · dtplite
doctoc commands doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax @@ -1083,11 +1086,11 @@ 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 + docstrip_util · doctools::changelog · doctools::html::cssdefaults · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::import::docidx · doctools::idx::import::json · doctools::idx::parse · doctools::idx::structure · doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr · doctools::nroff::man_macros · doctools::tcl::parse · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import::doctoc · doctools::toc::import::json · doctools::toc::parse · doctools::toc::structure · dtplite · dtplite
doctools commands doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax @@ -1116,16 +1119,16 @@ 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 DOM treeql
dom dom xsxp
domain name service
Keywords: E
e e math::constants
earley earley grammar::aycock
EBNF emacs doctools::changelog · doctools::cvs
email email imap4 · mime · pop3 · smtp
emptiness equality struct::list
equivalence class equivalence class struct::disjointset
error 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 extended namespace namespacex
Keywords: F @@ -1302,11 +1305,11 @@ fetching information uri
FFT FFT math::fourier
fifo filesystem map::slippy::cache
filter filter generator · struct::list
final try
find find struct::disjointset
finite floating-point math::bigfloat · math::fuzzy
flow flow control
flow network folding struct::list
foldl foldl generator
foldr foldr generator
foreach foreach generator
form html · ncgi
format conversion 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 formatting engine docidx_plugin_apiref · doctoc_plugin_apiref · doctools_plugin_apiref
Fourier transform Fourier transform math::fourier
FR ftp ftp · ftp::geturl · ftpd · uri
ftpd ftpd ftpd
ftpserver ftpserver ftpd
full outer join generation doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export
generator generator generator
geocoding map::geocode::nominatim
geodesy geodesy map::slippy · mapproj
geography geography map::slippy
get character graph grammar::me::cpu::gasm · struct::graph · struct::graph::op · struct::graph_v1 · struct::queue · struct::stack
graph walking graph walking page_util_flow · page_util_norm_lemon · page_util_norm_peg
green threads grep fileutil
GUID GUID uuid
Keywords: H @@ -1603,23 +1606,23 @@ histogram counter
hook hook hook · uevent
horspool 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 + doctools · doctools::html::cssdefaults · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::html · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::html · dtplite · dtplite · mpexpand
html html · htmlparse · javascript · ncgi @@ -1671,16 +1674,16 @@ idle uevent::onidle
image image jpeg · png · tiff
imap imap imap4
import index formatter docidx_plugin_apiref
info info namespacex
inner join input mode term::ansi::ctrl::unix
integer integer math::roman
integration 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 internet asn · ftp · ftp::geturl · imap4 · ldap · ldapx · mime · pop3d · pop3d::dbox · pop3d::udb · smtp
internet address isthmus struct::graph::op
iterator iterator generator
Keywords: J @@ -1877,11 +1880,11 @@ keywords docidx_plugin_apiref
knuth knuth soundex
Keywords: L @@ -1905,21 +1908,21 @@ latex doctools::idx · doctools::idx · doctools::toc · doctools::toc
latitute latitute map::slippy
ldap ldap ldap · ldapx · uri
ldap client ldap client ldap · ldapx
ldif left outer join struct::list
lemon lemon page_util_norm_lemon
level graph limitsize tcl::transform::limitsize
line line math::geometry
linear algebra 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 location map::geocode::nominatim · map::slippy · map::slippy::cache · map::slippy::fetcher
log longest common subsequence struct::list
longitude longitude map::slippy
loop macros doctools::nroff::man_macros
mail mail imap4 · mime · pop3 · smtp
mailto
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 + doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import · doctools_plugin_apiref · dtplite · dtplite · mpexpand
map 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 + docidx_intro · docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · docidx_plugin_apiref · doctoc_intro · doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctoc_plugin_apiref · doctools · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · doctools_intro · doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax · doctools_plugin_apiref · dtplite · dtplite · mpexpand · tcldocstrip
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 @@ -2103,11 +2106,11 @@ 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 mathematics math::fourier · math::statistics
matrices merge tcl::chan::randseed · uevent::onidle
merge find merge find struct::disjointset
merging multi-file fileutil::multi · fileutil::multi::op
multiplexer multiplexer multiplexer
multiprecision multiprecision math::bigfloat · math::bignum
my method name service nameserv · nameserv::auto · nameserv::common · nameserv::protocol · nameserv::server · nns · nns_intro · nnsd · nnslog
namespace unknown namespace unknown namespacex
namespace utilities namespace utilities namespacex
neighbour net ftp · ftp::geturl · imap4 · mime · smtp
network network pop3d · pop3d::dbox · pop3d::udb
news nntpclient nntp
no-op no-op control
node
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 + doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::nroff · doctools::nroff::man_macros · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::nroff · dtplite · dtplite · mpexpand
NTP NTP ntp_time
null optimization math::optimize · simulation::annealing
ordered list ordered list struct::prioqueue
otp package indexing docstrip_util
page page page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote
pager 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 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 partial application lambda
partition partition struct::disjointset
partitioned set partitioned set struct::disjointset
passive transfer::connect
password password otp
patch persistence tie · tie
pi pi math::constants
plain text doctools::idx::export::text · doctools::toc::export::text
plane geometry plane geometry math::geometry
plugin png png
point point math::geometry
polynomial functions prioqueue struct::prioqueue · struct::queue
priority queue priority queue struct::prioqueue
proc procedure deleg_proc · tepam · tepam::procedure
producer producer hook
profile profiler
projection projection mapproj
prospero uri
protocol protocol asn · ldap · ldapx · nameserv::protocol · pop3d · pop3d::dbox · pop3d::udb
proxy public key cipher pki
publisher publisher hook
push down automaton queue csv · htmlparse · struct::stack · transfer::copy::queue
quoting quoting page_util_quote
Keywords: R @@ -2728,11 +2731,11 @@ random tcl::chan::random · tcl::chan::randseed
random numbers random numbers simulation::random
rational functions 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 reduce generator · struct::list
reference repetition struct::list · textutil::repeat
report report report
reshuffle reverse struct::list
rfc 821 rfc 821 mime · smtp · smtpd
rfc 822 rfc 822 mime · pop3d::dbox · smtp
rfc 868 rfc 868 ntp_time
rfc 959 rfc 1939 pop3 · pop3d
rfc 2030 rfc 2030 ntp_time
rfc 2045 rfc 2045 mime
rfc 2046 rfc 2046 mime
rfc 2049 rfc 2049 mime
rfc 2104 md4 · md5 · ripemd128 · ripemd160 · sha1 · sha256
rfc 2141 rfc 2141 uri_urn
rfc 2251 rfc 2251 ldap · ldapx
rfc 2255 uri
rfc 2289 rfc 2289 otp
rfc 2396 uri
rfc 2554 rfc 2554 smtp
rfc 2821 rfc 2821 smtp · smtpd
rfc 2849 ldapx
rfc 3207 rfc 3207 smtp
rfc 3513 tcllib_ip
rfc 4511 rfc 4511 ldap
rfc3501 rfc3501 imap4
rfc3548 RIPEMD ripemd128 · ripemd160
roman numeral roman numeral math::roman
roots SASL SASL
scanl scanl generator
SCCS send comm
serialization 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 service logger
services services ftpd · smtpd
set simulated annealing simulation::annealing
simulation simulation simulation::random
singleton skiplist struct::queue · struct::skiplist
slippy slippy map::slippy · map::slippy::cache · map::slippy::fetcher
smtp smtp mime · smtp · smtpd
smtpd smtpd smtpd
Snit snit deleg_method · interp
SNTP SNTP ntp_time
socket comm · comm_wire · smtpd
soundex soundex soundex
source 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 state (de)serialization namespacex
statistical distribution statistical distribution simulation::random
statistics statistics counter · math · math::statistics
stdin strongly connected component struct::graph::op
struct struct struct::pool · struct::record
structure structure control
structured queries structured queries treeql
style subgraph struct::graph · struct::graph::op
subject subject hook
submitbutton javascript
subscriber subscriber hook
subsequence
Keywords: T
table table doctools::toc · doctools::toc::export · doctools::toc::import · html · report
table of contents tar tar
tcl tcl math::bigfloat · math::bignum · math::decimal
Tcl module TclOO oo::util
TCLPARAM TCLPARAM pt::peg::to::tclparam
TDPL text bench::in · bench::out::text · doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export
text comparison text comparison soundex
text conversion text expansion textutil::expander
text likeness text likeness soundex
text processing 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 tie tie · tie
tif tif tiff
tiff tiff exif · tiff
tile map::slippy::cache · map::slippy::fetcher
time time ntp_time
timestamp Tk tcl::chan::textwindow
tls tls comm · imap4 · pop3 · pop3d · smtp · transfer::connect · transfer::receiver · transfer::transmitter
TMML - doctools · doctools::idx · doctools::idx · doctools::toc · doctools::toc · dtplite · mpexpand + doctools · doctools::idx · doctools::idx · doctools::toc · doctools::toc · dtplite · dtplite · mpexpand
toc doctoc_intro · doctoc_plugin_apiref · doctools::toc · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import::doctoc · doctools::toc::import::json @@ -3749,21 +3752,21 @@ tree grammar::me::cpu::gasm · grammar::me::util · htmlparse · struct::queue · struct::stack · struct::tree · struct::tree_v1 · treeql
tree query language tree query language treeql
tree walking tree walking page_util_flow · page_util_norm_lemon · page_util_norm_peg
TreeQL TreeQL treeql
trimming
Keywords: U
uevent uevent hook
unbind unicode stringprep · stringprep::data · unicode · unicode::data
union union struct::disjointset · struct::set
unit units
unknown hooking unknown hooking namespacex
untie 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 urn uri_urn
utilities utilities namespacex
uuencode uuencode
UUID UUID uuid
Keywords: V @@ -3936,31 +3939,31 @@ x.209 asn
x.500 x.500 ldap
xml xml xsxp
xor tcl::transform::otp
XPath XPath treeql
XSLT XSLT treeql
Keywords: Y @@ -3997,11 +4000,11 @@ zlib tcl::transform::zlib
zoom zoom map::slippy · map::slippy::cache · map::slippy::fetcher
Index: embedded/www/tcllib/files/apps/dtplite.html ================================================================== --- embedded/www/tcllib/files/apps/dtplite.html +++ embedded/www/tcllib/files/apps/dtplite.html @@ -98,15 +98,18 @@ -->
[ - Main Table Of Contents + Tcllib Home +| Main Table Of Contents | Table Of Contents | Keyword Index -| Home -]
+| Categories +| Modules +| Applications + ]

dtplite(n) 1.0 tcllib "Documentation toolbox"

Name

dtplite - Lightweight DocTools Markup Processor

Description

-

The application described by this document, dtplite, is the +

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 +

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

USE CASES

-

dtplite was written with the following three use cases in +

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 @@ -174,11 +177,11 @@ 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
+
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 @@ -197,25 +200,25 @@ 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
+
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
+
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
+
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 Index: embedded/www/tcllib/files/apps/nns.html ================================================================== --- embedded/www/tcllib/files/apps/nns.html +++ embedded/www/tcllib/files/apps/nns.html @@ -98,15 +98,18 @@ -->

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

nns(n) 1.1 tcllib "Name service facility"

Name

nns - Name service facility, Commandline Client Application

Table Of Contents

Index: embedded/www/tcllib/files/apps/nnsd.html ================================================================== --- embedded/www/tcllib/files/apps/nnsd.html +++ embedded/www/tcllib/files/apps/nnsd.html @@ -98,15 +98,18 @@ -->
[ - Main Table Of Contents + Tcllib Home +| Main Table Of Contents | Table Of Contents | Keyword Index -| Home -]
+| Categories +| Modules +| Applications + ]

nnsd(n) 1.0.1 tcllib "Name service facility"

Name

nnsd - Name service facility, Commandline Server Application

Table Of Contents

Index: embedded/www/tcllib/files/apps/nnslog.html ================================================================== --- embedded/www/tcllib/files/apps/nnslog.html +++ embedded/www/tcllib/files/apps/nnslog.html @@ -98,15 +98,18 @@ -->
[ - Main Table Of Contents + Tcllib Home +| Main Table Of Contents | Table Of Contents | Keyword Index -| Home -]
+| Categories +| Modules +| Applications + ]

nnslog(n) 1.0 tcllib "Name service facility"

Name

nnslog - Name service facility, Commandline Logging Client Application

Table Of Contents

Index: embedded/www/tcllib/files/apps/page.html ================================================================== --- embedded/www/tcllib/files/apps/page.html +++ embedded/www/tcllib/files/apps/page.html @@ -98,15 +98,18 @@ -->
[ - Main Table Of Contents + Tcllib Home +| Main Table Of Contents | Table Of Contents | Keyword Index -| Home -]
+| Categories +| Modules +| Applications + ]

page(n) 1.0 tcllib "Development Tools"

Name

page - Parser Generator

Table Of Contents

@@ -347,11 +350,11 @@

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

lemon

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

treeser

Interprets the input as the serialization of a struct::tree. It is validated as such, @@ -460,14 +463,14 @@

See Also

page::pluginmgr

Category

Page Parser Generator

Index: embedded/www/tcllib/files/apps/tcldocstrip.html ================================================================== --- embedded/www/tcllib/files/apps/tcldocstrip.html +++ embedded/www/tcllib/files/apps/tcldocstrip.html @@ -98,15 +98,18 @@ -->
[ - Main Table Of Contents + Tcllib Home +| Main Table Of Contents | Table Of Contents | Keyword Index -| Home -]
+| Categories +| Modules +| Applications + ]

tcldocstrip(n) 1.0 tcllib "Textprocessing toolbox"

Name

tcldocstrip - Tcl-based Docstrip Processor

Table Of Contents

Index: embedded/www/tcllib/files/modules/aes/aes.html ================================================================== --- embedded/www/tcllib/files/modules/aes/aes.html +++ embedded/www/tcllib/files/modules/aes/aes.html @@ -98,15 +98,18 @@ -->
[ - Main Table Of Contents + Tcllib Home +| Main Table Of Contents | Table Of Contents | Keyword Index -| Home -]
+| Categories +| Modules +| Applications + ]

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

Name

aes - Implementation of the AES block cipher

Table Of Contents

Index: embedded/www/tcllib/files/modules/amazon-s3/S3.html ================================================================== --- embedded/www/tcllib/files/modules/amazon-s3/S3.html +++ embedded/www/tcllib/files/modules/amazon-s3/S3.html @@ -91,21 +91,24 @@ } --> -
[ - Main Table Of Contents + Tcllib Home +| Main Table Of Contents | Table Of Contents | Keyword Index -| Home -]
+| Categories +| Modules +| Applications + ]

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

Name

S3 - Amazon S3 Web Service Interface

Table Of Contents

@@ -230,11 +233,11 @@

  • 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/). +from Tcllib (available at http://core.tcl.tk/tcllib/). Note that S3::Configure is required for S3::REST to work due to the authentication portion, so we put that in the "lowest level."

  • The next layer parses the results of calls, allowing for functionality such as uploading only changed files, synchronizing directories, and so on. This layer depends on the TclXML package as well as the @@ -1254,8 +1257,8 @@

Category

Networking

Index: embedded/www/tcllib/files/modules/amazon-s3/xsxp.html ================================================================== --- embedded/www/tcllib/files/modules/amazon-s3/xsxp.html +++ embedded/www/tcllib/files/modules/amazon-s3/xsxp.html @@ -91,21 +91,24 @@ } --> -
[ - Main Table Of Contents + Tcllib Home +| Main Table Of Contents | Table Of Contents | Keyword Index -| Home -]
+| Categories +| Modules +| Applications + ]

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

Name

xsxp - eXtremely Simple Xml Parser

Table Of Contents

@@ -230,14 +233,14 @@ Tcllib SF Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

Category

Text processing

Index: embedded/www/tcllib/files/modules/asn/asn.html ================================================================== --- embedded/www/tcllib/files/modules/asn/asn.html +++ embedded/www/tcllib/files/modules/asn/asn.html @@ -98,15 +98,18 @@ -->
[ - Main Table Of Contents + Tcllib Home +| Main Table Of Contents | Table Of Contents | Keyword Index -| Home -]
+| Categories +| Modules +| Applications + ]

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

Name

asn - ASN.1 BER encoder/decoder

Table Of Contents

@@ -489,11 +492,11 @@ Tcllib SF Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

Category

Networking