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

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

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

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

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

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

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

    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:

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

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

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

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

    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

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

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

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

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

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

    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

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

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

    The string __unset__, and the *key*\.

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

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

    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:

    augmenting a command

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

    short circuiting a command

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

    Replacing double eval semantics

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

    Using a slave interpreter

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

    Using a slave interpreter \(double eval\)

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

    Subverting the script to execute

    % ::comm::comm hook eval \{
        switch \-\- $buffer \{
            a \{return A\-OK\}
            b \{return B\-OK\}
            default \{error "$buffer is a no\-no"\}
        \}
................................................................................
    __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

    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\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools\(n\) 1\.5 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?  

[__::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)  

[//000000001]: # (doctools \- Documentation tools)
[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2019 Andreas Kupries <andreas\[email protected]\.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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

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

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

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

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

                * notfound

                  The specified file could not be found\.

                * notread

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

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

  1. A plugin has to provide 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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

    An index serialization is a nested Tcl dictionary\.

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

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

           * __title__

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

           * __label__

................................................................................
             this order\.

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

    The *[type](\.\./\.\./\.\./\.\./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__
................................................................................
  - canonical serialization

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

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

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

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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

# <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='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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

# <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='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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

# <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='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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

# <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='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

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

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

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

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

                * notfound

                  The specified file could not be found\.

                * notread

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

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

  1. A plugin has to provide 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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

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

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

# <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='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:

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

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

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

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

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

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

Here we specify the format used by the doctools v2 packages to serialize tables
................................................................................

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

  - regular serialization

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

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

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

           * __title__

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

           * __label__
................................................................................
  - canonical serialization

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

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

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

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

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:

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

    The directory named in the TMPDIR environment variable\.

    The directory named in the TEMP environment variable\.

    The directory named in the TMP environment variable\.

    A platform specific location:

           * Windows

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

           * \(classic\) Macintosh

  - <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__?

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

    The constant string __grammar::fa__\.

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

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


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

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

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

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

    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:

    Convert the expression into a finite automaton\.

    Minimize the automaton\.

    Convert the automaton back to a regular expression\.

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

# <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='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

    reads the instruction references from the attributes __gas::entry__,
    __gas::exit::ok__, and __gas::exit::fail__ from the node *n* of
    the tree *t* and makes them available to assembler und the labels

    *label*/entry, *label*/exit::ok, and *label*/exit::fail respectively\.

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

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

    The command returns the empty string as its result\.

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

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

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

    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:

    The constant string __grammar::peg__\.

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

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

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

    Assuming the following PEG for simple mathematical expressions

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

    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

    No binding is ever called after it is deleted\.

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

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

    In particular:

    If __$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\.\)

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

    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
................................................................................
    among observers must be preserved, define one observer and have its bindings
    call the other callbacks directly in the proper sequence\.

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

    __hook call__ returns the empty string\.

    Normal return values from observer bindings are ignored\.

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


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

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

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

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

        hook call $s $h

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

  - <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* \.\.\.
................................................................................
      * __\-errorcommand__ *cmdPrefix*

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

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

        the result string, and

        the return options dictionary\.

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

      * __\-tracecommand__ *cmdPrefix*

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

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

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

        a list of the hook's argument values, and

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

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

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

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

        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
................................................................................
    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* \.\.\.
................................................................................
      * __\-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:

    HTML32

    HTML40

    HTML40T

    HTML40F

    HTML401

    HTML401T

    HTML401F

    XHTML10S

    XHTML10T

    XHTML10F

    XHTML11

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

  - <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\):

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

    Addition of a new entry\.

    \{__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\)\.

    \{__del__\}

    Deletion of an old entry\.

    \{__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

    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__

    $\{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\.

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

    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

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

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

    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)

    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='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\.

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

    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

    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__

    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

    east

    northeast

    north

    northwest

    west

    southwest

    south

    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

    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

    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

      * 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

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

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


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

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

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


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

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

    The default mode given to the nonterminals is __value__\.

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


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


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

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

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

    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:

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

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

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

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

    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:

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

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

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

    The casing of letters is not changed\.

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

    The casing of letters is not changed\.

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

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

    The casing of letters is not changed\.

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

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

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

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

    The load fails\.

    The algorithm to validate and initialize the loaded code is:

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

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

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

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

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

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

    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

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

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

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


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

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

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


    All elements after the first three represent the children of the node, which
    are themselves nodes\. This means that the serializations of nodes without

    children, i\.e\. leaf nodes, have exactly three elements\. The children are
    stored in the list with the leftmost child first, and the rightmost child
    last\.

  - Canonical serialization

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

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

## <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'       ;

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

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

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

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

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

                * notfound

                  The specified file could not be found\.

                * notread

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

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

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

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

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

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

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

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

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

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

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

                * __is__

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

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

  - regular serialization

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

## <a name='subsection3'></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

    Empty if both states are empty\.

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

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

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

  - __error\_nonterminal__ *symbol*

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

  - __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:

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

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

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

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


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

    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:

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

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

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

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

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

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

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

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


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

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

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


    All elements after the first three represent the children of the node, which
    are themselves nodes\. This means that the serializations of nodes without

    children, i\.e\. leaf nodes, have exactly three elements\. The children are
    stored in the list with the leftmost child first, and the rightmost child
    last\.

  - Canonical serialization

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

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

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

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

    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

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

## <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](#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

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

## <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](#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

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

## <a name='subsection3'></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)\.

................................................................................

           * __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='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\)\*

     their values are

       - __rules__

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

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

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

                * __is__

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

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

  - regular serialization

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

## <a name='subsection3'></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](#section6)\.
................................................................................

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='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\)\*

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

  - regular serialization

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

## <a name='subsection3'></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)\.

................................................................................

           * __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='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\)\*

     their values are

       - __rules__

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

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

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

                * __is__

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

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

  - regular serialization

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

## <a name='subsection3'></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](#section5)\.
................................................................................

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](#section5)\.

................................................................................

           * __start__

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

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

  - 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\)\*

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

  - regular serialization

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

## <a name='subsection3'></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](#section5)\.

................................................................................

           * __start__

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

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

  - 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\)\*

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

  - regular serialization

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

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

................................................................................

           * __start__

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

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

  - canonical serialization

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

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

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

## <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__

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

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

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

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

      * __Combined Parsing Expressions__

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

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

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

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

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


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


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

  - Canonical serialization

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

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

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

## <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](#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\)\*

     their values are

       - __rules__

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

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

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

                * __is__

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

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

  - regular serialization

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

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

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

           * __rules__

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

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

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

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></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](#section5)\.
................................................................................

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](#section5)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - 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\)\*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></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](#section5)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - 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\)\*

    structure, printing it for debugging, and walking it either from the bottom
    up, or top down\.

    When encountering a syntax error the command will throw an error instead\.
    This error will be a 4\-element Tcl\-list, containing, in the order listed
    below:

    The string __pt::rde__ identifying it as parser runtime error\.

    The location of the parse error, as character offset from the beginning of
    the parsed input\.

    The location of parse error, now as a 2\-element list containing line\-number
    and column in the line\.

    A set of atomic parsing expressions indicating encoding the characters
    and/or nonterminal symbols the parser expected to see at the location of the
    parse error, but did not get\. For the specification of atomic parsing
    expressions please see the section [PE serialization
    format](#section3)\.

  - <a name='5'></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='section2'></a>AST serialization format
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
tree may have more than one regular serialization only exactly one of them will
be *canonical*\.

  - Regular serialization

    The serialization of any AST is the serialization of its root node\.

    The serialization of any node is a Tcl list containing at least three
    elements\.

    The first element is the name of the nonterminal symbol stored in the node\.


    The second and third element are the locations of the first and last token
    in the token stream the node represents \(covers\)\.

    Locations are provided as non\-negative integer offsets from the beginning of
    the token stream, with the first token found in the stream located at offset
    0 \(zero\)\.

    The end location has to be equal to or larger than the start location\.


    All elements after the first three represent the children of the node, which
    are themselves nodes\. This means that the serializations of nodes without

    children, i\.e\. leaf nodes, have exactly three elements\. The children are
    stored in the list with the leftmost child first, and the rightmost child
    last\.

  - Canonical serialization

    The canonical serialization of an abstract syntax tree has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this tree\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection3'></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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection4'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

    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](#section3)\.

  - <a name='5'></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='section2'></a>AST serialization format
................................................................................

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='subsection3'></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='subsection4'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

    package __[pt::peg::container](pt\_peg\_container\.md)__\.

  - <a name='7'></a>__::peg::peg::op__ __modeopt__ *container*

    This command optimizes the semantic modes of non\-terminal symbols according
    to the two rules below\.

    If a symbol X with mode __value__ calls no other symbols, i\.e\. uses only
    terminal symbols in whatever combination, then this can be represented
    simpler by using mode __leaf__\.

    If a symbol X is only called from symbols with modes __leaf__ or
    __void__ then this symbol should have mode __void__ also, as any AST
    it could generate will be discarded anyway\.

    The result of the command is the empty string\.

    The grammar in the container is directly modified\. If that is not wanted, a
    copy of the original container has to be used\.

    The *container* instance has to expose a method API as is provided by the

    package __[pt::peg::container](pt\_peg\_container\.md)__\.

  - <a name='7'></a>__::peg::peg::op__ __modeopt__ *container*

    This command optimizes the semantic modes of non\-terminal symbols according
    to the two rules below\.

      1. If a symbol X with mode __value__ calls no other symbols, i\.e\. uses
         only terminal symbols in whatever combination, then this can be
         represented simpler by using mode __leaf__\.

      1. If a symbol X is only called from symbols with modes __leaf__ or
         __void__ then this symbol should have mode __void__ also, as
         any AST it could generate will be discarded anyway\.

    The result of the command is the empty string\.

    The grammar in the container is directly modified\. If that is not wanted, a
    copy of the original container has to be used\.

    The *container* instance has to expose a method API as is provided by the

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></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)\.

................................................................................

           * __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='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\)\*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></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)\.

................................................................................

           * __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='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\)\*

     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

         The value for each symbol is a JSON object itself\. The relevant keys
         and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section6)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></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](#section6)\.
................................................................................

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='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\)\*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></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)\.

................................................................................

           * __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='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\)\*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></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)\.

................................................................................

           * __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='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\)\*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <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](#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\)\*

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section4)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section4)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <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](#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='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\)\*

parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection1'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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='subsection1'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection1'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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='subsection1'></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

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section7)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section7)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <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__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <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](#section7)\.

................................................................................

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section7)\.

      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\)\*

            types \(e\.g\., stacks and queues\) more efficient\.

            If false \(the default\), instance methods are dispatched normally\. If
            true, a faster dispatching scheme is used instead\. The speed comes
            at a price; with __\-simpledispatch yes__ you get the following
            limitations:

            Methods cannot be delegated\.

            __uplevel__ and __upvar__ do not work as expected: the
            caller's scope is two levels up rather than one\.

            The option\-handling methods \(__cget__, __configure__, and
            __configurelist__\) are very slightly slower\.

      * <a name='25'></a>__expose__ *comp*

      * <a name='26'></a>__expose__ *comp* __as__ *method*

        __Deprecated\.__ To expose component *comp* publicly, use
        __component__'s __\-public__ option\.
................................................................................

  - <a name='29'></a>__snit::widget__ *name* *definition*

    This command defines a Snit megawidget type with the specified *name*\. The
    *definition* is defined as for __snit::type__\. A __snit::widget__
    differs from a __snit::type__ in these ways:

    Every instance of a __snit::widget__ has an automatically\-created
    component called __hull__, which is normally a Tk frame widget\. Other
    widgets created as part of the megawidget will be created within this
    widget\.

    The hull component is initially created with the requested widget name; then
    Snit does some magic, renaming the hull component and installing its own
    instance command in its place\. The hull component's new name is saved in an
    instance variable called __hull__\.

    The name of an instance must be valid Tk window name, and the parent window
    must exist\.

    A __snit::widget__ definition can include any of statements allowed in a
    __snit::type__ definition, and may also include the following:

      * <a name='30'></a>__widgetclass__ *name*

        Sets the __snit::widget__'s widget class to *name*, overriding the

            types \(e\.g\., stacks and queues\) more efficient\.

            If false \(the default\), instance methods are dispatched normally\. If
            true, a faster dispatching scheme is used instead\. The speed comes
            at a price; with __\-simpledispatch yes__ you get the following
            limitations:

              - Methods cannot be delegated\.

              - __uplevel__ and __upvar__ do not work as expected: the
                caller's scope is two levels up rather than one\.

              - The option\-handling methods \(__cget__, __configure__,
                and __configurelist__\) are very slightly slower\.

      * <a name='25'></a>__expose__ *comp*

      * <a name='26'></a>__expose__ *comp* __as__ *method*

        __Deprecated\.__ To expose component *comp* publicly, use
        __component__'s __\-public__ option\.
................................................................................

  - <a name='29'></a>__snit::widget__ *name* *definition*

    This command defines a Snit megawidget type with the specified *name*\. The
    *definition* is defined as for __snit::type__\. A __snit::widget__
    differs from a __snit::type__ in these ways:

      * Every instance of a __snit::widget__ has an automatically\-created
        component called __hull__, which is normally a Tk frame widget\.
        Other widgets created as part of the megawidget will be created within
        this widget\.

        The hull component is initially created with the requested widget name;
        then Snit does some magic, renaming the hull component and installing
        its own instance command in its place\. The hull component's new name is
        saved in an instance variable called __hull__\.

      * The name of an instance must be valid Tk window name, and the parent
        window must exist\.

    A __snit::widget__ definition can include any of statements allowed in a
    __snit::type__ definition, and may also include the following:

      * <a name='30'></a>__widgetclass__ *name*

        Sets the __snit::widget__'s widget class to *name*, overriding the

    The result is a list containing a multiple of three items, plus one\! In
    other words, '\[llength $serial\] % 3 == 1'\. Valid values include 1, 4, 7, \.\.\.

    The last element of the list is a dictionary containing the attributes
    associated with the whole graph\. Regarding the other elements; each triple
    consists of

    The name of the node to be described,

    A dictionary containing the attributes associated with the node,

    And a list describing all the arcs starting at that node\.

    The elements of the arc list are lists containing three or four elements
    each, i\.e\.

    The name of the arc described by the element,

    A reference to the destination node of the arc\. This reference is an integer
    number given the index of that node in the main serialization list\. As that
    it is greater than or equal to zero, less than the length of the
    serialization, and a multiple of three\. *Note:* For internal consistency
    no arc name may be used twice, whether in the same node, or at some other
    node\. This is a global consistency requirement for the serialization\.


    And a dictionary containing the attributes associated with the arc\.

    The weight associated with the arc\. This value is optional\. Its non\-presence
    means that the arc in question has no weight associated with it\.


    *Note:* This information is new, compared to the serialization of
    __[graph](\.\./\.\./\.\./\.\./index\.md\#graph)__ 2\.3 and earlier\. By making
    it an optional element the new format is maximally compatible with the old\.
    This means that any graph not using weights will generate a serialization
    which is still understood by the older graph package\. A serialization will
    not be understood any longer by the older packages if, and only if the graph
    it was generated from actually has arcs with weights\.


    For all attribute dictionaries they keys are the names of the attributes,
    and the values are the values for each name\.

    *Note:* The order of the nodes in the serialization has no relevance, nor
    has the order of the arcs per node\.

    The result is a list containing a multiple of three items, plus one\! In
    other words, '\[llength $serial\] % 3 == 1'\. Valid values include 1, 4, 7, \.\.\.

    The last element of the list is a dictionary containing the attributes
    associated with the whole graph\. Regarding the other elements; each triple
    consists of

      1. The name of the node to be described,

      1. A dictionary containing the attributes associated with the node,

      1. And a list describing all the arcs starting at that node\.

    The elements of the arc list are lists containing three or four elements
    each, i\.e\.

      1. The name of the arc described by the element,

      1. A reference to the destination node of the arc\. This reference is an
         integer number given the index of that node in the main serialization
         list\. As that it is greater than or equal to zero, less than the length
         of the serialization, and a multiple of three\. *Note:* For internal
         consistency no arc name may be used twice, whether in the same node, or
         at some other node\. This is a global consistency requirement for the
         serialization\.

      1. And a dictionary containing the attributes associated with the arc\.

      1. The weight associated with the arc\. This value is optional\. Its
         non\-presence means that the arc in question has no weight associated
         with it\.

         *Note:* This information is new, compared to the serialization of
         __[graph](\.\./\.\./\.\./\.\./index\.md\#graph)__ 2\.3 and earlier\. By
         making it an optional element the new format is maximally compatible
         with the old\. This means that any graph not using weights will generate
         a serialization which is still understood by the older graph package\. A
         serialization will not be understood any longer by the older packages
         if, and only if the graph it was generated from actually has arcs with
         weights\.

    For all attribute dictionaries they keys are the names of the attributes,
    and the values are the values for each name\.

    *Note:* The order of the nodes in the serialization has no relevance, nor
    has the order of the arcs per node\.

    *[E](\.\./\.\./\.\./\.\./index\.md\#e)* a set of edges\), and one vertice *v*
    of *V*, find a path *P* from *v* to a *v'* of V so that the sum of
    weights on edges along the path is minimal among all paths connecting v to
    v'\.

  - Generalizations:

    *The single\-source shortest path problem*, in which we have to find
    shortest paths from a source vertex v to all other vertices in the graph\.


    *The single\-destination shortest path problem*, in which we have to find
    shortest paths from all vertices in the graph to a single destination vertex
    v\. This can be reduced to the single\-source shortest path problem by
    reversing the edges in the graph\.

    *The all\-pairs shortest path problem*, in which we have to find shortest
    paths between every pair of vertices v, v' in the graph\.

    *Note:* The result of *Shortest Path problem* can be *Shortest Path
    tree*, which is a subgraph of a given \(possibly weighted\) graph constructed
    so that the distance between a selected root node and all other nodes is
    minimal\. It is a tree because if there are two paths between the root node
    and some vertex v \(i\.e\. a cycle\), we can delete the last edge of the longer
    path without increasing the distance from the root node to any node in the
................................................................................

    For given edge\-weighted \(weights on edges should be positive\) graph the goal
    is to find the cycle that visits each node in graph exactly once
    \(*Hamiltonian cycle*\)\.

  - Generalizations:

    *Metric TSP* \- A very natural restriction of the *TSP* is to require
    that the distances between cities form a *metric*, i\.e\., they satisfy
    *the triangle inequality*\. That is, for any 3 cities *A*, *B* and
    *[C](\.\./\.\./\.\./\.\./index\.md\#c)*, the distance between *A* and
    *[C](\.\./\.\./\.\./\.\./index\.md\#c)* must be at most the distance from *A*
    to *B* plus the distance from *B* to
    *[C](\.\./\.\./\.\./\.\./index\.md\#c)*\. Most natural instances of *TSP*
    satisfy this constraint\.

    *Euclidean TSP* \- Euclidean TSP, or *planar TSP*, is the *TSP* with
    the distance being the ordinary *Euclidean distance*\. *Euclidean TSP* is
    a particular case of *TSP* with *triangle inequality*, since distances
    in plane obey triangle inequality\. However, it seems to be easier than
    general *TSP* with *triangle inequality*\. For example, *the minimum
    spanning tree* of the graph associated with an instance of *Euclidean
    TSP* is a *Euclidean minimum spanning tree*, and so can be computed in
    expected *O\(n log n\)* time for *n* points \(considerably less than the
    number of edges\)\. This enables the simple *2\-approximation algorithm* for
    TSP with triangle inequality above to operate more quickly\.


    *Asymmetric TSP* \- In most cases, the distance between two nodes in the
    *TSP* network is the same in both directions\. The case where the distance
    from *A* to *B* is not equal to the distance from *B* to *A* is
    called *asymmetric TSP*\. A practical application of an *asymmetric TSP*
    is route optimisation using street\-level routing \(asymmetric due to one\-way
    streets, slip\-roads and motorways\)\.

## <a name='subsection3'></a>Matching Problem

  - Definition:

    Given a graph *G = \(V,E\)*, a matching or *edge\-independent set* *M* in
    *G* is a set of pairwise non\-adjacent edges, that is, no two edges share a
    common vertex\. A vertex is *matched* if it is incident to an edge in the
    *matching M*\. Otherwise the vertex is *unmatched*\.

  - Generalizations:

    *Maximal matching* \- a matching *M* of a graph G with the property that
    if any edge not in *M* is added to *M*, it is no longer a
    *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)*, that is, *M* is maximal
    if it is not a proper subset of any other
    *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)* in graph G\. In other
    words, a *matching M* of a graph G is maximal if every edge in G has a
    non\-empty intersection with at least one edge in *M*\.

    *Maximum matching* \- a matching that contains the largest possible number
    of edges\. There may be many *maximum matchings*\. The *matching number*
    of a graph G is the size of a *maximum matching*\. Note that every
    *maximum matching* is *maximal*, but not every *maximal matching* is a
    *maximum matching*\.

    *Perfect matching* \- a matching which matches all vertices of the graph\.
    That is, every vertex of the graph is incident to exactly one edge of the
    matching\. Every *perfect matching* is
    *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)* and hence *maximal*\. In
    some literature, the term *complete matching* is used\. A *perfect
    matching* is also a *minimum\-size edge cover*\. Moreover, the size of a
    *maximum matching* is no larger than the size of a *minimum edge cover*\.


    *Near\-perfect matching* \- a matching in which exactly one vertex is
    unmatched\. This can only occur when the graph has an odd number of vertices,
    and such a *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)* must be
    *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)*\. If, for every vertex in a
    graph, there is a near\-perfect matching that omits only that vertex, the
    graph is also called *factor\-critical*\.

  - Related terms:

    *Alternating path* \- given a matching *M*, an *alternating path* is a
    path in which the edges belong alternatively to the matching and not to the
    matching\.

    *[Augmenting path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* \- given a
    matching *M*, an *[augmenting
    path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* is an *alternating path*
    that starts from and ends on free \(unmatched\) vertices\.

## <a name='subsection4'></a>Cut Problems

  - Definition:

    A *cut* is a partition of the vertices of a graph into two *disjoint
    subsets*\. The *cut\-set* of the *cut* is the set of edges whose end
    points are in different subsets of the partition\. Edges are said to be
    crossing the cut if they are in its *cut\-set*\.

    Formally:

    a *cut* *C = \(S,T\)* is a partition of *V* of a graph *G = \(V, E\)*\.


    an *s\-t cut* *C = \(S,T\)* of a *[flow
    network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)* *N = \(V, E\)* is a cut of
    *N* such that *s* is included in *S* and *t* is included in *T*,

    where *s* and *t* are the *[source](\.\./\.\./\.\./\.\./index\.md\#source)*
    and the *sink* of *N* respectively\.

    The *cut\-set* of a *cut C = \(S,T\)* is such set of edges from graph *G =
    \(V, E\)* that each edge *\(u, v\)* satisfies condition that *u* is
    included in *S* and *v* is included in *T*\.

    In an *unweighted undirected* graph, the size or weight of a cut is the
    number of edges crossing the cut\. In a *weighted graph*, the same term is
    defined by the sum of the weights of the edges crossing the cut\.

    In a *[flow network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*, an *s\-t
    cut* is a cut that requires the
................................................................................
    defined by the sum of capacity of each edge in the *cut\-set*\.

    The *cut* of a graph can sometimes refer to its *cut\-set* instead of the
    partition\.

  - Generalizations:

    *Minimum cut* \- A cut is minimum if the size of the cut is not larger than
    the size of any other cut\.

    *Maximum cut* \- A cut is maximum if the size of the cut is not smaller
    than the size of any other cut\.

    *Sparsest cut* \- The *Sparsest cut problem* is to bipartition the
    vertices so as to minimize the ratio of the number of edges across the cut
    divided by the number of vertices in the smaller half of the partition\.


## <a name='subsection5'></a>K\-Center Problem

  - Definitions:

      * *Unweighted K\-Center*

................................................................................
        \}\}* has the smallest possible worth \( *v* is a node in *V* and
        *u* is a node in *S* \)\.

## <a name='subsection6'></a>Flow Problems

  - Definitions:

    *the maximum flow problem* \- the goal is to find a feasible flow through a
    single\-source, single\-sink flow network that is maximum\. The *maximum flow
    problem* can be seen as a special case of more complex network flow
    problems, such as the *circulation problem*\. The maximum value of an *s\-t
    flow* is equal to the minimum capacity of an *s\-t cut* in the network, as
    stated in the *max\-flow min\-cut theorem*\.

    More formally for flow network *G = \(V,E\)*, where for each edge *\(u, v\)*
    we have its throuhgput *c\(u,v\)* defined\. As
    *[flow](\.\./\.\./\.\./\.\./index\.md\#flow)* *F* we define set of
    non\-negative integer attributes *f\(u,v\)* assigned to edges, satisfying
    such conditions:

    for each edge *\(u, v\)* in *G* such condition should be satisfied: 0 <=
    f\(u,v\) <= c\(u,v\)

    Network *G* has source node *s* such that the flow *F* is equal to the
    sum of outcoming flow decreased by the sum of incoming flow from that source
    node *s*\.

    Network *G* has sink node *t* such that the the *\-F* value is equal to
    the sum of the incoming flow decreased by the sum of outcoming flow from
    that sink node *t*\.


    For each node that is not a *[source](\.\./\.\./\.\./\.\./index\.md\#source)* or
    *sink* the sum of incoming flow and sum of outcoming flow should be equal\.

    *the minimum cost flow problem* \- the goal is finding the cheapest
    possible way of sending a certain amount of flow through a *[flow
    network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*\.

    *[blocking flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* \- a *[blocking
    flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* for a *residual network*
    *Gf* we name such flow *b* in *Gf* that:


    Each path from *sink* to *[source](\.\./\.\./\.\./\.\./index\.md\#source)* is
    the shortest path in *Gf*\.

    Each shortest path in *Gf* contains an edge with fully used throughput in
    *Gf\+b*\.

    *residual network* \- for a flow network *G* and flow *f* *residual
    network* is built with those edges, which can send larger flow\. It contains
    only those edges, which can send flow larger than 0\.

    *level network* \- it has the same set of nodes as *[residual
    graph](\.\./\.\./\.\./\.\./index\.md\#residual\_graph)*, but has only those edges
    *\(u,v\)* from *Gf* for which such equality is satisfied:
    *distance\(s,u\)\+1 = distance\(s,v\)*\.

    *[augmenting network](\.\./\.\./\.\./\.\./index\.md\#augmenting\_network)* \- it
    is a modification of *residual network* considering the new flow values\.
    Structure stays unchanged but values of throughputs and costs at edges are
    different\.

## <a name='subsection7'></a>Approximation algorithm

  - k\-approximation algorithm:

    Algorithm is a k\-approximation, when for *ALG* \(solution returned by
    algorithm\) and *OPT* \(optimal solution\), such inequality is true:

    for minimalization problems: *ALG/OPT <= k*

    for maximalization problems: *OPT/ALG <= k*

# <a name='section4'></a>References

  1. [Adjacency matrix](http://en\.wikipedia\.org/wiki/Adjacency\_matrix)

  1. [Adjacency list](http://en\.wikipedia\.org/wiki/Adjacency\_list)

    *[E](\.\./\.\./\.\./\.\./index\.md\#e)* a set of edges\), and one vertice *v*
    of *V*, find a path *P* from *v* to a *v'* of V so that the sum of
    weights on edges along the path is minimal among all paths connecting v to
    v'\.

  - Generalizations:

      * *The single\-source shortest path problem*, in which we have to find
        shortest paths from a source vertex v to all other vertices in the
        graph\.

      * *The single\-destination shortest path problem*, in which we have to
        find shortest paths from all vertices in the graph to a single
        destination vertex v\. This can be reduced to the single\-source shortest
        path problem by reversing the edges in the graph\.

      * *The all\-pairs shortest path problem*, in which we have to find
        shortest paths between every pair of vertices v, v' in the graph\.

    *Note:* The result of *Shortest Path problem* can be *Shortest Path
    tree*, which is a subgraph of a given \(possibly weighted\) graph constructed
    so that the distance between a selected root node and all other nodes is
    minimal\. It is a tree because if there are two paths between the root node
    and some vertex v \(i\.e\. a cycle\), we can delete the last edge of the longer
    path without increasing the distance from the root node to any node in the
................................................................................

    For given edge\-weighted \(weights on edges should be positive\) graph the goal
    is to find the cycle that visits each node in graph exactly once
    \(*Hamiltonian cycle*\)\.

  - Generalizations:

      * *Metric TSP* \- A very natural restriction of the *TSP* is to require
        that the distances between cities form a *metric*, i\.e\., they satisfy
        *the triangle inequality*\. That is, for any 3 cities *A*, *B* and
        *[C](\.\./\.\./\.\./\.\./index\.md\#c)*, the distance between *A* and
        *[C](\.\./\.\./\.\./\.\./index\.md\#c)* must be at most the distance from
        *A* to *B* plus the distance from *B* to
        *[C](\.\./\.\./\.\./\.\./index\.md\#c)*\. Most natural instances of *TSP*
        satisfy this constraint\.

      * *Euclidean TSP* \- Euclidean TSP, or *planar TSP*, is the *TSP*
        with the distance being the ordinary *Euclidean distance*\. *Euclidean
        TSP* is a particular case of *TSP* with *triangle inequality*,
        since distances in plane obey triangle inequality\. However, it seems to
        be easier than general *TSP* with *triangle inequality*\. For
        example, *the minimum spanning tree* of the graph associated with an
        instance of *Euclidean TSP* is a *Euclidean minimum spanning tree*,
        and so can be computed in expected *O\(n log n\)* time for *n* points
        \(considerably less than the number of edges\)\. This enables the simple
        *2\-approximation algorithm* for TSP with triangle inequality above to
        operate more quickly\.

      * *Asymmetric TSP* \- In most cases, the distance between two nodes in
        the *TSP* network is the same in both directions\. The case where the
        distance from *A* to *B* is not equal to the distance from *B* to
        *A* is called *asymmetric TSP*\. A practical application of an
        *asymmetric TSP* is route optimisation using street\-level routing
        \(asymmetric due to one\-way streets, slip\-roads and motorways\)\.

## <a name='subsection3'></a>Matching Problem

  - Definition:

    Given a graph *G = \(V,E\)*, a matching or *edge\-independent set* *M* in
    *G* is a set of pairwise non\-adjacent edges, that is, no two edges share a
    common vertex\. A vertex is *matched* if it is incident to an edge in the
    *matching M*\. Otherwise the vertex is *unmatched*\.

  - Generalizations:

      * *Maximal matching* \- a matching *M* of a graph G with the property
        that if any edge not in *M* is added to *M*, it is no longer a
        *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)*, that is, *M* is
        maximal if it is not a proper subset of any other
        *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)* in graph G\. In other
        words, a *matching M* of a graph G is maximal if every edge in G has a
        non\-empty intersection with at least one edge in *M*\.

      * *Maximum matching* \- a matching that contains the largest possible
        number of edges\. There may be many *maximum matchings*\. The *matching
        number* of a graph G is the size of a *maximum matching*\. Note that
        every *maximum matching* is *maximal*, but not every *maximal
        matching* is a *maximum matching*\.

      * *Perfect matching* \- a matching which matches all vertices of the
        graph\. That is, every vertex of the graph is incident to exactly one
        edge of the matching\. Every *perfect matching* is
        *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)* and hence *maximal*\.
        In some literature, the term *complete matching* is used\. A *perfect
        matching* is also a *minimum\-size edge cover*\. Moreover, the size of
        a *maximum matching* is no larger than the size of a *minimum edge
        cover*\.

      * *Near\-perfect matching* \- a matching in which exactly one vertex is
        unmatched\. This can only occur when the graph has an odd number of
        vertices, and such a *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)*
        must be *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)*\. If, for every
        vertex in a graph, there is a near\-perfect matching that omits only that
        vertex, the graph is also called *factor\-critical*\.

  - Related terms:

      * *Alternating path* \- given a matching *M*, an *alternating path*
        is a path in which the edges belong alternatively to the matching and
        not to the matching\.

      * *[Augmenting path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* \- given
        a matching *M*, an *[augmenting
        path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* is an *alternating
        path* that starts from and ends on free \(unmatched\) vertices\.

## <a name='subsection4'></a>Cut Problems

  - Definition:

    A *cut* is a partition of the vertices of a graph into two *disjoint
    subsets*\. The *cut\-set* of the *cut* is the set of edges whose end
    points are in different subsets of the partition\. Edges are said to be
    crossing the cut if they are in its *cut\-set*\.

    Formally:

      * a *cut* *C = \(S,T\)* is a partition of *V* of a graph *G = \(V,
        E\)*\.

      * an *s\-t cut* *C = \(S,T\)* of a *[flow
        network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)* *N = \(V, E\)* is a cut
        of *N* such that *s* is included in *S* and *t* is included in
        *T*, where *s* and *t* are the
        *[source](\.\./\.\./\.\./\.\./index\.md\#source)* and the *sink* of *N*
        respectively\.

      * The *cut\-set* of a *cut C = \(S,T\)* is such set of edges from graph
        *G = \(V, E\)* that each edge *\(u, v\)* satisfies condition that *u*
        is included in *S* and *v* is included in *T*\.

    In an *unweighted undirected* graph, the size or weight of a cut is the
    number of edges crossing the cut\. In a *weighted graph*, the same term is
    defined by the sum of the weights of the edges crossing the cut\.

    In a *[flow network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*, an *s\-t
    cut* is a cut that requires the
................................................................................
    defined by the sum of capacity of each edge in the *cut\-set*\.

    The *cut* of a graph can sometimes refer to its *cut\-set* instead of the
    partition\.

  - Generalizations:

      * *Minimum cut* \- A cut is minimum if the size of the cut is not larger
        than the size of any other cut\.

      * *Maximum cut* \- A cut is maximum if the size of the cut is not smaller
        than the size of any other cut\.

      * *Sparsest cut* \- The *Sparsest cut problem* is to bipartition the
        vertices so as to minimize the ratio of the number of edges across the
        cut divided by the number of vertices in the smaller half of the
        partition\.

## <a name='subsection5'></a>K\-Center Problem

  - Definitions:

      * *Unweighted K\-Center*

................................................................................
        \}\}* has the smallest possible worth \( *v* is a node in *V* and
        *u* is a node in *S* \)\.

## <a name='subsection6'></a>Flow Problems

  - Definitions:

      * *the maximum flow problem* \- the goal is to find a feasible flow
        through a single\-source, single\-sink flow network that is maximum\. The
        *maximum flow problem* can be seen as a special case of more complex
        network flow problems, such as the *circulation problem*\. The maximum
        value of an *s\-t flow* is equal to the minimum capacity of an *s\-t
        cut* in the network, as stated in the *max\-flow min\-cut theorem*\.

        More formally for flow network *G = \(V,E\)*, where for each edge *\(u,
        v\)* we have its throuhgput *c\(u,v\)* defined\. As
        *[flow](\.\./\.\./\.\./\.\./index\.md\#flow)* *F* we define set of
        non\-negative integer attributes *f\(u,v\)* assigned to edges, satisfying
        such conditions:

          1. for each edge *\(u, v\)* in *G* such condition should be
             satisfied: 0 <= f\(u,v\) <= c\(u,v\)

          1. Network *G* has source node *s* such that the flow *F* is
             equal to the sum of outcoming flow decreased by the sum of incoming
             flow from that source node *s*\.

          1. Network *G* has sink node *t* such that the the *\-F* value is
             equal to the sum of the incoming flow decreased by the sum of
             outcoming flow from that sink node *t*\.

          1. For each node that is not a
             *[source](\.\./\.\./\.\./\.\./index\.md\#source)* or *sink* the sum
             of incoming flow and sum of outcoming flow should be equal\.

      * *the minimum cost flow problem* \- the goal is finding the cheapest
        possible way of sending a certain amount of flow through a *[flow
        network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*\.

      * *[blocking flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* \- a
        *[blocking flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* for a
        *residual network* *Gf* we name such flow *b* in *Gf* that:

          1. Each path from *sink* to
             *[source](\.\./\.\./\.\./\.\./index\.md\#source)* is the shortest path
             in *Gf*\.

          1. Each shortest path in *Gf* contains an edge with fully used
             throughput in *Gf\+b*\.

      * *residual network* \- for a flow network *G* and flow *f*
        *residual network* is built with those edges, which can send larger
        flow\. It contains only those edges, which can send flow larger than 0\.

      * *level network* \- it has the same set of nodes as *[residual
        graph](\.\./\.\./\.\./\.\./index\.md\#residual\_graph)*, but has only those
        edges *\(u,v\)* from *Gf* for which such equality is satisfied:
        *distance\(s,u\)\+1 = distance\(s,v\)*\.

      * *[augmenting network](\.\./\.\./\.\./\.\./index\.md\#augmenting\_network)* \-
        it is a modification of *residual network* considering the new flow
        values\. Structure stays unchanged but values of throughputs and costs at
        edges are different\.

## <a name='subsection7'></a>Approximation algorithm

  - k\-approximation algorithm:

    Algorithm is a k\-approximation, when for *ALG* \(solution returned by
    algorithm\) and *OPT* \(optimal solution\), such inequality is true:

      * for minimalization problems: *ALG/OPT <= k*

      * for maximalization problems: *OPT/ALG <= k*

# <a name='section4'></a>References

  1. [Adjacency matrix](http://en\.wikipedia\.org/wiki/Adjacency\_matrix)

  1. [Adjacency list](http://en\.wikipedia\.org/wiki/Adjacency\_list)

  - <a name='10'></a>*poolName* __request__ itemVar ?options?

    Handles a request for an item, taking into account a possible preference for
    a particular item\. There are two possible outcomes depending on the
    availability of items:

    The request is honoured, an item is allocated and the variable whose name is
    passed with the argument *itemVar* will be set to the name of the item
    that was allocated\. The command returns 1\.

    The request is denied\. No item is allocated\. The variable whose name is
    itemVar is not set\. Attempts to read *itemVar* may raise an error if the
    variable was not defined before issuing the request\. The command returns 0\.


    The return values from this command are meant to be inspected\. The examples
    below show how to do this\. Failure to check the return value may result in
    erroneous behaviour\. If no preference for a particular item is supplied
    through the option __\-prefer__ \(see below\), then all requests are
    honoured as long as items are available\.

  - <a name='10'></a>*poolName* __request__ itemVar ?options?

    Handles a request for an item, taking into account a possible preference for
    a particular item\. There are two possible outcomes depending on the
    availability of items:

      1. The request is honoured, an item is allocated and the variable whose
         name is passed with the argument *itemVar* will be set to the name of
         the item that was allocated\. The command returns 1\.

      1. The request is denied\. No item is allocated\. The variable whose name is
         itemVar is not set\. Attempts to read *itemVar* may raise an error if
         the variable was not defined before issuing the request\. The command
         returns 0\.

    The return values from this command are meant to be inspected\. The examples
    below show how to do this\. Failure to check the return value may result in
    erroneous behaviour\. If no preference for a particular item is supplied
    through the option __\-prefer__ \(see below\), then all requests are
    honoured as long as items are available\.

        Inversion  = \{\{deleted  \{0  0\} \{\-1 0\}\}
                      \{changed  \{3  3\}  \{2 2\}\}
                      \{deleted  \{6  7\}  \{4 5\}\}
                      \{added   \{10 11\}  \{8 8\}\}\}

    *Notes:*

    An index of __\-1__ in a *deleted* chunk refers to just before the
    first element of the second sequence\.

    Also an index equal to the length of the first sequence in an *added*
    chunk refers to just behind the end of the sequence\.

  - <a name='4'></a>__::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2*

    Similar to __lcsInvert__\. Instead of directly taking the result of a
    call to __longestCommonSubsequence__ this subcommand expects the indices
    for the two sequences in two separate lists\.

        Inversion  = \{\{deleted  \{0  0\} \{\-1 0\}\}
                      \{changed  \{3  3\}  \{2 2\}\}
                      \{deleted  \{6  7\}  \{4 5\}\}
                      \{added   \{10 11\}  \{8 8\}\}\}

    *Notes:*

      * An index of __\-1__ in a *deleted* chunk refers to just before the
        first element of the second sequence\.

      * Also an index equal to the length of the first sequence in an *added*
        chunk refers to just behind the end of the sequence\.

  - <a name='4'></a>__::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2*

    Similar to __lcsInvert__\. Instead of directly taking the result of a
    call to __longestCommonSubsequence__ this subcommand expects the indices
    for the two sequences in two separate lists\.

# <a name='section2'></a>ARGUMENTS

  - ?\-format *format*?

    Specifies the documentation format\. __TEPAM Doc Gen__ provides support
    for the following formats:

    TXT \- Text format \(default\)

    HTML

    POD \- Perl Plain Old Documentation format \(PerlPOD\)

    DT \- TclLib DocTool format

    Section [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4) shows how
    support for additional formats can be added\.

  - ?\-style *style*?

    The documentation is by default generated in Tcl style \(e\.g\. __command

# <a name='section2'></a>ARGUMENTS

  - ?\-format *format*?

    Specifies the documentation format\. __TEPAM Doc Gen__ provides support
    for the following formats:

      * TXT \- Text format \(default\)

      * HTML

      * POD \- Perl Plain Old Documentation format \(PerlPOD\)

      * DT \- TclLib DocTool format

    Section [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4) shows how
    support for additional formats can be added\.

  - ?\-style *style*?

    The documentation is by default generated in Tcl style \(e\.g\. __command

  - __command\_log__

    Procedure calls can be logged inside the list variable
    __tepam::ProcedureCallLogList__\. The variable __tepam::command\_log__
    controls the default logging settings for any procedures\. The following
    configurations are supported:

    *0*: Disables any procedure call loggings

    *1*: Enables any procedure call loggings

    *"interactive"*: Will log any procedures called interactively \(e\.g\.
    procedures called with the \-interactive flag\)\. This is the default
    configuration\.

    This default logging configuration can be changed individually for each
    procedure with the *\-command\_log* attribute\.

# <a name='section5'></a>ARGUMENT TYPES

TEPAM provides a comprehensive set of procedure argument types\. They can easily

  - __command\_log__

    Procedure calls can be logged inside the list variable
    __tepam::ProcedureCallLogList__\. The variable __tepam::command\_log__
    controls the default logging settings for any procedures\. The following
    configurations are supported:

      * *0*: Disables any procedure call loggings

      * *1*: Enables any procedure call loggings

      * *"interactive"*: Will log any procedures called interactively \(e\.g\.
        procedures called with the \-interactive flag\)\. This is the default
        configuration\.

    This default logging configuration can be changed individually for each
    procedure with the *\-command\_log* attribute\.

# <a name='section5'></a>ARGUMENT TYPES

TEPAM provides a comprehensive set of procedure argument types\. They can easily

    *Note* that uncaught errors will leave the *node set* of the object in
    an intermediate state, per the TreeQL operators which were executed
    successfully before the error occurred\.

    The above means in detail that:

    The first argument is interpreted as the name of a query operator, the
    number of arguments required by that operator is then determined, and taken
    from the immediately following arguments\.

    Because of this operators cannot have optional arguments, all arguments have
    to be present as defined\. Failure to do this will, at least, confuse the
    query interpreter, but more likely cause errors\.

    The operator is applied to the current node set, yielding a new node set,
    and/or manipulating the tree object the query object is connected to\.


    The arguments used \(i\.e\. operator name and arguments\) are removed from the
    list of method arguments, and then the whole process is repeated from step
    \[1\], until the list of arguments is empty or an error occurred\.


            \# q is the query object\.

            q query root children get data

            \# The above query
            \# \- Resets the node set to the root node \- root

    *Note* that uncaught errors will leave the *node set* of the object in
    an intermediate state, per the TreeQL operators which were executed
    successfully before the error occurred\.

    The above means in detail that:

      1. The first argument is interpreted as the name of a query operator, the
         number of arguments required by that operator is then determined, and
         taken from the immediately following arguments\.

         Because of this operators cannot have optional arguments, all arguments
         have to be present as defined\. Failure to do this will, at least,
         confuse the query interpreter, but more likely cause errors\.

      1. The operator is applied to the current node set, yielding a new node
         set, and/or manipulating the tree object the query object is connected
         to\.

      1. The arguments used \(i\.e\. operator name and arguments\) are removed from
         the list of method arguments, and then the whole process is repeated
         from step \[1\], until the list of arguments is empty or an error
         occurred\.

            \# q is the query object\.

            q query root children get data

            \# The above query
            \# \- Resets the node set to the root node \- root

'\"
'\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003-2019 Andreas Kupries <[email protected]\&.sourceforge\&.net>
'\"
.TH "doctools" n 1\&.5 tcllib "Documentation tools"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
................................................................................
..
.BS
.SH NAME
doctools \- doctools - Processing documents
.SH SYNOPSIS
package require \fBTcl  8\&.2\fR
.sp
package require \fBdoctools  ?1\&.5?\fR
.sp
\fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.?
.sp
\fB::doctools::help\fR
.sp
\fB::doctools::search\fR \fIpath\fR
.sp

'\"
'\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003-2019 Andreas Kupries <[email protected]\&.sourceforge\&.net>
'\"
.TH "doctools" n 1\&.5\&.1 tcllib "Documentation tools"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
................................................................................
..
.BS
.SH NAME
doctools \- doctools - Processing documents
.SH SYNOPSIS
package require \fBTcl  8\&.2\fR
.sp
package require \fBdoctools  ?1\&.5\&.1?\fR
.sp
\fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.?
.sp
\fB::doctools::help\fR
.sp
\fB::doctools::search\fR \fIpath\fR
.sp

&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools(n) 1.5 tcllib &quot;Documentation tools&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools - doctools - Processing documents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
................................................................................
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">doctools <span class="opt">?1.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::help</b></a></li>
<li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li>
<li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>

&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools(n) 1.5.1 tcllib &quot;Documentation tools&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools - doctools - Processing documents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
................................................................................
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">doctools <span class="opt">?1.5.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::help</b></a></li>
<li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li>
<li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>

[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 1.5]
[manpage_begin doctools n [vset PACKAGE_VERSION]]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_intro]
[see_also doctools_lang_syntax]
[see_also doctools_plugin_apiref]
[keywords conversion]