Tcl Library Source Code

  - <a name='1'></a>__xsxp::parse__ *xml*

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

      * The first element is the name of the tag\.

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

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

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

  - <a name='2'></a>__xsxp::fetch__ *pxml* *path* ?*part*?

    *pxml* is a parsed XML, as returned from xsxp::parse\. *path* is a list
    of element tag names\. Each element is the name of a child to look up,
    optionally followed by a hash \("\#"\) and a string of digits\. An empty list or
    an initial empty element selects *pxml*\. If no hash sign is present, the

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

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

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

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

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

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

# <a name='section3'></a>Code map

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

    valid *string*, and __False__ otherwise\. In the latter case an error
    message describing the problem with the input is stored into the variable
    named by *mvar*\. The variable is not touched if the input was found to be
    valid\.

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

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

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

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

# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *base32* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

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

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

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

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

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

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

# <a name='section3'></a>Code map

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

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

      * string

        A list containing three elements:

          + The constant string __string__, denoting the type of the value\.

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

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

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

      * integer

    not yet known the command prefix specified during construction of the cache
    object is used to ask for this information\.

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

      1. The string __set__, the *key*, and the value\.

      1. The string __unset__, and the *key*\.

    These two possibilities are used to either signal the value for the *key*,
    or that the *key* has no value defined for it\. The latter is distinct from
    the cache not knowing about the *key*\.

    For a cache object configured to be fully asynchronous \(default\) the
    *donecmdprefix* is always run in an idle\-handler, decoupling it from the

    result, as is if the script caused the error\. Any other return will evaluate
    the script in *buffer* as normal\. For compatibility with 3\.2,
    __break__ and __return \-code break__ *result* is supported, acting
    similarly to __return \{\}__ and __return \-code return__ *result*\.

    Examples:

      1. augmenting a command

    % ::comm::comm send \[::comm::comm self\] pid
    5013
    % ::comm::comm hook eval \{puts "going to execute $buffer"\}
    % ::comm::comm send \[::comm::comm self\] pid
    going to execute pid
    5013

      1. short circuiting a command

    % ::comm::comm hook eval \{puts "would have executed $buffer"; return 0\}
    % ::comm::comm send \[::comm::comm self\] pid
    would have executed pid
    0

      1. Replacing double eval semantics

    % ::comm::comm send \[::comm::comm self\] llength \{a b c\}
    wrong \# args: should be "llength list"
    % ::comm::comm hook eval \{return \[uplevel \#0 $buffer\]\}
    return \[uplevel \#0 $buffer\]
    % ::comm::comm send \[::comm::comm self\] llength \{a b c\}
    3

      1. Using a slave interpreter

    % interp create foo
    % ::comm::comm hook eval \{return \[foo eval $buffer\]\}
    % ::comm::comm send \[::comm::comm self\] set myvar 123
    123
    % set myvar
    can't read "myvar": no such variable
    % foo eval set myvar
    123

      1. Using a slave interpreter \(double eval\)

    % ::comm::comm hook eval \{return \[eval foo eval $buffer\]\}

      1. Subverting the script to execute

    % ::comm::comm hook eval \{
        switch \-\- $buffer \{
            a \{return A\-OK\}
            b \{return B\-OK\}
            default \{error "$buffer is a no\-no"\}
        \}

    __return\(\)__\.

    This hook is invoked after collecting a complete reply script from a remote
    but *before* evaluating it\. This allows complete control over the
    processing of replies to sent commands\. The reply *buffer* is in one of
    the following forms

      * return result

      * return \-code code result

      * return \-code code \-errorinfo info \-errorcode ecode msg

    For safety reasons, this is decomposed\. The return result is in *ret*, and
    the return switches are in the return array:

      * *return\(\-code\)*

      * *return\(\-errorinfo\)*

      * *return\(\-errorcode\)*

    Any of these may be the empty string\. Modifying these four variables can
    change the return value, whereas modifying *buffer* has no effect\.

  - __callback__

    Variables: __chan__, __id__, __buffer__, __ret__, and

[//000000001]: # (doctools \- Documentation tools)
[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>)
[//000000004]: # (doctools\(n\) 1\.5\.1 tcllib "Documentation tools")

<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../../toc.md">Table Of Contents</a> &#124; <a
href="../../../../index.md">Keyword Index</a> &#124; <a
href="../../../../toc0.md">Categories</a> &#124; <a
href="../../../../toc1.md">Modules</a> &#124; <a
href="../../../../toc2.md">Applications</a> ] <hr>

  - [Category](#category)

  - [Copyright](#copyright)

# <a name='synopsis'></a>SYNOPSIS

package require Tcl 8\.2  
package require doctools ?1\.5\.1?  

[__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1)  
[__::doctools::help__](#2)  
[__::doctools::search__ *path*](#3)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#4)  
[*objectName* __configure__](#5)  
[*objectName* __configure__ *option*](#6)  

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

           * string *path*

             The path of the include file as specified in the include directive
             being processed\.

         The result of the command will be a 5\-element list containing

           1) A boolean flag indicating the success \(__True__\) or failure
              \(__False__\) of the operation\.

           1) In case of success the contents of the included file, and the
              empty string otherwise\.

           1) The resolved, i\.e\. absolute path of the included file, if
              possible, or the unchanged *path* argument\. This is for display
              in an error message, or as the *currentfile* argument of another
              call to __IncludeFile__ should this file contain more files\.

           1) In case of success an empty string, and for failure a code
              indicating the reason for it, one of

                * notfound

                  The specified file could not be found\.

                * notread

                  The specified file was found, but not be read into memory\.

           1) An empty string in case of success of a __notfound__ failure,
              and an additional error message describing the reason for a
              __notread__ error in more detail\.

  1. A plugin has to provide one command, with the signature shown below\.

       - <a name='17'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration*

         Whenever an import manager of
         __[doctools::idx](idx\_container\.md)__ has to parse input for an

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section4'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__

             The identifier of the reference is interpreted as an url, referring
             to some external location, like a website, etc\.

  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

           * string *path*

             The path of the include file as specified in the include directive
             being processed\.

         The result of the command will be a 5\-element list containing

           1) A boolean flag indicating the success \(__True__\) or failure
              \(__False__\) of the operation\.

           1) In case of success the contents of the included file, and the
              empty string otherwise\.

           1) The resolved, i\.e\. absolute path of the included file, if
              possible, or the unchanged *path* argument\. This is for display
              in an error message, or as the *currentfile* argument of another
              call to __IncludeFile__ should this file contain more files\.

           1) In case of success an empty string, and for failure a code
              indicating the reason for it, one of

                * notfound

                  The specified file could not be found\.

                * notread

                  The specified file was found, but not be read into memory\.

           1) An empty string in case of success of a __notfound__ failure,
              and an additional error message describing the reason for a
              __notread__ error in more detail\.

  1. A plugin has to provide one command, with the signature shown below\.

       - <a name='17'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration*

         Whenever an import manager of
         __[doctools::toc](\.\./doctools/doctoc\.md)__ has to parse input

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

    canonical serialization of this unified table of contents\.

    Title and label of the resulting table are taken from the table contained in
    *serialb*\.

    The whole table and its divisions are merged recursively in the same manner:

      1. All reference elements which occur in both divisions \(identified by
         their label\) are unified with document id's and descriptions taken from
         the second table\.

      1. All division elements which occur in both divisions \(identified by
         their label\) are unified with the optional document id taken from the
         second table, if any, or from the first if none is in the second\. The
         elements in the division are merged recursively using the same
         algorithm as described in this list\.

      1. Type conflicts between elements, i\.e\. finding two elements with the
         same label but different types result in a merge error\.

      1. All elements found in the second division but not in the first are
         added to the end of the list of elements in the merge result\.

    For the specification of regular and canonical serializations see the
    section [ToC serialization format](#section3)\.

# <a name='section3'></a>ToC serialization format

Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc\.

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__

  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

# <a name='section4'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

  - <a name='22'></a>__::fileutil::tempdir__

    The command returns the path of a directory where the caller can place
    temporary files, such as "/tmp" on Unix systems\. The algorithm we use to
    find the correct directory is as follows:

      1. The directory set by an invokation of __::fileutil::tempdir__ with
         an argument\. If this is present it is tried exclusively and none of the
         following item are tried\.

      1. The directory named in the TMPDIR environment variable\.

      1. The directory named in the TEMP environment variable\.

      1. The directory named in the TMP environment variable\.

      1. A platform specific location:

           * Windows

             "C:\\TEMP", "C:\\TMP", "\\TEMP", and "\\TMP" are tried in that order\.

           * \(classic\) Macintosh

  - <a name='3'></a>__::ftp::Cd__ *handle* *directory*

    This command changes the current working directory on the ftp server to a
    specified target *directory*\. The command returns 1 if the current working
    directory was successfully changed to the specified directory or 0 if it
    fails\. The target directory can be

      * a subdirectory of the current directory,

      * Two dots, __\.\.__ \(as an indicator for the parent directory of the
        current directory\)

      * or a fully qualified path to a new working directory\.

  - <a name='4'></a>__::ftp::Pwd__ *handle*

    This command returns the complete path of the current working directory on
    the ftp server, or an empty string in case of an error\.

  - <a name='5'></a>__::ftp::Type__ *handle* ?__ascii&#124;binary&#124;tenex__?

    The result of this method has to be semantically identical over all
    implementations of the __grammar::fa__ interface\. This is what will
    enable us to copy automatons between different implementations of the same
    interface\.

    The result is a list of three elements with the following structure:

      1. The constant string __grammar::fa__\.

      1. A list containing the names of all known input symbols\. The order of
         elements in this list is not relevant\.

      1. The last item in the list is a dictionary, however the order of the
         keys is important as well\. The keys are the states of the serialized
         FA, and their order is the order in which to create the states when
         deserializing\. This is relevant to preserve the order relationship
         between states\.

         The value of each dictionary entry is a list of three elements
         describing the state in more detail\.

           1) A boolean flag\. If its value is __true__ then the state is a
              start state, otherwise it is not\.

           1) A boolean flag\. If its value is __true__ then the state is a
              final state, otherwise it is not\.

           1) The last element is a dictionary describing the transitions for
              the state\. The keys are symbols \(or the empty string\), and the
              values are sets of successor states\.

    Assuming the following FA \(which describes the life of a truck driver in a
    very simple way :\)

        Drive \-\- yellow \-\-> Brake \-\- red \-\-> \(Stop\) \-\- red/yellow \-\-> Attention \-\- green \-\-> Drive
        \(\.\.\.\) is the start state\.

  - <a name='19'></a>__::grammar::fa::op::simplifyRegexp__ *regexp*

    This command simplifies a regular expression by applying the following
    algorithm first to the main expression and then recursively to all
    sub\-expressions:

      1. Convert the expression into a finite automaton\.

      1. Minimize the automaton\.

      1. Convert the automaton back to a regular expression\.

      1. Choose the shorter of original expression and expression from the
         previous step\.

# <a name='section3'></a>EXAMPLES

# <a name='section4'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *grammar\_fa* of the

  - <a name='6'></a>__::grammar::me::cpu::gasm::Inline__ *t* *node* *label*

    This command links an instruction sequence created by an earlier begin/done
    pair into the current instruction sequence\.

    To this end it

      1. reads the instruction references from the attributes
         __gas::entry__, __gas::exit::ok__, and __gas::exit::fail__
         from the node *n* of the tree *t* and makes them available to
         assembler und the labels *label*/entry, *label*/exit::ok, and
         *label*/exit::fail respectively\.

      1. Creates an arc from the *anchor* to the node labeled *label*/entry,
         and tags it with the current condition code\.

      1. Makes the node labeled *label*/exit/ok the new *anchor*\.

    The command returns the empty string as its result\.

  - <a name='7'></a>__::grammar::me::cpu::gasm::Cmd__ *cmd* ?*arg*\.\.\.?

    This is the basic command to add instructions to the graph\. It creates a new
    instruction of type *cmd* with the given arguments *arg*\.\.\. If the

    and the line/col information is computed based on the characters encountered
    and the data in the variables *lvar* and *cvar*\.

  - <a name='24'></a>*meName* __run__ ?*n*?

    This methods causes the engine to execute match instructions until either

      * *n* instructions have been executed, or

      * a halt instruction was executed, or

      * the input queue is empty and the code is asking for more tokens to
        process\.

    If no limit *n* was set only the last two conditions are checked for\.

  - <a name='25'></a>*meName* __pull__ *nextcmd*

    This method implements pull\-style operation of the machine\. It causes it to
    execute match instructions until either a halt instruction is reached, or

    This method takes the state value of a ME virtual machine as stored in the
    variable named by *statevar*, executes a number of instructions and stores
    the state resulting from their modifications back into the variable\.

    The execution loop will run until either

      * *n* instructions have been executed, or

      * a halt instruction was executed, or

      * the input queue is empty and the code is asking for more tokens to
        process\.

    If no limit *n* was set only the last two conditions are checked for\.

## <a name='subsection1'></a>MATCH PROGRAM REPRESENTATION

A match program is represented by nested Tcl list\. The first element, *asm*,
is a list of integer numbers, the instructions to execute, and their arguments\.

    The result of this method has to be semantically identical over all
    implementations of the __grammar::peg__ interface\. This is what will
    enable us to copy grammars between different implementations of the same
    interface\.

    The result is a list of four elements with the following structure:

      1. The constant string __grammar::peg__\.

      1. A dictionary\. Its keys are the names of all known nonterminal symbols,
         and their associated values are the parsing expressions describing
         their sentennial structure\.

      1. A dictionary\. Its keys are the names of all known nonterminal symbols,
         and their associated values hints to a matcher regarding the semantic
         values produced by the symbol\.

      1. The last item is a parsing expression, the *start expression* of the
         grammar\.

    Assuming the following PEG for simple mathematical expressions

    Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'
    Sign       <\- '\+' / '\-'
    Number     <\- Sign? Digit\+
    Expression <\- '\(' Expression '\)' / \(Factor \(MulOp Factor\)\*\)

        hook bind $s $h $o $binding

    is called during the execution of

        hook call $s $h

      1. No binding is ever called after it is deleted\.

      1. When a binding is called, the most recently given command prefix is
         always used\.

      1. The set of observers whose bindings are to be called is determined when
         this method begins to execute, and does not change thereafter, except
         that deleted bindings are not called\.

    In particular:

      1. If __$o__s binding to __$s__ and __$h__ is deleted, and
         __$o__s binding has not yet been called during this execution of

             hook call $s $h

         it will not be called\. \(Note that it might already have been called;
         and in all likelihood, it is probably deleting itself\.\)

      1. If __$o__ changes the command prefix that's bound to __$s__ and
         __$h__, and if __$o__s binding has not yet been called during
         this execution of

             hook call $s $h

         the new binding will be called when the time comes\. \(But again, it is
         probably __$o__s binding that is is making the change\.\)

      1. If a new observer is bound to __$s__ and __$h__, its binding
         will not be called until the next invocation of

             hook call $s $h

  - <a name='2'></a>__hook__ __call__ *subject* *hook* ?*args*\.\.\.?

    This command is called when the named *subject* wishes to call the named
    *hook*\. All relevant bindings are called with the specified arguments in
    the global namespace\. Note that the bindings are called synchronously,
    before the command returns; this allows the *args* to include references
    to entities that will be cleaned up as soon as the hook has been called\.

    The order in which the bindings are called is not guaranteed\. If sequence
    among observers must be preserved, define one observer and have its bindings
    call the other callbacks directly in the proper sequence\.

    Because the __hook__ mechanism is intended to support loose coupling, it
    is presumed that the *subject* has no knowledge of the observers, nor any
    expectation regarding return values\. This has a number of implications:

      1. __hook call__ returns the empty string\.

      1. Normal return values from observer bindings are ignored\.

      1. Errors and other exceptional returns propagate normally by default\.
         This will rarely be what is wanted, because the subjects usually have
         no knowledge of the observers and will therefore have no particular
         competence at handling their errors\. That makes it an application
         issue, and so applications will usually want to define an
         __\-errorcommand__\.

    If the __\-errorcommand__ configuration option has a non\-empty value, its
    value will be invoked for all errors and other exceptional returns in
    observer bindings\. See __hook configure__, below, for more information
    on configuration options\.

  - <a name='3'></a>__hook__ __forget__ *object*

    This command deletes any existing bindings in which the named *object*
    appears as either the *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)* or the
    *[observer](\.\./\.\./\.\./\.\./index\.md\#observer)*\. Bindings deleted by this
    method will never be called again\. In particular,

      1. If an observer is forgotten during a call to __hook call__, any
         uncalled binding it might have had to the relevant subject and hook
         will *not* be called subsequently\.

      1. If a subject __$s__ is forgotten during a call to

             hook call $s $h

         then __hook call__ will return as soon as the current binding
         returns\. No further bindings will be called\.

  - <a name='4'></a>__hook__ __cget__ *option*

    This command returns the value of one of the __hook__ command's
    configuration options\.

  - <a name='5'></a>__hook__ __configure__ __option__ *value* \.\.\.

    This command sets the value of one or more of the __hook__ command's
    configuration options:

      * __\-errorcommand__ *cmdPrefix*

        If the value of this option is the empty string, "", then errors and
        other exception returns in binding scripts are propagated normally\.
        Otherwise, it must be a command prefix taking three additional
        arguments:

          1. a 4\-element list \{subject hook arglist observer\},

          1. the result string, and

          1. the return options dictionary\.

        Given this information, the __\-errorcommand__ can choose to log the
        error, call __interp bgerror__, delete the errant binding \(thus
        preventing the error from arising a second time\) and so forth\.

      * __\-tracecommand__ *cmdPrefix*

        The option's value should be a command prefix taking four arguments:

          1. a *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*,

          1. a *[hook](\.\./\.\./\.\./\.\./index\.md\#hook)*,

          1. a list of the hook's argument values, and

          1. a list of *objects* the hook was called for\.

        The command will be called for each hook that is called\. This allows the
        application to trace hook execution for debugging purposes\.

# <a name='section4'></a>Example

The __::model__ module calls the <Update> hook in response to commands that

  - <a name='62'></a>__::html::doctype__ *id*

    This procedure can be used to build the standard DOCTYPE declaration string\.
    It will return the standard declaration string for the id, or throw an error
    if the id is not known\. The following id's are defined:

      1. HTML32

      1. HTML40

      1. HTML40T

      1. HTML40F

      1. HTML401

      1. HTML401T

      1. HTML401F

      1. XHTML10S

      1. XHTML10T

      1. XHTML10F

      1. XHTML11

      1. XHTMLB

# <a name='section2'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *html* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

    modifications are handled by specialized methods such as __apply__ or
    __commit__\. Detailed format should not be used directly by programs\.

    Internally, modifications are represented as a list of elements, each
    element has one of the following formats \(which match the corresponding LDAP
    operations\):

      1. \{__add__ \{attr1 \{val1\.\.\.valn\} attr2 \{\.\.\.\} \.\.\.\}\}

         Addition of a new entry\.

      1. \{__mod__ \{modop \{attr1 ?val1\.\.\.valn?\} attr2 \.\.\.\} \{modop \.\.\.\} \.\.\.\}

         Modification of one or more attributes and/or values, where <modop> can
         be __modadd__, __moddel__ or __modrepl__ \(see the LDAP
         modify operation\)\.

      1. \{__del__\}

         Deletion of an old entry\.

      1. \{__modrdn__ newrdn deleteoldrdn ?newsuperior?\}

         Renaming of an entry\.

## <a name='subsection2'></a>Entry Options

No option is defined by this class\.

## <a name='subsection3'></a>Methods for all kinds of entries

    $\{log\}::logproc notice logtoserver

    Trace logs are slightly different: instead of a plain text argument, the
    argument provided to the logproc is a dictionary consisting of the
    __enter__ or __leave__ keyword along with another dictionary of
    details about the trace\. These include:

      * __proc__ \- Name of the procedure being traced\.

      * __level__ \- The stack level for the procedure invocation \(from
        __[info](\.\./\.\./\.\./\.\./index\.md\#info)__ __level__\)\.

      * __script__ \- The name of the file in which the procedure is defined,
        or an empty string if defined in interactive mode\.

      * __caller__ \- The name of the procedure calling the procedure being
        traced, or an empty string if the procedure was called from the global
        scope \(stack level 0\)\.

      * __procargs__ \- A dictionary consisting of the names of arguments to
        the procedure paired with values given for those arguments
        \(__enter__ traces only\)\.

      * __status__ \- The Tcl return code \(e\.g\. __ok__, __continue__,
        etc\.\) \(__leave__ traces only\)\.

      * __result__ \- The value returned by the procedure \(__leave__
        traces only\)\.

  - <a name='26'></a>__$\{log\}::services__

    Returns a list of the registered logging services which are children of this
    service\.

  - <a name='27'></a>__$\{log\}::servicename__

    *tile* from the cache\. The tile identifier is a list containing three
    elements, the zoom level, row, and column number of the tile, in this order\.

    The command refix *donecmd* will be invoked when the cache either knows
    the image for the tile or that no image will forthcoming\. It will be invoked
    with either 2 or 3 arguments, i\.e\.

      1. The string __set__, the *tile*, and the image\.

      1. The string __unset__, and the *tile*\.

    These two possibilities are used to either signal the image for the
    *tile*, or that the *tile* has no image defined for it\.

    When the cache has no information about the tile it will invoke the
    *provider* command prefix specified during its construction, adding three
    arguments: The string __get__, the *tile*, and a callback into the

    specified *tile*\. The tile identifier is a list containing three elements,
    the zoom level, row, and column number of the tile, in this order\.

    The command refix *donecmd* will be invoked when the fetcher either knows
    the image for the tile or that no image will forthcoming\. It will be invoked
    with either 2 or 3 arguments, i\.e\.

      1. The string __set__, the *tile*, and the image\.

      1. The string __unset__, and the *tile*\.

    These two possibilities are used to either signal the image for the
    *tile*, or that the *tile* has no image defined for it\.

# <a name='section3'></a>References

  1. [http://wiki\.openstreetmap\.org/wiki/Main\_Page](http://wiki\.openstreetmap\.org/wiki/Main\_Page)

# <a name='section4'></a>COMPARISONS

  - <a name='16'></a>__iszero__ *x*

    Returns 1 if *x* is :

      * a BigFloat close enough to zero to raise "divide by zero"\.

      * the integer 0\.

    See here how numbers that are close to zero are converted to strings:

        tostr \[fromstr 0\.001\] ; \# \-> 0\.e\-2
        tostr \[fromstr 0\.000000\] ; \# \-> 0\.e\-5
        tostr \[fromstr \-0\.000001\] ; \# \-> 0\.e\-5
        tostr \[fromstr 0\.0\] ; \# \-> 0\.

  - <a name='8'></a>__::math::calculus::qk15\_detailed__ *xstart* *xend* *func* *nosteps*

    Determine the integral of the given function using the Gauss\-Kronrod 15
    points quadrature rule\. The interval for the integration is \[*xstart*,
    *xend*\]\. The procedure returns a list of four values:

      * The estimate of the integral over the specified interval \(I\)\.

      * An estimate of the absolute error in I\.

      * The estimate of the integral of the absolute value of the function over
        the interval\.

      * The estimate of the integral of the absolute value of the function minus
        its mean over the interval\.

    The remaining arguments are:

      * *func*

        Function to be integrated\. It should take one single argument\.

    Convert *decimal* into a string representing the number in base 10\.

  - <a name='3'></a>__::math::decimal::setVariable__ *variable* *setting*

    Sets the *variable* to *setting*\. Valid variables are:

      * *rounding* \- Method of rounding to use during rescale\. Valid methods
        are round\_half\_even, round\_half\_up, round\_half\_down, round\_down,
        round\_up, round\_floor, round\_ceiling\.

      * *precision* \- Maximum number of digits allowed in mantissa\.

      * *extended* \- Set to 1 for extended mode\. 0 for simplified mode\.

      * *maxExponent* \- Maximum value for the exponent\. Defaults to 999\.

      * *minExponent* \- Minimum value for the exponent\. Default to \-998\.

  - <a name='4'></a>__::math::decimal::add__ *a* *b*

  - <a name='5'></a>__::math::decimal::\+__ *a* *b*

    Return the sum of the two decimals *a* and *b*\.

    Checks if two objects \(vector or matrix\) have conforming shapes, that is if
    they can be applied in an operation like addition or matrix multiplication\.

      * string *type*

        Type of check:

          + "shape" \- the two objects have the same shape \(for all element\-wise
            operations\)

          + "rows" \- the two objects have the same number of rows \(for use as A
            and b in a system of linear equations *Ax = b*

          + "matmul" \- the first object has the same number of columns as the
            number of rows of the second object\. Useful for matrix\-matrix or
            matrix\-vector multiplication\.

      * list *obj1*

        First vector or matrix \(left operand\)

      * list *obj2*

        A column vector

      * list *scope*

        If not provided, the operation is performed on all rows/columns of A if
        provided, it is expected to be the list \{imin imax jmin jmax\} where:

          + *imin* Minimum row index

          + *imax* Maximum row index

          + *jmin* Minimum column index

          + *jmax* Maximum column index

  - <a name='59'></a>__::math::linearalgebra::dgetrf__ *matrix*

    Computes an LU factorization of a general matrix, using partial, pivoting
    with row interchanges\. Returns the permutation vector\.

    The factorization has the form

    Computes the machine parameters\.

  - <a name='6'></a>*objectname* __get__ *key*

    Returns the value corresponding with given key\. The following is the list of
    available keys\.

      * \-epsilon : smallest value so that 1\+epsilon>1 is false

      * \-rounding : The rounding mode used on the machine\. The rounding occurs
        when more than t digits would be required to represent the number\. Two
        modes can be determined with the current system : "chop" means than only
        t digits are kept, no matter the value of the number "proper" means that
        another rounding mode is used, be it "round to nearest", "round up",
        "round down"\.

      * \-basis : the basis of the floating\-point representation\. The basis is
        usually 2, i\.e\. binary representation \(for example IEEE 754 machines\),
        but some machines \(like HP calculators for example\) uses 10, or 16,
        etc\.\.\.

      * \-mantissa : the number of bits in the mantissa

      * \-exponentmax : the largest positive exponent before overflow occurs

      * \-exponentmin : the largest negative exponent before \(gradual\) underflow
        occurs

      * \-vmax : largest positive value before overflow occurs

      * \-vmin : largest negative value before \(gradual\) underflow occurs

  - <a name='7'></a>*objectname* __tostring__

    Return a report for machine parameters\.

  - <a name='8'></a>*objectname* __print__

    or > 1 extrapolate along the line between the two point\.

  - <a name='11'></a>__::math::geometry::octant__ *point*

    Compute the octant of the circle the point is in and return it as the result
    of the command\. The possible results are

      1. east

      1. northeast

      1. north

      1. northwest

      1. west

      1. southwest

      1. south

      1. southeast

    Each octant is the arc of the circle \+/\- 22\.5 degrees from the cardinal
    direction the octant is named for\.

  - <a name='12'></a>__::math::geometry::rect__ *nw* *se*

    Construct a rectangle from its northwest and southeast corners and return it

    These procedures operate by making the change of variable u=\(x\-a\)\*\*\(1\-gamma\)
    \(__romberg\_powerLawLower__\) or u=\(b\-x\)\*\*\(1\-gamma\)
    \(__romberg\_powerLawUpper__\)\.

    To summarize the meaning of gamma:

      * If f\(x\) ~ x\*\*\(\-a\) \(0 < a < 1\), use gamma = a

      * If f'\(x\) ~ x\*\*\(\-b\) \(0 < b < 1\), use gamma = b

  - __romberg\_sqrtSingLower__ and __romberg\_sqrtSingUpper__

    These procedures behave identically to __romberg\_powerLawLower__ and
    __romberg\_powerLawUpper__ for the common case of *gamma*=0\.5; that is,
    they integrate a function with an inverse square root singularity at one end
    of the interval\. They have a simpler implementation involving square roots

      * boolean *intercept*

        \- \(Optional\) compute the intercept \(1, default\) or fit to a line through
        the origin \(0\)

        The result consists of the following list:

          + \(Estimate of\) Intercept A

          + \(Estimate of\) Slope B

          + Standard deviation of Y relative to fit

          + Correlation coefficient R2

          + Number of degrees of freedom df

          + Standard error of the intercept A

          + Significance level of A

          + Standard error of the slope B

          + Significance level of B

  - <a name='29'></a>__::math::statistics::linear\-residuals__ *xdata* *ydata* *intercept*

    Determine the difference between actual data and predicted from the linear
    model\.

    Returns a list of the differences between the actual data and the predicted

    and each point satisfies

        yi = b0 \+ b1 \* xi1 \+ b2 \* xi2 \+ \.\.\. \+ bN \* xiN \+ Residual\_i

    The procedure returns a list with the following elements:

      * The r\-squared statistic

      * The adjusted r\-squared statistic

      * A list containing the estimated coefficients b1, \.\.\. bN, b0 \(The
        constant b0 comes last in the list\.\)

      * A list containing the standard errors of the coefficients

      * A list containing the 95% confidence bounds of the coefficients, with
        each set of bounds returned as a list with two values

    Arguments:

      * list *weights\_and\_values*

        A list consisting of: the weight for the first observation, the data for
        the first observation \(as a sublist\), the weight for the second

The __mime__ library package provides the commands to create and manipulate
MIME body parts\.

  - <a name='1'></a>__::mime::initialize__ ?__\-canonical__ *type/subtype* ?__\-param__ \{*key value*\}\.\.\.? ?__\-encoding__ *value*? ?__\-header__ \{*key value*\}\.\.\.?? \(__\-file__ *name* &#124; __\-string__ *value* &#124; __\-parts__ \{*token1* \.\.\. *tokenN*\}\)

    This command creates a MIME part and returns a token representing it\.

      * If the __\-canonical__ option is present, then the body is in
        canonical \(raw\) form and is found by consulting either the
        __\-file__, __\-string__, or __\-parts__ option\.

        In addition, both the __\-param__ and __\-header__ options may
        occur zero or more times to specify __Content\-Type__ parameters
        \(e\.g\., __charset__\) and header keyword/values \(e\.g\.,
        __Content\-Disposition__\), respectively\.

        Also, __\-encoding__, if present, specifies the
        __Content\-Transfer\-Encoding__ when copying the body\.

      * If the __\-canonical__ option is not present, then the MIME part
        contained in either the __\-file__ or the __\-string__ option is
        parsed, dynamically generating subordinates as appropriate\.

  - <a name='2'></a>__::mime::finalize__ *token* ?__\-subordinates__ __all__ &#124; __dynamic__ &#124; __none__?

    This command destroys the MIME part represented by *token*\. It returns an
    empty string\.

    If the __\-subordinates__ option is present, it specifies which

    This command assumes the *tree* object contains for a parsing expression
    grammar\. It normalizes this tree in place\. The result is called a
    *Normalized PE Grammar Tree*\.

    The following operations are performd

      1. The data for all terminals is stored in their grandparental nodes\. The
         terminal nodes and their parents are removed\. Type information is
         dropped\.

      1. All nodes which have exactly one child are irrelevant and are removed,
         with the exception of the root node\. The immediate child of the root is
         irrelevant as well, and removed as well\.

      1. The name of the grammar is moved from the tree node it is stored in to
         an attribute of the root node, and the tree node removed\.

         The node keeping the start expression separate is removed as irrelevant
         and the root node of the start expression tagged with a marker
         attribute, and its handle saved in an attribute of the root node for
         quick access\.

      1. Nonterminal hint information is moved from nodes into attributes, and
         the now irrelevant nodes are deleted\.

         *Note:* This transformation is dependent on the removal of all nodes
         with exactly one child, as it removes the all 'Attribute' nodes
         already\. Otherwise this transformation would have to put the
         information into the grandparental node\.

         The default mode given to the nonterminals is __value__\.

         Like with the global metadata definition specific information is moved
         out out of nodes into attributes, the now irrelevant nodes are deleted,
         and the root nodes of all definitions are tagged with marker
         attributes\. This provides us with a mapping from nonterminal names to
         their defining nodes as well, which is saved in an attribute of the
         root node for quick reference\.

         At last the range in the input covered by a definition is computed\. The
         left extent comes from the terminal for the nonterminal symbol it
         defines\. The right extent comes from the rightmost child under the
         definition\. While this not an expression tree yet the location data is
         sound already\.

      1. The remaining nodes under all definitions are transformed into proper
         expression trees\. First character ranges, followed by unary operations,
         characters, and nonterminals\. At last the tree is flattened by the
         removal of superfluous inner nodes\.

         The order matters, to shed as much nodes as possible early, and to
         avoid unnecessary work later\.

# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *page* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

    specified multiple times, the last one specified is used\. The input to
    encrypt is specified as *input*\. The *key* parameter, holding the key to
    use, is a return value from either __::pki::pkcs::parse\_key__,
    __::pki::x509::parse\_cert__, or __::pki::rsa::generate__\.

    Mapping to OpenSSL's __openssl__ application:

      1. "openssl rsautl \-encrypt" == "::pki::encrypt \-binary \-pub"

      1. "openssl rsautl \-sign" == "::pki::encrypt \-binary \-priv"

  - <a name='2'></a>__::pki::decrypt__ ?*\-binary*? ?*\-hex*? ?*\-unpad*? ?*\-nounpad*? ?*\-priv*? ?*\-pub*? ?*\-\-*? *input* *key*

    Decrypt a message using PKI \(probably RSA\)\. See __::pki::encrypt__ for
    option handling\.

    Mapping to OpenSSL's __openssl__ application:

      1. "openssl rsautl \-decrypt" == "::pki::decrypt \-binary \-priv"

      1. "openssl rsautl \-verify" == "::pki::decrypt \-binary \-pub"

  - <a name='3'></a>__::pki::sign__ *input* *key* ?*algo*?

    Digitally sign message *input* using the private *key*\. If *algo* is
    ommited "sha1" is assumed\. Possible values for *algo* include "md5",
    "sha1", "sha256", and "raw"\. Specifyin "raw" for *algo* will inhibit the
    building of an ASN\.1 structure to encode which hashing algorithm was chosen\.

    applicable plugins and their API\.

  - <a name='2'></a>__::pluginmgr::paths__ *objectName* *name*\.\.\.

    This utility command adds a set of paths to the specified object, based on
    the given *name*s\. It will search for:

      1. The environment variable __*name*\_PLUGINS__\. Its contents will be
         interpreted as a list of package paths\. The entries have to be
         separated by either __:__ \(unix\) or __;__ \(windows\)\.

         The name will be converted to upper\-case letters\.

      1. The registry entry "HKEY\_LOCAL\_MACHINE\\SOFTWARE\\*name*\\PLUGINS"\. Its
         contents will be interpreted as a list of package paths\. The entries
         have to be separated by __;__\. This item is considered only when on
         Windows \(tm\)\.

         The casing of letters is not changed\.

      1. The registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\*name*\\PLUGINS"\. Its
         contents will be interpreted as a list of package paths\. The entries
         have to be separated by __;__\. This item is considered only when on
         Windows \(tm\)\.

         The casing of letters is not changed\.

      1. The directory "~/\.*name*/plugin"\.

      1. The directory "~/\.*name*/plugins"\.

         The casing of letters is not changed\.

    and add all the paths found that way to the list of package paths maintained
    by the object\.

    If *name* is namespaced each item in the list will be repeated per prefix
    of *name*, with conversion of :\-sequences into the proper separator
    \(underscore for environment variables, backslash for registry entries, and /

  - <a name='13'></a>*objectName* __load__ *string*

    This method loads, validates, and initializes a named plugin into the
    manager object\.

    The algorithm to locate and load the plugin employed is:

      1. If the *string* contains the path to an existing file then this file
         is taken as the implementation of the plugin\.

      1. Otherwise the plugin name is translated into a package name via the
         value of the option __\-pattern__ and then loaded through the
         regular package management\.

      1. The load fails\.

    The algorithm to validate and initialize the loaded code is:

      1. If the option __\-api__ is non\-empty introspection commands are used
         to ascertain that the plugin provides the listed commands\.

      1. If the option __\-check__ is non\-empty the specified command prefix
         is called\.

      1. If either of the above fails the candidate plugin is unloaded again

      1. Otherwise all the commands specified via the option __\-cmds__ are
         installed in the plugin\.

    A previously loaded plugin is discarded, but only if the new plugin was
    found and sucessfully validated and initialized\. Note that there will be no
    intereference between old and new plugin as both will be put into separate
    safe interpreters\.

  - <a name='14'></a>*objectName* __unload__

We distinguish between *regular* and *canonical* serializations\. While a
tree may have more than one regular serialization only exactly one of them will
be *canonical*\.

  - Regular serialization

      1. The serialization of any AST is the serialization of its root node\.

      1. The serialization of any node is a Tcl list containing at least three
         elements\.

           1) The first element is the name of the nonterminal symbol stored in
              the node\.

           1) The second and third element are the locations of the first and
              last token in the token stream the node represents \(covers\)\.

                1. Locations are provided as non\-negative integer offsets from
                   the beginning of the token stream, with the first token found
                   in the stream located at offset 0 \(zero\)\.

                1. The end location has to be equal to or larger than the start
                   location\.

           1) All elements after the first three represent the children of the
              node, which are themselves nodes\. This means that the
              serializations of nodes without children, i\.e\. leaf nodes, have
              exactly three elements\. The children are stored in the list with
              the leftmost child first, and the rightmost child last\.


  - Canonical serialization

    The canonical serialization of an abstract syntax tree has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this tree\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the parsing expression grammar below

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;

           * string *path*

             The path of the include file as specified in the include directive
             being processed\.

         The result of the command will be a 5\-element list containing

           1) A boolean flag indicating the success \(__True__\) or failure
              \(__False__\) of the operation\.

           1) In case of success the contents of the included file, and the
              empty string otherwise\.

           1) The resolved, i\.e\. absolute path of the included file, if
              possible, or the unchanged *path* argument\. This is for display
              in an error message, or as the *currentfile* argument of another
              call to __IncludeFile__ should this file contain more files\.

           1) In case of success an empty string, and for failure a code
              indicating the reason for it, one of

                * notfound

                  The specified file could not be found\.

                * notread

                  The specified file was found, but not be read into memory\.

           1) An empty string in case of success of a __notfound__ failure,
              and an additional error message describing the reason for a
              __notread__ error in more detail\.

  1. A plugin has to provide a single command, in the global namespace, with the
     signature shown below\. Plugins are allowed to provide more commands of
     their own, but not less, and they may not provide different semantics for
     the standardized command\.

       - <a name='3'></a>__::import__ *text*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;

parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's
             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

           1) Each nonterminal symbol may occur only once\.

           1) The empty string is not a legal nonterminal symbol\.

           1) The value for each symbol is a JSON object itself\. The relevant
              keys and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section3)\.

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section3)\.

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section3)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;

parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's
             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

  - __error\_pop\_merge__

    This instruction takes the topmost entry of ES and merges the error status
    it contains with ES, making the result the new ES\.

    The merge is governed by four rules, with the merge result

      1. Empty if both states are empty\.

      1. The non\-empty state if only one of the two states is non\-empty\.

      1. The state with the larger location, if the two states specify different
         locations\.

      1. The pair of the location shared by the two states, and the set\-union of
         their messages for states at the same location\.

  - __error\_nonterminal__ *symbol*

    This is a guarded instruction\. It does nothing if either ES is empty, or if
    the location in ES is not just past the last location saved in LS\. Otherwise
    it sets the pair of that location and the nonterminal *symbol* as the new
    ES\.

    for validation of the tree's basic structure, printing it for debugging, and
    walking it either from the bottom up, or top down\.

    When encountering a syntax error the command will throw an error instead\.
    This error will be a 4\-element Tcl\-list, containing, in the order listed
    below:

      1. The string __pt::rde__ identifying it as parser runtime error\.

      1. The location of the parse error, as character offset from the beginning
         of the parsed input\.

      1. The location of parse error, now as a 2\-element list containing
         line\-number and column in the line\.

      1. A set of atomic parsing expressions indicating encoding the characters
         and/or nonterminal symbols the parser expected to see at the location
         of the parse error, but did not get\. For the specification of atomic
         parsing expressions please see the section __PE serialization
         format__\.

  - <a name='4'></a>*objectName* __parset__ *text*

    This method runs the parser using the string in *text* as input\. In all
    other ways it behaves like the method __parse__, shown above\.

# <a name='section4'></a>Bugs, Ideas, Feedback

    structure, printing it for debugging, and walking it either from the bottom
    up, or top down\.

    When encountering a syntax error the command will throw an error instead\.
    This error will be a 4\-element Tcl\-list, containing, in the order listed
    below:

      1. The string __pt::rde__ identifying it as parser runtime error\.

      1. The location of the parse error, as character offset from the beginning
         of the parsed input\.

      1. The location of parse error, now as a 2\-element list containing
         line\-number and column in the line\.

      1. A set of atomic parsing expressions indicating encoding the characters
         and/or nonterminal symbols the parser expected to see at the location
         of the parse error, but did not get\. For the specification of atomic
         parsing expressions please see the section [PE serialization
         format](#section6)\.

  - <a name='4'></a>*objectName* __parset__ *text*

    This method runs the parser using the string in *text* as input\. In all
    other ways it behaves like the method __parse__, shown above\.

# <a name='section4'></a>Usage

We distinguish between *regular* and *canonical* serializations\. While a
tree may have more than one regular serialization only exactly one of them will
be *canonical*\.

  - Regular serialization

      1. The serialization of any AST is the serialization of its root node\.

      1. The serialization of any node is a Tcl list containing at least three
         elements\.

           1) The first element is the name of the nonterminal symbol stored in
              the node\.

           1) The second and third element are the locations of the first and
              last token in the token stream the node represents \(covers\)\.

                1. Locations are provided as non\-negative integer offsets from
                   the beginning of the token stream, with the first token found
                   in the stream located at offset 0 \(zero\)\.

                1. The end location has to be equal to or larger than the start
                   location\.

           1) All elements after the first three represent the children of the
              node, which are themselves nodes\. This means that the
              serializations of nodes without children, i\.e\. leaf nodes, have
              exactly three elements\. The children are stored in the list with
              the leftmost child first, and the rightmost child last\.


  - Canonical serialization

    The canonical serialization of an abstract syntax tree has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this tree\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the parsing expression grammar below

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;

parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's
             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section3)\.

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section3)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection3'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;

parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's
             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection4'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section4)\.

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section4)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection4'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;

parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's
             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection5'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.