tDOM

Check-in [36d3888cac]
Login

Check-in [36d3888cac]

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

Overview
Comment:Added some sparse word of documentation.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | keyspaces
Files: files | file ages | folders
SHA3-256: 36d3888cac6644804b6ea08cd6dd13a8001f893518b6682c8d3c4a03404eb7f6
User & Date: rolf 2019-05-30 23:40:17.119
Context
2019-05-30
23:54
Adapt the example section to what is actually implemented. Closed-Leaf check-in: ebb73c9257 user: rolf tags: keyspaces
23:40
Added some sparse word of documentation. check-in: 36d3888cac user: rolf tags: keyspaces
22:38
Added simple keyref feature to keyspaces. check-in: 1f7b8a81c1 user: rolf tags: keyspaces
Changes
Unified Diff Ignore Whitespace Patch
Changes to doc/schema.html. 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<html>
<head>
<link rel="stylesheet" href="manpage.css"><title>tDOM manual: schema</title><meta name="xsl-processor" content="Jochen Loewer ([email protected]), Rolf Ade ([email protected]) 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="#SECTid0x55ce24033b10">NAME</a> · <a href="#SECTid0x55ce24034170">SYNOPSIS</a> · <a href="#SECTid0x55ce2402e5f0">DESCRIPTION </a> · <a href="#SECTid0x55ce2408e1e0">Schema definition scripts</a> · <a href="#SECTid0x55ce24096d00">Quantity specifier</a> · <a href="#SECTid0x55ce24098b90">Text constraint scripts</a> · <a href="#SECTid0x55ce240a0fa0">Exampels</a>
</div><hr class="navsep">
</div><div class="body">
  <h2><a name="SECTid0x55ce24033b10">NAME</a></h2><p class="namesection">
<b class="names">tdom::schema - </b><br>Create a schema validation command</p>

  <h2><a name="SECTid0x55ce24034170">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="SECTid0x55ce2402e5f0">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 or DOM trees (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">
      







|


|


|




|








1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<html>
<head>
<link rel="stylesheet" href="manpage.css"><title>tDOM manual: schema</title><meta name="xsl-processor" content="Jochen Loewer ([email protected]), Rolf Ade ([email protected]) 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="#SECTid0x555cbefafb30">NAME</a> · <a href="#SECTid0x555cbefb0160">SYNOPSIS</a> · <a href="#SECTid0x555cbefaa5d0">DESCRIPTION </a> · <a href="#SECTid0x555cbf00a680">Schema definition scripts</a> · <a href="#SECTid0x555cbf0131a0">Quantity specifier</a> · <a href="#SECTid0x555cbf015030">Text constraint scripts</a> · <a href="#SECTid0x555cbf01d520">Local key constraints</a> · <a href="#SECTid0x555cbf01f330">Exampels</a>
</div><hr class="navsep">
</div><div class="body">
  <h2><a name="SECTid0x555cbefafb30">NAME</a></h2><p class="namesection">
<b class="names">tdom::schema - </b><br>Create a schema validation command</p>

  <h2><a name="SECTid0x555cbefb0160">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="SECTid0x555cbefaa5d0">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 or DOM trees (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">
︙︙
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198

        <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="SECTid0x55ce2408e1e0">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 render the content as valid. It is a
    validation error if the element in the XML source has additional
    (not matched) content.</p><p>The schema definition commands are:</p><dl class="commandlist">








|








184
185
186
187
188
189
190
191
192
193
194
195
196
197
198

        <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="SECTid0x555cbf00a680">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 render the content as valid. It is a
    validation error if the element in the XML source has additional
    (not matched) content.</p><p>The schema definition commands are:</p><dl class="commandlist">
︙︙
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359

        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="SECTid0x55ce24096d00">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. This is the default, if a quantifier is








|








345
346
347
348
349
350
351
352
353
354
355
356
357
358
359

        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="SECTid0x555cbf0131a0">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. This is the default, if a quantifier is
︙︙
390
391
392
393
394
395
396


397
398
399
400
401
402
403
404

        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="SECTid0x55ce24098b90">Text constraint scripts</a></h2><p></p><p>The text constraint commands are:</p><dl class="commandlist">
      
        <dt><b class="cmd">isint</b></dt>
        <dd></dd>
      

      
        <dt>








>
>
|








390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406

        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="SECTid0x555cbf015030">Text constraint scripts</a></h2><p>Text - parsed character data, as XML calles it - must sometimes
    have to be of a certain kind, must comply to some rules etc to be
    valid.</p><p>The text constraint commands are:</p><dl class="commandlist">
      
        <dt><b class="cmd">isint</b></dt>
        <dd></dd>
      

      
        <dt>
︙︙
553
554
555
556
557
558
559
560




































561
562
563
564
565
566
567
568

      
      
        <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="SECTid0x55ce240a0fa0">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.








|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|








555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606

      
      
        <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="SECTid0x555cbf01d520">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">names list&gt;</i> <i class="m">&lt;constraint script&gt;</i>
</dt>
            <dd>Any number of keyspaces are possible. A keyspace is
            either active or not. An inside a <i class="m">constraint
            script&gt;</i> called keyspace with the same name does
            nothing.</dd>
        
    </dl><p>This text constraint commands work with keyspaces:</p><dl class="commandlist">
        
            <dt>
<b class="cmd">key</b> <i class="m">name&gt;</i>
</dt>
            <dd>If the keyspace with the name <i class="m">name&gt;</i> is not
            active always matches. If the keyspace is active then
            reports error if there is already a key with the value.
            Otherwise, stores the value as key in this keyspace and
            matches.</dd>
        
        
            <dt>
<b class="cmd">keyref</b> <i class="m">name&gt;</i>
</dt>
            <dd>If the keyspace with the name <i class="m">name&gt;</i> is not
            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">name&gt;</i>. Otherwise it
            matches.</dd>
        
    </dl>

  <h2><a name="SECTid0x555cbf01f330">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.
︙︙
Changes to doc/schema.n.
︙︙
428
429
430
431
432
433
434



435
436
437
438
439
440
441

quantifier must be a tcl list with two elements. Both elements
must be integers, with n >= 0 and n < m.
.PP
If an optional quantifier is not given then it defaults to * in
case of the mixed command and to ! for all other commands.
.SH "Text constraint scripts"
.PP



.PP
The text constraint commands are:
.TP
\&\fB\fBisint\fP
\&\fR
.TP
\&\fB\fBfixed\fP \fIvalue\fB








>
>
>








428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444

quantifier must be a tcl list with two elements. Both elements
must be integers, with n >= 0 and n < m.
.PP
If an optional quantifier is not given then it defaults to * in
case of the mixed command and to ! for all other commands.
.SH "Text constraint scripts"
.PP
Text - parsed character data, as XML calles it - must sometimes
have to be of a certain kind, must comply to some rules etc to be
valid.
.PP
The text constraint commands are:
.TP
\&\fB\fBisint\fP
\&\fR
.TP
\&\fB\fBfixed\fP \fIvalue\fB
︙︙
560
561
562
563
564
565
566




























567
568
569
570
571
572
573

reference to an ID within the document. The referenced ID may
be later in the document, that the reference. Several
references within the document to one ID are possible.
.TP
\&\fB\fBbase64\fP
\&\fRThis text constraint match if text is valid according to
RFC 4648.




























.SH Exampels
.PP
.UR "https://www.w3.org/TR/xmlschema-0/"
<URL: https://www.w3.org/TR/xmlschema-0/>
.UE
The XML Schema Part 0: Primer Second Edition
() starts with this








>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>








563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604

reference to an ID within the document. The referenced ID may
be later in the document, that the reference. Several
references within the document to one ID are possible.
.TP
\&\fB\fBbase64\fP
\&\fRThis text constraint match if text is valid according to
RFC 4648.
.SH "Local key constraints"
.PP
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.
.TP
\&\fB\fBkeyspace\fP \fInames list>\fB \fI<constraint script>\fB
\&\fRAny number of keyspaces are possible. A keyspace is
either active or not. An inside a \fIconstraint
script>\fR called keyspace with the same name does
nothing.
.PP
This text constraint commands work with keyspaces:
.TP
\&\fB\fBkey\fP \fIname>\fB
\&\fRIf the keyspace with the name \fIname>\fR is not
active always matches. If the keyspace is active then
reports error if there is already a key with the value.
Otherwise, stores the value as key in this keyspace and
matches.
.TP
\&\fB\fBkeyref\fP \fIname>\fB
\&\fRIf the keyspace with the name \fIname>\fR is not
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 \fIname>\fR. Otherwise it
matches.
.SH Exampels
.PP
.UR "https://www.w3.org/TR/xmlschema-0/"
<URL: https://www.w3.org/TR/xmlschema-0/>
.UE
The XML Schema Part 0: Primer Second Edition
() starts with this
︙︙
Changes to doc/schema.xml.
︙︙
367
368
369
370
371
372
373


374
375
376
377
378
379
380
381

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

  <section>
    <title>Text constraint scripts</title>



    <p></p>

    <p>The text constraint commands are:</p>

    <commandlist>
      <commanddef>
        <command><cmd>isint</cmd></command>
        <desc></desc>








>
>
|








367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383

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

  <section>
    <title>Text constraint scripts</title>

    <p>Text - parsed character data, as XML calles it - must sometimes
    have to be of a certain kind, must comply to some rules etc to be
    valid.</p>

    <p>The text constraint commands are:</p>

    <commandlist>
      <commanddef>
        <command><cmd>isint</cmd></command>
        <desc></desc>
︙︙
509
510
511
512
513
514
515
516









































517
518
519
520
521
522
523

      <commanddef>
        <command><cmd>base64</cmd></command>
        <desc>This text constraint match if text is valid according to
        RFC 4648.</desc>
      </commanddef>
    </commandlist>
  </section>
  









































  <section>
    <title>Exampels</title>

    <p>The XML Schema Part 0: Primer Second Edition
    (<url>https://www.w3.org/TR/xmlschema-0/</url>) starts with this
    example schema:</p>









|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>








511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566

      <commanddef>
        <command><cmd>base64</cmd></command>
        <desc>This text constraint match if text is valid according to
        RFC 4648.</desc>
      </commanddef>
    </commandlist>
  </section>

  <section>
    <title>Local key constraints</title>

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

    <commandlist>
        <commanddef>
            <command><cmd>keyspace</cmd> <m>&kt;names list></m> <m>&lt;constraint script></m></command>
            <desc>Any number of keyspaces are possible. A keyspace is
            either active or not. An inside a <m>constraint
            script></m> called keyspace with the same name does
            nothing.</desc>
        </commanddef>
    </commandlist>

    <p>This text constraint commands work with keyspaces:</p>

    <commandlist>
        <commanddef>
            <command><cmd>key</cmd> <m>name></m></command>
            <desc>If the keyspace with the name <m>name></m> is not
            active always matches. If the keyspace is active then
            reports error if there is already a key with the value.
            Otherwise, stores the value as key in this keyspace and
            matches.</desc>
        </commanddef>
        <commanddef>
            <command><cmd>keyref</cmd> <m>name></m></command>
            <desc>If the keyspace with the name <m>name></m> is not
            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 <m>name></m>. Otherwise it
            matches.</desc>
        </commanddef>
    </commandlist>
    
  </section>

  <section>
    <title>Exampels</title>

    <p>The XML Schema Part 0: Primer Second Edition
    (<url>https://www.w3.org/TR/xmlschema-0/</url>) starts with this
    example schema:</p>
︙︙