tDOM: Check-in [c0721894cc]

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

Comment:	Updated documentation example section.
Downloads:	Tarball \| ZIP archive \| SQL archive
Timelines:	family \| ancestors \| descendants \| both \| schema
Files:	files \| file ages \| folders
SHA3-256:	c0721894ccf40573c4617bdb37dd35d7399128005011fc86e731eb74472c62c9
User & Date:	rolf 2019-11-15 15:17:23

Context

2019-11-16
13:09		A few spell fixes. check-in: 7726a079e1 user: rolf tags: schema
2019-11-15
23:46		Started check for ambiguity. check-in: a2f83dea7e user: rolf tags: wip
15:17		Updated documentation example section. check-in: c0721894cc user: rolf tags: schema
13:45		Work on the info method and the documentation for that method. check-in: e3fd3c93a9 user: rolf tags: schema

Changes

Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/schema.html.

<html>
<head>
<link rel="stylesheet" href="manpage.css"><title>tDOM manual: schema</title><meta name="xsl-processor" content="Jochen Loewer (loewerj@hotmail.com), Rolf Ade (rolf@pointsman.de) et. al."><meta name="generator" content="$RCSfile: tmml-html.xsl,v $ $Revision: 1.11 $"><meta charset="utf-8">
</head><body>
<div class="header">
<div class="navbar" align="center">
<a href="#SECTid0x55da2a6a4640">NAME</a> · <a href="#SECTid0x55da2a5f5120">SYNOPSIS</a> · <a href="#SECTid0x55da2a682800">DESCRIPTION </a> · <a href="#SECTid0x55da2a6e0ad0">Schema definition scripts</a> · <a href="#SECTid0x55da2a6eb700">Quantity specifier</a> · <a href="#SECTid0x55da2a6ed550">Text constraint scripts</a> · <a href="#SECTid0x55da2a6f7360">Local key constraints</a> · <a href="#SECTid0x55da2a6f9170">Exampels</a>
</div><hr class="navsep">
</div><div class="body">
  <h2><a name="SECTid0x55da2a6a4640">NAME</a></h2><p class="namesection">
<b class="names">tdom::schema - </b><br>Create a schema validation command</p>

  <h2><a name="SECTid0x55da2a5f5120">SYNOPSIS</a></h2><pre class="syntax">package require tdom

<b class="cmd">tdom::schema</b> <i class="m">?create?</i> <i class="m">cmdName</i>
    </pre>

  <h2><a name="SECTid0x55da2a682800">DESCRIPTION </a></h2><p>This command creates validation commands with a simple API. The
    validation commands have methods to define a schema and are able
    to validate XML data or to post-validate a tDOM DOM tree (and to
    some degree other kind of hierarchical data) against this
    schema.</p><p>Additionally, a validation command may be used as argument to
    the <i class="m">-validateCmd</i> option of the <i class="m">dom parse</i> and the
    <i class="m">expat</i> commands to enable validation additional to what they
    otherwise do.</p><p>The valid methods of the created commands are:</p><dl class="commandlist">
................................................................................
        <dt><b class="method">reset</b></dt>
        <dd>This method resets the validation command into state
        READY (while preserving the defined grammer).</dd>
      

    </dl>

  <h2><a name="SECTid0x55da2a6e0ad0">Schema definition scripts</a></h2><p>Schema definition scripts are ordinary Tcl scripts that are
    evaluatend in the namespace tdom::schema. The below listed schema
    definition commands in this tcl namespace allow to define a wide
    variety of document structures. Every schema definition command
    establish a validation constraint on the content which has to
    match or must be optional to qualify the content as valid. It is a
    validation error if there is additional (not matched) content.</p><p>The schema definition commands are:</p><dl class="commandlist">
      
................................................................................
        call. This is meant as toplevel command of a <i>schemacmd
        define</i> script. This command is not allowed nested in an
        other definition script command and will raise error, if you
        call it there.</dd>
      
    </dl>

  <h2><a name="SECTid0x55da2a6eb700">Quantity specifier</a></h2><p>Serveral schema definition commands expects a quantifier as
    one of their arguments, which specifies how often the content
    particle specified by the command is expected. The valid values
    for a <i class="m">quant</i> argument are:</p><dl class="optlist">
      
        <dt><b>!</b></dt>
        <dd>The content particle must occur exactly once in valid
        documents.</dd>
................................................................................
        n to m times (both inclusive) in a row in valid documents. The
        quantifier must be a tcl list with two elements. Both elements
        must be integers, with n &gt;= 0 and n &lt; m.</dd>
      
    </dl><p>If an optional quantifier is not given then it defaults to * in
    case of the mixed command and to ! for all other commands.</p>

  <h2><a name="SECTid0x55da2a6ed550">Text constraint scripts</a></h2><p>Text - parsed character data, as XML calles it - must sometimes
    be of a certain kind, must comply to some rules etc to be valid.
    The text constraint script arguments to the text, attribute,
    nsattribute and deftext commands allow the following text
    constraint commands to check text for certain properties.</p><p>The text constraint commands are:</p><dl class="commandlist">
      
        <dt>
<b class="cmd">integer</b> <i class="m">?(xsd|tcl)?</i>
................................................................................
      
        <dt><b class="cmd">base64</b></dt>
        <dd>This text constraint match if text is valid according to
        RFC 4648.</dd>
      
    </dl>

  <h2><a name="SECTid0x55da2a6f7360">Local key constraints</a></h2><p>Document wide uniqueness and foreign key constraints are
    available with the text constraint commands id and idref.
    Keyspaces allow for sub-tree local uniqueness and foreign key
    constraints.</p><dl class="commandlist">
        
            <dt>
<b class="cmd">keyspace</b> <i class="m">&lt;names list&gt;</i> <i class="m">&lt;constraint script&gt;</i>
</dt>
................................................................................
            active always matches. If the keyspace is active then
            reports error if there is still no key as the value at the
            end of the keyspace <i class="m">&lt;name&gt;</i>. Otherwise it
            matches.</dd>
        
    </dl>

  <h2><a name="SECTid0x55da2a6f9170">Exampels</a></h2><p>The XML Schema Part 0: Primer Second Edition
    (<a href="https://www.w3.org/TR/xmlschema-0/">https://www.w3.org/TR/xmlschema-0/</a>) starts with this
    example schema:</p><pre class="example">
&lt;xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"&gt;

  &lt;xsd:annotation&gt;
    &lt;xsd:documentation xml:lang="en"&gt;
     Purchase order schema for Example.com.
................................................................................
    defintion script would be:</p><pre class="example">
tdom::schema schema      
schema define {

    # Purchase order schema for Example.com.
    # Copyright 2000 Example.com. All rights reserved.

    element purchaseOrder {ref PurchaseOrderType}


    element comment {text}


    defpattern PurchaseOrderType {
        element shipTo ! {ref USAddress}
        element billTo ! {ref USAddress}
        element comment ?
        element items
        attribute orderDate isodate
    }

    defpattern USAddress {
        element name ! {text}
        element street ! {text}
        element city ! {text}
        element state ! {text}
        element zip ! {text isNumber}
        attribute country ! {fixed "US"}
    }

    defelement items {
        element item * {
            element product ! {text}
            element quantity ! {text {maxExcluse 100}}
            element USPrice ! {text integer}
            element comment
            element shipDate ? {text isodate}
            attribute partNum ! {pattern "\d{3}-[A-Z]{2}"}
        }
    }
}
      
    </pre><p>The RELAX NG Tutorial
    (<a href="http://relaxng.org/tutorial-20011203.html">http://relaxng.org/tutorial-20011203.html</a>) starts with
described at     this example:</p><pre class="example">
Consider a simple XML representation of an email address book:

&lt;addressBook&gt;
  &lt;card&gt;
    &lt;name&gt;John Smith&lt;/name&gt;
    &lt;email&gt;js@example.com&lt;/email&gt;
  &lt;/card&gt;

<html>
<head>
<link rel="stylesheet" href="manpage.css"><title>tDOM manual: schema</title><meta name="xsl-processor" content="Jochen Loewer (loewerj@hotmail.com), Rolf Ade (rolf@pointsman.de) et. al."><meta name="generator" content="$RCSfile: tmml-html.xsl,v $ $Revision: 1.11 $"><meta charset="utf-8">
</head><body>
<div class="header">
<div class="navbar" align="center">
<a href="#SECTid0x56384972a920">NAME</a> · <a href="#SECTid0x563849693ab0">SYNOPSIS</a> · <a href="#SECTid0x563849721800">DESCRIPTION </a> · <a href="#SECTid0x56384977fad0">Schema definition scripts</a> · <a href="#SECTid0x56384978a700">Quantity specifier</a> · <a href="#SECTid0x56384978c550">Text constraint scripts</a> · <a href="#SECTid0x563849796360">Local key constraints</a> · <a href="#SECTid0x563849798170">Exampels</a>
</div><hr class="navsep">
</div><div class="body">
  <h2><a name="SECTid0x56384972a920">NAME</a></h2><p class="namesection">
<b class="names">tdom::schema - </b><br>Create a schema validation command</p>

  <h2><a name="SECTid0x563849693ab0">SYNOPSIS</a></h2><pre class="syntax">package require tdom

<b class="cmd">tdom::schema</b> <i class="m">?create?</i> <i class="m">cmdName</i>
    </pre>

  <h2><a name="SECTid0x563849721800">DESCRIPTION </a></h2><p>This command creates validation commands with a simple API. The
    validation commands have methods to define a schema and are able
    to validate XML data or to post-validate a tDOM DOM tree (and to
    some degree other kind of hierarchical data) against this
    schema.</p><p>Additionally, a validation command may be used as argument to
    the <i class="m">-validateCmd</i> option of the <i class="m">dom parse</i> and the
    <i class="m">expat</i> commands to enable validation additional to what they
    otherwise do.</p><p>The valid methods of the created commands are:</p><dl class="commandlist">
................................................................................
        <dt><b class="method">reset</b></dt>
        <dd>This method resets the validation command into state
        READY (while preserving the defined grammer).</dd>
      

    </dl>

  <h2><a name="SECTid0x56384977fad0">Schema definition scripts</a></h2><p>Schema definition scripts are ordinary Tcl scripts that are
    evaluatend in the namespace tdom::schema. The below listed schema
    definition commands in this tcl namespace allow to define a wide
    variety of document structures. Every schema definition command
    establish a validation constraint on the content which has to
    match or must be optional to qualify the content as valid. It is a
    validation error if there is additional (not matched) content.</p><p>The schema definition commands are:</p><dl class="commandlist">
      
................................................................................
        call. This is meant as toplevel command of a <i>schemacmd
        define</i> script. This command is not allowed nested in an
        other definition script command and will raise error, if you
        call it there.</dd>
      
    </dl>

  <h2><a name="SECTid0x56384978a700">Quantity specifier</a></h2><p>Serveral schema definition commands expects a quantifier as
    one of their arguments, which specifies how often the content
    particle specified by the command is expected. The valid values
    for a <i class="m">quant</i> argument are:</p><dl class="optlist">
      
        <dt><b>!</b></dt>
        <dd>The content particle must occur exactly once in valid
        documents.</dd>
................................................................................
        n to m times (both inclusive) in a row in valid documents. The
        quantifier must be a tcl list with two elements. Both elements
        must be integers, with n &gt;= 0 and n &lt; m.</dd>
      
    </dl><p>If an optional quantifier is not given then it defaults to * in
    case of the mixed command and to ! for all other commands.</p>

  <h2><a name="SECTid0x56384978c550">Text constraint scripts</a></h2><p>Text - parsed character data, as XML calles it - must sometimes
    be of a certain kind, must comply to some rules etc to be valid.
    The text constraint script arguments to the text, attribute,
    nsattribute and deftext commands allow the following text
    constraint commands to check text for certain properties.</p><p>The text constraint commands are:</p><dl class="commandlist">
      
        <dt>
<b class="cmd">integer</b> <i class="m">?(xsd|tcl)?</i>
................................................................................
      
        <dt><b class="cmd">base64</b></dt>
        <dd>This text constraint match if text is valid according to
        RFC 4648.</dd>
      
    </dl>

  <h2><a name="SECTid0x563849796360">Local key constraints</a></h2><p>Document wide uniqueness and foreign key constraints are
    available with the text constraint commands id and idref.
    Keyspaces allow for sub-tree local uniqueness and foreign key
    constraints.</p><dl class="commandlist">
        
            <dt>
<b class="cmd">keyspace</b> <i class="m">&lt;names list&gt;</i> <i class="m">&lt;constraint script&gt;</i>
</dt>
................................................................................
            active always matches. If the keyspace is active then
            reports error if there is still no key as the value at the
            end of the keyspace <i class="m">&lt;name&gt;</i>. Otherwise it
            matches.</dd>
        
    </dl>

  <h2><a name="SECTid0x563849798170">Exampels</a></h2><p>The XML Schema Part 0: Primer Second Edition
    (<a href="https://www.w3.org/TR/xmlschema-0/">https://www.w3.org/TR/xmlschema-0/</a>) starts with this
    example schema:</p><pre class="example">
&lt;xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"&gt;

  &lt;xsd:annotation&gt;
    &lt;xsd:documentation xml:lang="en"&gt;
     Purchase order schema for Example.com.
................................................................................
    defintion script would be:</p><pre class="example">
tdom::schema schema      
schema define {

    # Purchase order schema for Example.com.
    # Copyright 2000 Example.com. All rights reserved.

    defelement purchaseOrder {ref PurchaseOrderType}

    foreach elm {comment name street city state product} {
        defelement $elm text
    }

    defpattern PurchaseOrderType {
        element shipTo ! {ref USAddress}
        element billTo ! {ref USAddress}
        element comment ?
        element items
        attribute orderDate isodate
    }

    defpattern USAddress {
        element name
        element street
        element city
        element state
        element zip ! {text number}
        attribute country ! {fixed "US"}
    }

    defelement items {
        element item * {
            element product
            element quantity ! {text integer}
            element USPrice ! {text number}
            element comment
            element shipDate ? {text isodate}
            attribute partNum ! {pattern "^\d{3}-[A-Z]{2}$"}
        }
    }
}
      
    </pre><p>The RELAX NG Tutorial
    (<a href="http://relaxng.org/tutorial-20011203.html">http://relaxng.org/tutorial-20011203.html</a>) starts with
    this example:</p><pre class="example">
Consider a simple XML representation of an email address book:

&lt;addressBook&gt;
  &lt;card&gt;
    &lt;name&gt;John Smith&lt;/name&gt;
    &lt;email&gt;js@example.com&lt;/email&gt;
  &lt;/card&gt;

Changes to doc/schema.n.


tdom::schema schema      
schema define {

    # Purchase order schema for Example.com.
    # Copyright 2000 Example.com. All rights reserved.

    element purchaseOrder {ref PurchaseOrderType}


    element comment {text}


    defpattern PurchaseOrderType {
        element shipTo ! {ref USAddress}
        element billTo ! {ref USAddress}
        element comment ?
        element items
        attribute orderDate isodate
    }

    defpattern USAddress {
        element name ! {text}
        element street ! {text}
        element city ! {text}
        element state ! {text}
        element zip ! {text isNumber}
        attribute country ! {fixed "US"}
    }

    defelement items {
        element item * {
            element product ! {text}
            element quantity ! {text {maxExcluse 100}}
            element USPrice ! {text integer}
            element comment
            element shipDate ? {text isodate}
            attribute partNum ! {pattern "\ed{3}-[A-Z]{2}"}
        }
    }
}
      
    
.CE
.PP
.UR "http://relaxng.org/tutorial-20011203.html"
<URL: http://relaxng.org/tutorial-20011203.html>
.UE
The RELAX NG Tutorial
() starts with
described at     this example:
.CS

Consider a simple XML representation of an email address book:

<addressBook>
  <card>
    <name>John Smith</name>








|

>
|
>










|
|
|
|
|





|
|
|


|












|


tdom::schema schema      
schema define {

    # Purchase order schema for Example.com.
    # Copyright 2000 Example.com. All rights reserved.

    defelement purchaseOrder {ref PurchaseOrderType}

    foreach elm {comment name street city state product} {
        defelement $elm text
    }

    defpattern PurchaseOrderType {
        element shipTo ! {ref USAddress}
        element billTo ! {ref USAddress}
        element comment ?
        element items
        attribute orderDate isodate
    }

    defpattern USAddress {
        element name
        element street
        element city
        element state
        element zip ! {text number}
        attribute country ! {fixed "US"}
    }

    defelement items {
        element item * {
            element product
            element quantity ! {text integer}
            element USPrice ! {text number}
            element comment
            element shipDate ? {text isodate}
            attribute partNum ! {pattern "^\ed{3}-[A-Z]{2}$"}
        }
    }
}
      
    
.CE
.PP
.UR "http://relaxng.org/tutorial-20011203.html"
<URL: http://relaxng.org/tutorial-20011203.html>
.UE
The RELAX NG Tutorial
() starts with
this example:
.CS

Consider a simple XML representation of an email address book:

<addressBook>
  <card>
    <name>John Smith</name>

Changes to doc/schema.xml.

    <example>
tdom::schema schema      
schema define {

    # Purchase order schema for Example.com.
    # Copyright 2000 Example.com. All rights reserved.

    element purchaseOrder {ref PurchaseOrderType}


    element comment {text}


    defpattern PurchaseOrderType {
        element shipTo ! {ref USAddress}
        element billTo ! {ref USAddress}
        element comment ?
        element items
        attribute orderDate isodate
    }

    defpattern USAddress {
        element name ! {text}
        element street ! {text}
        element city ! {text}
        element state ! {text}
        element zip ! {text isNumber}
        attribute country ! {fixed "US"}
    }

    defelement items {
        element item * {
            element product ! {text}
            element quantity ! {text {maxExcluse 100}}
            element USPrice ! {text integer}
            element comment
            element shipDate ? {text isodate}
            attribute partNum ! {pattern "\d{3}-[A-Z]{2}"}
        }
    }
}
      
    </example>

    <p>The RELAX NG Tutorial
    (<url>http://relaxng.org/tutorial-20011203.html</url>) starts with
described at     this example:</p>

    <example>
Consider a simple XML representation of an email address book:

&lt;addressBook>
  &lt;card>
    &lt;name>John Smith&lt;/name>








|

>
|
>










|
|
|
|
|





|
|
|


|








|

    <example>
tdom::schema schema      
schema define {

    # Purchase order schema for Example.com.
    # Copyright 2000 Example.com. All rights reserved.

    defelement purchaseOrder {ref PurchaseOrderType}

    foreach elm {comment name street city state product} {
        defelement $elm text
    }

    defpattern PurchaseOrderType {
        element shipTo ! {ref USAddress}
        element billTo ! {ref USAddress}
        element comment ?
        element items
        attribute orderDate isodate
    }

    defpattern USAddress {
        element name
        element street
        element city
        element state
        element zip ! {text number}
        attribute country ! {fixed "US"}
    }

    defelement items {
        element item * {
            element product
            element quantity ! {text integer}
            element USPrice ! {text number}
            element comment
            element shipDate ? {text isodate}
            attribute partNum ! {pattern "^\d{3}-[A-Z]{2}$"}
        }
    }
}
      
    </example>

    <p>The RELAX NG Tutorial
    (<url>http://relaxng.org/tutorial-20011203.html</url>) starts with
    this example:</p>

    <example>
Consider a simple XML representation of an email address book:

&lt;addressBook>
  &lt;card>
    &lt;name>John Smith&lt;/name>