helm/DEVEL/pxp/pxp/doc/manual/html/x939.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >The class type node</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.46"><LINK
   8 REL="HOME"
   9 TITLE="The PXP user's guide"
  10 HREF="index.html"><LINK
  11 REL="UP"
  12 TITLE="The objects representing the document"
  13 HREF="c893.html"><LINK
  14 REL="PREVIOUS"
  15 TITLE="The objects representing the document"
  16 HREF="c893.html"><LINK
  17 REL="NEXT"
  18 TITLE="The class type extension"
  19 HREF="x1439.html"><LINK
  20 REL="STYLESHEET"
  21 TYPE="text/css"
  22 HREF="markup.css"></HEAD
  23 ><BODY
  24 CLASS="SECT1"
  25 BGCOLOR="#FFFFFF"
  26 TEXT="#000000"
  27 LINK="#0000FF"
  28 VLINK="#840084"
  29 ALINK="#0000FF"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 WIDTH="100%"
  34 BORDER="0"
  35 CELLPADDING="0"
  36 CELLSPACING="0"
  37 ><TR
  38 ><TH
  39 COLSPAN="3"
  40 ALIGN="center"
  41 >The PXP user's guide</TH
  42 ></TR
  43 ><TR
  44 ><TD
  45 WIDTH="10%"
  46 ALIGN="left"
  47 VALIGN="bottom"
  48 ><A
  49 HREF="c893.html"
  50 >Prev</A
  51 ></TD
  52 ><TD
  53 WIDTH="80%"
  54 ALIGN="center"
  55 VALIGN="bottom"
  56 >Chapter 3. The objects representing the document</TD
  57 ><TD
  58 WIDTH="10%"
  59 ALIGN="right"
  60 VALIGN="bottom"
  61 ><A
  62 HREF="x1439.html"
  63 >Next</A
  64 ></TD
  65 ></TR
  66 ></TABLE
  67 ><HR
  68 ALIGN="LEFT"
  69 WIDTH="100%"></DIV
  70 ><DIV
  71 CLASS="SECT1"
  72 ><H1
  73 CLASS="SECT1"
  74 ><A
  75 NAME="AEN939"
  76 >3.2. The class type <TT
  77 CLASS="LITERAL"
  78 >node</TT
  79 ></A
  80 ></H1
  81 ><P
  82 >&#13;From <TT
  83 CLASS="LITERAL"
  84 >Pxp_document</TT
  85 >:
  86
  87 <PRE
  88 CLASS="PROGRAMLISTING"
  89 >type node_type =
  90   T_data
  91 | T_element of string
  92 | T_super_root
  93 | T_pinstr of string
  94 | T_comment
  95 <TT
  96 CLASS="REPLACEABLE"
  97 ><I
  98 >and some other, reserved types</I
  99 ></TT
 100 >
 101 ;;
 102
 103 class type [ 'ext ] node =
 104   object ('self)
 105     constraint 'ext = 'ext node #extension
 106
 107     <A
 108 NAME="TYPE-NODE-GENERAL.SIG"
 109 ></A
 110 >(* <A
 111 HREF="x939.html#TYPE-NODE-GENERAL"
 112 ><I
 113 ><I
 114 >General observers</I
 115 ></I
 116 ></A
 117 > *)
 118
 119     method extension : 'ext
 120     method dtd : dtd
 121     method parent : 'ext node
 122     method root : 'ext node
 123     method sub_nodes : 'ext node list
 124     method iter_nodes : ('ext node -&gt; unit) -&gt; unit
 125     method iter_nodes_sibl :
 126            ('ext node option -&gt; 'ext node -&gt; 'ext node option -&gt; unit) -&gt; unit
 127     method node_type : node_type
 128     method encoding : Pxp_types.rep_encoding
 129     method data : string
 130     method position : (string * int * int)
 131     method comment : string option
 132     method pinstr : string -&gt; proc_instruction list
 133     method pinstr_names : string list
 134     method write : Pxp_types.output_stream -&#62; Pxp_types.encoding -&#62; unit
 135
 136     <A
 137 NAME="TYPE-NODE-ATTS.SIG"
 138 ></A
 139 >(* <A
 140 HREF="x939.html#TYPE-NODE-ATTS"
 141 ><I
 142 ><I
 143 >Attribute observers</I
 144 ></I
 145 ></A
 146 > *)
 147
 148     method attribute : string -&gt; Pxp_types.att_value
 149     method required_string_attribute : string -&gt; string
 150     method optional_string_attribute : string -&gt; string option
 151     method required_list_attribute : string -&gt; string list
 152     method optional_list_attribute : string -&gt; string list
 153     method attribute_names : string list
 154     method attribute_type : string -&gt; Pxp_types.att_type
 155     method attributes : (string * Pxp_types.att_value) list
 156     method id_attribute_name : string
 157     method id_attribute_value : string
 158     method idref_attribute_names : string
 159
 160     <A
 161 NAME="TYPE-NODE-MODS.SIG"
 162 ></A
 163 >(* <A
 164 HREF="x939.html#TYPE-NODE-MODS"
 165 ><I
 166 ><I
 167 >Modifying methods</I
 168 ></I
 169 ></A
 170 > *)
 171
 172     method add_node : ?force:bool -&gt; 'ext node -&gt; unit
 173     method add_pinstr : proc_instruction -&gt; unit
 174     method delete : unit
 175     method set_nodes : 'ext node list -&gt; unit
 176     method quick_set_attributes : (string * Pxp_types.att_value) list -&gt; unit
 177     method set_comment : string option -&gt; unit
 178
 179     <A
 180 NAME="TYPE-NODE-CLONING.SIG"
 181 ></A
 182 >(* <A
 183 HREF="x939.html#TYPE-NODE-CLONING"
 184 ><I
 185 ><I
 186 >Cloning methods</I
 187 ></I
 188 ></A
 189 > *)
 190
 191     method orphaned_clone : 'self
 192     method orphaned_flat_clone : 'self
 193     method create_element :
 194               ?position:(string * int * int) -&gt;
 195               dtd -&gt; node_type -&gt; (string * string) list -&gt;
 196                   'ext node
 197     method create_data : dtd -&gt; string -&gt; 'ext node
 198     method keep_always_whitespace_mode : unit
 199
 200     <A
 201 NAME="TYPE-NODE-WEIRD.SIG"
 202 ></A
 203 >(* <A
 204 HREF="x939.html#TYPE-NODE-WEIRD"
 205 ><I
 206 ><I
 207 >Validating methods</I
 208 ></I
 209 ></A
 210 > *)
 211
 212     method local_validate : ?use_dfa:bool -&#62; unit -&#62; unit
 213
 214     (* ... Internal methods are undocumented. *)
 215
 216   end
 217 ;;</PRE
 218 >
 219
 220 In the module <TT
 221 CLASS="LITERAL"
 222 >Pxp_types</TT
 223 > you can find another type
 224 definition that is important in this context:
 225
 226 <PRE
 227 CLASS="PROGRAMLISTING"
 228 >type Pxp_types.att_value =
 229     Value     of string
 230   | Valuelist of string list
 231   | Implied_value
 232 ;;</PRE
 233 ></P
 234 ><DIV
 235 CLASS="SECT2"
 236 ><H2
 237 CLASS="SECT2"
 238 ><A
 239 NAME="AEN958"
 240 >3.2.1. The structure of document trees</A
 241 ></H2
 242 ><P
 243 >A node represents either an element or a character data section. There are two
 244 classes implementing the two aspects of nodes: <TT
 245 CLASS="LITERAL"
 246 >element_impl</TT
 247 >
 248 and <TT
 249 CLASS="LITERAL"
 250 >data_impl</TT
 251 >. The latter class does not implement all
 252 methods because some methods do not make sense for data nodes.</P
 253 ><P
 254 >(Note: PXP also supports a mode which forces that processing instructions and
 255 comments are represented as nodes of the document tree. However, these nodes
 256 are instances of <TT
 257 CLASS="LITERAL"
 258 >element_impl</TT
 259 > with node types
 260 <TT
 261 CLASS="LITERAL"
 262 >T_pinstr</TT
 263 > and <TT
 264 CLASS="LITERAL"
 265 >T_comment</TT
 266 >,
 267 respectively. This mode must be explicitly configured; the basic representation
 268 knows only element and data nodes.)</P
 269 ><P
 270 >The following figure
 271 (<A
 272 HREF="x939.html#NODE-TERM"
 273 ><I
 274 ><I
 275 >A tree with element nodes, data nodes, and attributes</I
 276 ><I
 277 ></I
 278 ></I
 279 ></A
 280 >) shows an example how
 281 a tree is constructed from element and data nodes. The circular areas
 282 represent element nodes whereas the ovals denote data nodes. Only elements
 283 may have subnodes; data nodes are always leaves of the tree. The subnodes
 284 of an element can be either element or data nodes; in both cases the O'Caml
 285 objects storing the nodes have the class type <TT
 286 CLASS="LITERAL"
 287 >node</TT
 288 >.</P
 289 ><P
 290 >Attributes (the clouds in the picture) are not directly
 291 integrated into the tree; there is always an extra link to the attribute
 292 list. This is also true for processing instructions (not shown in the
 293 picture). This means that there are separated access methods for attributes and
 294 processing instructions.</P
 295 ><DIV
 296 CLASS="FIGURE"
 297 ><A
 298 NAME="NODE-TERM"
 299 ></A
 300 ><P
 301 ><B
 302 >Figure 3-1. A tree with element nodes, data nodes, and attributes</B
 303 ></P
 304 ><P
 305 ><IMG
 306 SRC="pic/node_term.gif"></P
 307 ></DIV
 308 ><P
 309 >Only elements, data sections, attributes and processing
 310 instructions (and comments, if configured) can, directly or indirectly, occur
 311 in the document tree. It is impossible to add entity references to the tree; if
 312 the parser finds such a reference, not the reference as such but the referenced
 313 text (i.e. the tree representing the structured text) is included in the
 314 tree.</P
 315 ><P
 316 >Note that the parser collapses as much data material into one
 317 data node as possible such that there are normally never two adjacent data
 318 nodes. This invariant is enforced even if data material is included by entity
 319 references or CDATA sections, or if a data sequence is interrupted by
 320 comments. So <TT
 321 CLASS="LITERAL"
 322 >a &amp;amp; b &lt;-- comment --&gt; c &lt;![CDATA[
 323 &lt;&gt; d]]&gt;</TT
 324 > is represented by only one data node, for
 325 instance. However, you can create document trees manually which break this
 326 invariant; it is only the way the parser forms the tree.</P
 327 ><DIV
 328 CLASS="FIGURE"
 329 ><A
 330 NAME="NODE-GENERAL"
 331 ></A
 332 ><P
 333 ><B
 334 >Figure 3-2. Nodes are doubly linked trees</B
 335 ></P
 336 ><P
 337 ><IMG
 338 SRC="pic/node_general.gif"></P
 339 ></DIV
 340 ><P
 341 >The node tree has links in both directions: Every node has a link to its parent
 342 (if any), and it has links to the subnodes (see
 343 figure <A
 344 HREF="x939.html#NODE-GENERAL"
 345 ><I
 346 ><I
 347 >Nodes are doubly linked trees</I
 348 ><I
 349 ></I
 350 ></I
 351 ></A
 352 >). Obviously,
 353 this doubly-linked structure simplifies the navigation in the tree; but has
 354 also some consequences for the possible operations on trees.</P
 355 ><P
 356 >Because every node must have at most <I
 357 CLASS="EMPHASIS"
 358 >one</I
 359 > parent node,
 360 operations are illegal if they violate this condition. The following figure
 361 (<A
 362 HREF="x939.html#NODE-ADD"
 363 ><I
 364 ><I
 365 >A node can only be added if it is a root</I
 366 ><I
 367 ></I
 368 ></I
 369 ></A
 370 >) shows on the left side
 371 that node <TT
 372 CLASS="LITERAL"
 373 >y</TT
 374 > is added to <TT
 375 CLASS="LITERAL"
 376 >x</TT
 377 > as new subnode
 378 which is allowed because <TT
 379 CLASS="LITERAL"
 380 >y</TT
 381 > does not have a parent yet. The
 382 right side of the picture illustrates what would happen if <TT
 383 CLASS="LITERAL"
 384 >y</TT
 385 >
 386 had a parent node; this is illegal because <TT
 387 CLASS="LITERAL"
 388 >y</TT
 389 > would have two
 390 parents after the operation.</P
 391 ><DIV
 392 CLASS="FIGURE"
 393 ><A
 394 NAME="NODE-ADD"
 395 ></A
 396 ><P
 397 ><B
 398 >Figure 3-3. A node can only be added if it is a root</B
 399 ></P
 400 ><P
 401 ><IMG
 402 SRC="pic/node_add.gif"></P
 403 ></DIV
 404 ><P
 405 >The "delete" operation simply removes the links between two nodes. In the
 406 picture (<A
 407 HREF="x939.html#NODE-DELETE"
 408 ><I
 409 ><I
 410 >A deleted node becomes the root of the subtree</I
 411 ><I
 412 ></I
 413 ></I
 414 ></A
 415 >) the node
 416 <TT
 417 CLASS="LITERAL"
 418 >x</TT
 419 > is deleted from the list of subnodes of
 420 <TT
 421 CLASS="LITERAL"
 422 >y</TT
 423 >. After that, <TT
 424 CLASS="LITERAL"
 425 >x</TT
 426 > becomes the root of the
 427 subtree starting at this node.</P
 428 ><DIV
 429 CLASS="FIGURE"
 430 ><A
 431 NAME="NODE-DELETE"
 432 ></A
 433 ><P
 434 ><B
 435 >Figure 3-4. A deleted node becomes the root of the subtree</B
 436 ></P
 437 ><P
 438 ><IMG
 439 SRC="pic/node_delete.gif"></P
 440 ></DIV
 441 ><P
 442 >It is also possible to make a clone of a subtree; illustrated in
 443 <A
 444 HREF="x939.html#NODE-CLONE"
 445 ><I
 446 ><I
 447 >The clone of a subtree</I
 448 ><I
 449 ></I
 450 ></I
 451 ></A
 452 >. In this case, the
 453 clone is a copy of the original subtree except that it is no longer a
 454 subnode. Because cloning never keeps the connection to the parent, the clones
 455 are called <I
 456 CLASS="EMPHASIS"
 457 >orphaned</I
 458 >.</P
 459 ><DIV
 460 CLASS="FIGURE"
 461 ><A
 462 NAME="NODE-CLONE"
 463 ></A
 464 ><P
 465 ><B
 466 >Figure 3-5. The clone of a subtree</B
 467 ></P
 468 ><P
 469 ><IMG
 470 SRC="pic/node_clone.gif"></P
 471 ></DIV
 472 ></DIV
 473 ><DIV
 474 CLASS="SECT2"
 475 ><H2
 476 CLASS="SECT2"
 477 ><A
 478 NAME="AEN1007"
 479 >3.2.2. The methods of the class type <TT
 480 CLASS="LITERAL"
 481 >node</TT
 482 ></A
 483 ></H2
 484 ><A
 485 NAME="TYPE-NODE-GENERAL"
 486 ></A
 487 ><DIV
 488 CLASS="FORMALPARA"
 489 ><P
 490 ><B
 491 >              <A
 492 HREF="x939.html#TYPE-NODE-GENERAL.SIG"
 493 >General observers</A
 494 >
 495             . </B
 496 >             <P
 497 ></P
 498 ><UL
 499 COMPACT="COMPACT"
 500 ><LI
 501 STYLE="list-style-type: disc"
 502 ><P
 503 ><TT
 504 CLASS="LITERAL"
 505 >extension</TT
 506 >: The reference to the extension object which
 507 belongs to this node (see ...).</P
 508 ></LI
 509 ><LI
 510 STYLE="list-style-type: disc"
 511 ><P
 512 ><TT
 513 CLASS="LITERAL"
 514 >dtd</TT
 515 >: Returns a reference to the global DTD. All nodes
 516 of a tree must share the same DTD.</P
 517 ></LI
 518 ><LI
 519 STYLE="list-style-type: disc"
 520 ><P
 521 ><TT
 522 CLASS="LITERAL"
 523 >parent</TT
 524 >: Get the father node. Raises
 525 <TT
 526 CLASS="LITERAL"
 527 >Not_found</TT
 528 > in the case the node does not have a
 529 parent, i.e. the node is the root.</P
 530 ></LI
 531 ><LI
 532 STYLE="list-style-type: disc"
 533 ><P
 534 ><TT
 535 CLASS="LITERAL"
 536 >root</TT
 537 >: Gets the reference to the root node of the tree.
 538 Every node is contained in a tree with a root, so this method always
 539 succeeds. Note that this method <I
 540 CLASS="EMPHASIS"
 541 >searches</I
 542 > the root,
 543 which costs time proportional to the length of the path to the root.</P
 544 ></LI
 545 ><LI
 546 STYLE="list-style-type: disc"
 547 ><P
 548 ><TT
 549 CLASS="LITERAL"
 550 >sub_nodes</TT
 551 >: Returns references to the children. The returned
 552 list reflects the order of the children. For data nodes, this method returns
 553 the empty list.</P
 554 ></LI
 555 ><LI
 556 STYLE="list-style-type: disc"
 557 ><P
 558 ><TT
 559 CLASS="LITERAL"
 560 >iter_nodes f</TT
 561 >: Iterates over the children, and calls
 562 <TT
 563 CLASS="LITERAL"
 564 >f</TT
 565 > for every child in turn. </P
 566 ></LI
 567 ><LI
 568 STYLE="list-style-type: disc"
 569 ><P
 570 ><TT
 571 CLASS="LITERAL"
 572 >iter_nodes_sibl f</TT
 573 >: Iterates over the children, and calls
 574 <TT
 575 CLASS="LITERAL"
 576 >f</TT
 577 > for every child in turn. <TT
 578 CLASS="LITERAL"
 579 >f</TT
 580 > gets as
 581 arguments the previous node, the current node, and the next node.</P
 582 ></LI
 583 ><LI
 584 STYLE="list-style-type: disc"
 585 ><P
 586 ><TT
 587 CLASS="LITERAL"
 588 >node_type</TT
 589 >: Returns either <TT
 590 CLASS="LITERAL"
 591 >T_data</TT
 592 > which
 593 means that the node is a data node, or <TT
 594 CLASS="LITERAL"
 595 >T_element n</TT
 596 >
 597 which means that the node is an element of type <TT
 598 CLASS="LITERAL"
 599 >n</TT
 600 >.
 601 If configured, possible node types are also <TT
 602 CLASS="LITERAL"
 603 >T_pinstr t</TT
 604 >
 605 indicating that the node represents a processing instruction with target
 606 <TT
 607 CLASS="LITERAL"
 608 >t</TT
 609 >, and <TT
 610 CLASS="LITERAL"
 611 >T_comment</TT
 612 > in which case the node
 613 is a comment.</P
 614 ></LI
 615 ><LI
 616 STYLE="list-style-type: disc"
 617 ><P
 618 ><TT
 619 CLASS="LITERAL"
 620 >encoding</TT
 621 >: Returns the encoding of the strings.</P
 622 ></LI
 623 ><LI
 624 STYLE="list-style-type: disc"
 625 ><P
 626 ><TT
 627 CLASS="LITERAL"
 628 >data</TT
 629 >: Returns the character data of this node and all
 630 children, concatenated as one string. The encoding of the string is what
 631 the method <TT
 632 CLASS="LITERAL"
 633 >encoding</TT
 634 > returns.
 635 - For data nodes, this method simply returns the represented characters.
 636 For elements, the meaning of the method has been extended such that it
 637 returns something useful, i.e. the effectively contained characters, without
 638 markup. (For <TT
 639 CLASS="LITERAL"
 640 >T_pinstr</TT
 641 > and <TT
 642 CLASS="LITERAL"
 643 >T_comment</TT
 644 >
 645 nodes, the method returns the empty string.)</P
 646 ></LI
 647 ><LI
 648 STYLE="list-style-type: disc"
 649 ><P
 650 ><TT
 651 CLASS="LITERAL"
 652 >position</TT
 653 >: If configured, this method returns the position of
 654 the element as triple (entity, line, byteposition). For data nodes, the
 655 position is not stored. If the position is not available the triple
 656 <TT
 657 CLASS="LITERAL"
 658 >"?", 0, 0</TT
 659 > is returned.</P
 660 ></LI
 661 ><LI
 662 STYLE="list-style-type: disc"
 663 ><P
 664 ><TT
 665 CLASS="LITERAL"
 666 >comment</TT
 667 >: Returns <TT
 668 CLASS="LITERAL"
 669 >Some text</TT
 670 > for comment
 671 nodes, and <TT
 672 CLASS="LITERAL"
 673 >None</TT
 674 > for other nodes. The <TT
 675 CLASS="LITERAL"
 676 >text</TT
 677 >
 678 is everything between the comment delimiters <TT
 679 CLASS="LITERAL"
 680 >&lt;--</TT
 681 > and
 682 <TT
 683 CLASS="LITERAL"
 684 >--&gt;</TT
 685 >.</P
 686 ></LI
 687 ><LI
 688 STYLE="list-style-type: disc"
 689 ><P
 690 ><TT
 691 CLASS="LITERAL"
 692 >pinstr n</TT
 693 >: Returns all processing instructions that are
 694 directly contained in this element and that have a <I
 695 CLASS="EMPHASIS"
 696 >target</I
 697 >
 698 specification of <TT
 699 CLASS="LITERAL"
 700 >n</TT
 701 >. The target is the first word after
 702 the <TT
 703 CLASS="LITERAL"
 704 >&lt;?</TT
 705 >.</P
 706 ></LI
 707 ><LI
 708 STYLE="list-style-type: disc"
 709 ><P
 710 ><TT
 711 CLASS="LITERAL"
 712 >pinstr_names</TT
 713 >: Returns the list of all targets of processing
 714 instructions directly contained in this element.</P
 715 ></LI
 716 ><LI
 717 STYLE="list-style-type: disc"
 718 ><P
 719 ><TT
 720 CLASS="LITERAL"
 721 >write s enc</TT
 722 >: Prints the node and all subnodes to the passed
 723 output stream as valid XML text, using the passed external encoding.</P
 724 ></LI
 725 ></UL
 726 >
 727             </P
 728 ></DIV
 729 ><A
 730 NAME="TYPE-NODE-ATTS"
 731 ></A
 732 ><DIV
 733 CLASS="FORMALPARA"
 734 ><P
 735 ><B
 736 >              <A
 737 HREF="x939.html#TYPE-NODE-ATTS.SIG"
 738 >Attribute observers</A
 739 >
 740             . </B
 741 >             <P
 742 ></P
 743 ><UL
 744 COMPACT="COMPACT"
 745 ><LI
 746 STYLE="list-style-type: disc"
 747 ><P
 748 ><TT
 749 CLASS="LITERAL"
 750 >attribute n</TT
 751 >: Returns the value of the attribute with name
 752 <TT
 753 CLASS="LITERAL"
 754 >n</TT
 755 >. This method returns a value for every declared
 756 attribute, and it raises <TT
 757 CLASS="LITERAL"
 758 >Not_found</TT
 759 > for any undeclared
 760 attribute. Note that it even returns a value if the attribute is actually
 761 missing but is declared as <TT
 762 CLASS="LITERAL"
 763 >#IMPLIED</TT
 764 > or has a default
 765 value. - Possible values are:
 766                   <P
 767 ></P
 768 ><UL
 769 COMPACT="COMPACT"
 770 ><LI
 771 STYLE="list-style-type: disc"
 772 ><P
 773 ><TT
 774 CLASS="LITERAL"
 775 >Implied_value</TT
 776 >: The attribute has been declared with the
 777 keyword <TT
 778 CLASS="LITERAL"
 779 >#IMPLIED</TT
 780 >, and the attribute is missing in the
 781 attribute list of this element.</P
 782 ></LI
 783 ><LI
 784 STYLE="list-style-type: disc"
 785 ><P
 786 ><TT
 787 CLASS="LITERAL"
 788 >Value s</TT
 789 >: The attribute has been declared as type
 790 <TT
 791 CLASS="LITERAL"
 792 >CDATA</TT
 793 >, as <TT
 794 CLASS="LITERAL"
 795 >ID</TT
 796 >, as
 797 <TT
 798 CLASS="LITERAL"
 799 >IDREF</TT
 800 >, as <TT
 801 CLASS="LITERAL"
 802 >ENTITY</TT
 803 >, or as
 804 <TT
 805 CLASS="LITERAL"
 806 >NMTOKEN</TT
 807 >, or as enumeration or notation, and one of the two
 808 conditions holds: (1) The attribute value is present in the attribute list in
 809 which case the value is returned in the string <TT
 810 CLASS="LITERAL"
 811 >s</TT
 812 >. (2) The
 813 attribute has been omitted, and the DTD declared the attribute with a default
 814 value. The default value is returned in <TT
 815 CLASS="LITERAL"
 816 >s</TT
 817 >.
 818 - Summarized, <TT
 819 CLASS="LITERAL"
 820 >Value s</TT
 821 > is returned for non-implied, non-list
 822 attribute values.</P
 823 ></LI
 824 ><LI
 825 STYLE="list-style-type: disc"
 826 ><P
 827 ><TT
 828 CLASS="LITERAL"
 829 >Valuelist l</TT
 830 >: The attribute has been declared as type
 831 <TT
 832 CLASS="LITERAL"
 833 >IDREFS</TT
 834 >, as <TT
 835 CLASS="LITERAL"
 836 >ENTITIES</TT
 837 >, or
 838 as <TT
 839 CLASS="LITERAL"
 840 >NMTOKENS</TT
 841 >, and one of the two conditions holds: (1) The
 842 attribute value is present in the attribute list in which case the
 843 space-separated tokens of the value are returned in the string list
 844 <TT
 845 CLASS="LITERAL"
 846 >l</TT
 847 >. (2) The attribute has been omitted, and the DTD declared
 848 the attribute with a default value. The default value is returned in
 849 <TT
 850 CLASS="LITERAL"
 851 >l</TT
 852 >.
 853 - Summarized, <TT
 854 CLASS="LITERAL"
 855 >Valuelist l</TT
 856 > is returned for all list-type
 857 attribute values.</P
 858 ></LI
 859 ></UL
 860 >
 861
 862 Note that before the attribute value is returned, the value is normalized. This
 863 means that newlines are converted to spaces, and that references to character
 864 entities (i.e. <TT
 865 CLASS="LITERAL"
 866 >&amp;#<TT
 867 CLASS="REPLACEABLE"
 868 ><I
 869 >n</I
 870 ></TT
 871 >;</TT
 872 >) and
 873 general entities
 874 (i.e. <TT
 875 CLASS="LITERAL"
 876 >&amp;<TT
 877 CLASS="REPLACEABLE"
 878 ><I
 879 >name</I
 880 ></TT
 881 >;</TT
 882 >) are expanded;
 883 if necessary, expansion is performed recursively.</P
 884 ><P
 885 >In well-formedness mode, there is no DTD which could declare an
 886 attribute. Because of this, every occuring attribute is considered as a CDATA
 887 attribute.</P
 888 ></LI
 889 ><LI
 890 STYLE="list-style-type: disc"
 891 ><P
 892 ><TT
 893 CLASS="LITERAL"
 894 >required_string_attribute n</TT
 895 >: returns the Value attribute
 896 called n, or the Valuelist attribute as a string where the list elements
 897 are separated by spaces. If the attribute value is implied, or if the
 898 attribute does not exists, the method will fail. - This method is convenient
 899 if you expect a non-implied and non-list attribute value.</P
 900 ></LI
 901 ><LI
 902 STYLE="list-style-type: disc"
 903 ><P
 904 ><TT
 905 CLASS="LITERAL"
 906 >optional_string_attribute n</TT
 907 >: returns the Value attribute
 908 called n, or the Valuelist attribute as a string where the list elements
 909 are separated by spaces. If the attribute value is implied, or if the
 910 attribute does not exists, the method returns None. - This method is
 911 convenient if you expect a non-list attribute value including the implied
 912 value.</P
 913 ></LI
 914 ><LI
 915 STYLE="list-style-type: disc"
 916 ><P
 917 ><TT
 918 CLASS="LITERAL"
 919 >required_list_attribute n</TT
 920 >: returns the Valuelist attribute
 921 called n, or the Value attribute as a list with a single element.
 922 If the attribute value is implied, or if the
 923 attribute does not exists, the method will fail. - This method is
 924 convenient if you expect a list attribute value.</P
 925 ></LI
 926 ><LI
 927 STYLE="list-style-type: disc"
 928 ><P
 929 ><TT
 930 CLASS="LITERAL"
 931 >optional_list_attribute n</TT
 932 >: returns the Valuelist attribute
 933 called n, or the Value attribute as a list with a single element.
 934 If the attribute value is implied, or if the
 935 attribute does not exists, an empty list will be returned. - This method
 936 is convenient if you expect a list attribute value or the implied value.</P
 937 ></LI
 938 ><LI
 939 STYLE="list-style-type: disc"
 940 ><P
 941 ><TT
 942 CLASS="LITERAL"
 943 >attribute_names</TT
 944 >: returns the list of all attribute names of
 945 this element. As this is a validating parser, this list is equal to the
 946 list of declared attributes.</P
 947 ></LI
 948 ><LI
 949 STYLE="list-style-type: disc"
 950 ><P
 951 ><TT
 952 CLASS="LITERAL"
 953 >attribute_type n</TT
 954 >: returns the type of the attribute called
 955 <TT
 956 CLASS="LITERAL"
 957 >n</TT
 958 >. See the module <TT
 959 CLASS="LITERAL"
 960 >Pxp_types</TT
 961 > for a
 962 description of the encoding of the types.</P
 963 ></LI
 964 ><LI
 965 STYLE="list-style-type: disc"
 966 ><P
 967 ><TT
 968 CLASS="LITERAL"
 969 >attributes</TT
 970 >: returns the list of pairs of names and values
 971 for all attributes of
 972 this element.</P
 973 ></LI
 974 ><LI
 975 STYLE="list-style-type: disc"
 976 ><P
 977 ><TT
 978 CLASS="LITERAL"
 979 >id_attribute_name</TT
 980 >: returns the name of the attribute that is
 981 declared with type ID. There is at most one such attribute. The method raises
 982 <TT
 983 CLASS="LITERAL"
 984 >Not_found</TT
 985 > if there is no declared ID attribute for the
 986 element type.</P
 987 ></LI
 988 ><LI
 989 STYLE="list-style-type: disc"
 990 ><P
 991 ><TT
 992 CLASS="LITERAL"
 993 >id_attribute_value</TT
 994 >: returns the value of the attribute that
 995 is declared with type ID. There is at most one such attribute. The method raises
 996 <TT
 997 CLASS="LITERAL"
 998 >Not_found</TT
 999 > if there is no declared ID attribute for the
1000 element type.</P
1001 ></LI
1002 ><LI
1003 STYLE="list-style-type: disc"
1004 ><P
1005 ><TT
1006 CLASS="LITERAL"
1007 >idref_attribute_names</TT
1008 >: returns the list of attribute names
1009 that are declared as IDREF or IDREFS.</P
1010 ></LI
1011 ></UL
1012 >
1013           </P
1014 ></DIV
1015 ><A
1016 NAME="TYPE-NODE-MODS"
1017 ></A
1018 ><DIV
1019 CLASS="FORMALPARA"
1020 ><P
1021 ><B
1022 >              <A
1023 HREF="x939.html#TYPE-NODE-MODS.SIG"
1024 >Modifying methods</A
1025 >
1026             . </B
1027 >The following methods are only defined for element nodes (more exactly:
1028 the methods are defined for data nodes, too, but fail always).
1029
1030               <P
1031 ></P
1032 ><UL
1033 COMPACT="COMPACT"
1034 ><LI
1035 STYLE="list-style-type: disc"
1036 ><P
1037 ><TT
1038 CLASS="LITERAL"
1039 >add_node sn</TT
1040 >: Adds sub node <TT
1041 CLASS="LITERAL"
1042 >sn</TT
1043 > to the list
1044 of children. This operation is illustrated in the picture
1045 <A
1046 HREF="x939.html#NODE-ADD"
1047 ><I
1048 ><I
1049 >A node can only be added if it is a root</I
1050 ><I
1051 ></I
1052 ></I
1053 ></A
1054 >. This method expects that
1055 <TT
1056 CLASS="LITERAL"
1057 >sn</TT
1058 > is a root, and it requires that <TT
1059 CLASS="LITERAL"
1060 >sn</TT
1061 > and
1062 the current object share the same DTD.</P
1063 ><P
1064 >Because <TT
1065 CLASS="LITERAL"
1066 >add_node</TT
1067 > is the method the parser itself uses
1068 to add new nodes to the tree, it performs by default some simple validation
1069 checks: If the content model is a regular expression, it is not allowed to add
1070 data nodes to this node unless the new nodes consist only of whitespace. In
1071 this case, the new data nodes are silently dropped (you can change this by
1072 invoking <TT
1073 CLASS="LITERAL"
1074 >keep_always_whitespace_mode</TT
1075 >).</P
1076 ><P
1077 >If the document is flagged as stand-alone, these data nodes only
1078 containing whitespace are even forbidden if the element declaration is
1079 contained in an external entity. This case is detected and rejected.</P
1080 ><P
1081 >If the content model is <TT
1082 CLASS="LITERAL"
1083 >EMPTY</TT
1084 >, it is not allowed to
1085 add any data node unless the data node is empty. In this case, the new data
1086 node is silently dropped.</P
1087 ><P
1088 >These checks only apply if there is a DTD. In well-formedness mode, it is
1089 assumed that every element is declared with content model
1090 <TT
1091 CLASS="LITERAL"
1092 >ANY</TT
1093 > which prohibits any validation check. Furthermore, you
1094 turn these checks off by passing <TT
1095 CLASS="LITERAL"
1096 >~force:true</TT
1097 > as first
1098 argument.</P
1099 ></LI
1100 ><LI
1101 STYLE="list-style-type: disc"
1102 ><P
1103 ><TT
1104 CLASS="LITERAL"
1105 >add_pinstr pi</TT
1106 >: Adds the processing instruction
1107 <TT
1108 CLASS="LITERAL"
1109 >pi</TT
1110 > to the list of processing instructions.</P
1111 ></LI
1112 ><LI
1113 STYLE="list-style-type: disc"
1114 ><P
1115 ><TT
1116 CLASS="LITERAL"
1117 >delete</TT
1118 >: Deletes this node from the tree. After this
1119 operation, this node is no longer the child of the former father node; and the
1120 node loses the connection to the father as well. This operation is illustrated
1121 by the figure <A
1122 HREF="x939.html#NODE-DELETE"
1123 ><I
1124 ><I
1125 >A deleted node becomes the root of the subtree</I
1126 ><I
1127 ></I
1128 ></I
1129 ></A
1130 >.</P
1131 ></LI
1132 ><LI
1133 STYLE="list-style-type: disc"
1134 ><P
1135 ><TT
1136 CLASS="LITERAL"
1137 >set_nodes nl</TT
1138 >: Sets the list of children to
1139 <TT
1140 CLASS="LITERAL"
1141 >nl</TT
1142 >. It is required that every member of <TT
1143 CLASS="LITERAL"
1144 >nl</TT
1145 >
1146 is a root, and that all members and the current object share the same DTD.
1147 Unlike <TT
1148 CLASS="LITERAL"
1149 >add_node</TT
1150 >, no validation checks are performed.</P
1151 ></LI
1152 ><LI
1153 STYLE="list-style-type: disc"
1154 ><P
1155 ><TT
1156 CLASS="LITERAL"
1157 >quick_set_attributes atts</TT
1158 >: sets the attributes of this
1159 element to <TT
1160 CLASS="LITERAL"
1161 >atts</TT
1162 >. It is <I
1163 CLASS="EMPHASIS"
1164 >not</I
1165 > checked
1166 whether <TT
1167 CLASS="LITERAL"
1168 >atts</TT
1169 > matches the DTD or not; it is up to the
1170 caller of this method to ensure this. (This method may be useful to transform
1171 the attribute values, i.e. apply a mapping to every attribute.)</P
1172 ></LI
1173 ><LI
1174 STYLE="list-style-type: disc"
1175 ><P
1176 ><TT
1177 CLASS="LITERAL"
1178 >set_comment text</TT
1179 >: This method is only applicable to
1180 <TT
1181 CLASS="LITERAL"
1182 >T_comment</TT
1183 > nodes; it sets the comment text contained by such
1184 nodes. </P
1185 ></LI
1186 ></UL
1187 ></P
1188 ></DIV
1189 ><A
1190 NAME="TYPE-NODE-CLONING"
1191 ></A
1192 ><DIV
1193 CLASS="FORMALPARA"
1194 ><P
1195 ><B
1196 >              <A
1197 HREF="x939.html#TYPE-NODE-CLONING.SIG"
1198 >Cloning methods</A
1199 >
1200             . </B
1201 >             <P
1202 ></P
1203 ><UL
1204 COMPACT="COMPACT"
1205 ><LI
1206 STYLE="list-style-type: disc"
1207 ><P
1208 ><TT
1209 CLASS="LITERAL"
1210 >orphaned_clone</TT
1211 >: Returns a clone of the node and the complete
1212 tree below this node (deep clone). The clone does not have a parent (i.e. the
1213 reference to the parent node is <I
1214 CLASS="EMPHASIS"
1215 >not</I
1216 > cloned). While
1217 copying the subtree, strings are skipped; it is likely that the original tree
1218 and the copy tree share strings. Extension objects are cloned by invoking
1219 the <TT
1220 CLASS="LITERAL"
1221 >clone</TT
1222 > method on the original objects; how much of
1223 the extension objects is cloned depends on the implemention of this method.</P
1224 ><P
1225 >This operation is illustrated by the figure
1226 <A
1227 HREF="x939.html#NODE-CLONE"
1228 ><I
1229 ><I
1230 >The clone of a subtree</I
1231 ><I
1232 ></I
1233 ></I
1234 ></A
1235 >.</P
1236 ></LI
1237 ><LI
1238 STYLE="list-style-type: disc"
1239 ><P
1240 ><TT
1241 CLASS="LITERAL"
1242 >orphaned_flat_clone</TT
1243 >: Returns a clone of the node,
1244 but sets the list of sub nodes to [], i.e. the sub nodes are not cloned.</P
1245 ></LI
1246 ><LI
1247 STYLE="list-style-type: disc"
1248 ><P
1249 ><A
1250 NAME="TYPE-NODE-METH-CREATE-ELEMENT"
1251 ></A
1252 >
1253 <TT
1254 CLASS="LITERAL"
1255 >create_element dtd nt al</TT
1256 >: Returns a flat copy of this node
1257 (which must be an element) with the following modifications: The DTD is set to
1258 <TT
1259 CLASS="LITERAL"
1260 >dtd</TT
1261 >; the node type is set to <TT
1262 CLASS="LITERAL"
1263 >nt</TT
1264 >, and the
1265 new attribute list is set to <TT
1266 CLASS="LITERAL"
1267 >al</TT
1268 > (given as list of
1269 (name,value) pairs). The copy does not have children nor a parent. It does not
1270 contain processing instructions. See
1271 <A
1272 HREF="x939.html#TYPE-NODE-EX-CREATE-ELEMENT"
1273 >the example below</A
1274 >.</P
1275 ><P
1276 >Note that you can specify the position of the new node
1277 by the optional argument <TT
1278 CLASS="LITERAL"
1279 >~position</TT
1280 >.</P
1281 ></LI
1282 ><LI
1283 STYLE="list-style-type: disc"
1284 ><P
1285 ><A
1286 NAME="TYPE-NODE-METH-CREATE-DATA"
1287 ></A
1288 >
1289 <TT
1290 CLASS="LITERAL"
1291 >create_data dtd cdata</TT
1292 >: Returns a flat copy of this node
1293 (which must be a data node) with the following modifications: The DTD is set to
1294 <TT
1295 CLASS="LITERAL"
1296 >dtd</TT
1297 >; the node type is set to <TT
1298 CLASS="LITERAL"
1299 >T_data</TT
1300 >; the
1301 attribute list is empty (data nodes never have attributes); the list of
1302 children and PIs is empty, too (same reason). The new node does not have a
1303 parent. The value <TT
1304 CLASS="LITERAL"
1305 >cdata</TT
1306 > is the new character content of the
1307 node. See
1308 <A
1309 HREF="x939.html#TYPE-NODE-EX-CREATE-DATA"
1310 >the example below</A
1311 >.</P
1312 ></LI
1313 ><LI
1314 STYLE="list-style-type: disc"
1315 ><P
1316 ><TT
1317 CLASS="LITERAL"
1318 >keep_always_whitespace_mode</TT
1319 >: Even data nodes which are
1320 normally dropped because they only contain ignorable whitespace, can added to
1321 this node once this mode is turned on. (This mode is useful to produce
1322 canonical XML.)</P
1323 ></LI
1324 ></UL
1325 ></P
1326 ></DIV
1327 ><A
1328 NAME="TYPE-NODE-WEIRD"
1329 ></A
1330 ><DIV
1331 CLASS="FORMALPARA"
1332 ><P
1333 ><B
1334 >              <A
1335 HREF="x939.html#TYPE-NODE-WEIRD.SIG"
1336 >Validating methods</A
1337 >
1338             . </B
1339 >There is one method which locally validates the node, i.e. checks whether the
1340 subnodes match the content model of this node.
1341
1342               <P
1343 ></P
1344 ><UL
1345 COMPACT="COMPACT"
1346 ><LI
1347 STYLE="list-style-type: disc"
1348 ><P
1349 ><TT
1350 CLASS="LITERAL"
1351 >local_validate</TT
1352 >: Checks that this node conforms to the
1353 DTD by comparing the type of the subnodes with the content model for this
1354 node. (Applications need not call this method unless they add new nodes
1355 themselves to the tree.)</P
1356 ></LI
1357 ></UL
1358 ></P
1359 ></DIV
1360 ></DIV
1361 ><DIV
1362 CLASS="SECT2"
1363 ><H2
1364 CLASS="SECT2"
1365 ><A
1366 NAME="AEN1252"
1367 >3.2.3. The class <TT
1368 CLASS="LITERAL"
1369 >element_impl</TT
1370 ></A
1371 ></H2
1372 ><P
1373 >This class is an implementation of <TT
1374 CLASS="LITERAL"
1375 >node</TT
1376 > which
1377 realizes element nodes:
1378
1379 <PRE
1380 CLASS="PROGRAMLISTING"
1381 >class [ 'ext ] element_impl : 'ext -&#62; [ 'ext ] node</PRE
1382 >&#13;</P
1383 ><DIV
1384 CLASS="FORMALPARA"
1385 ><P
1386 ><B
1387 >Constructor. </B
1388 >You can create a new instance by
1389
1390 <PRE
1391 CLASS="PROGRAMLISTING"
1392 >new element_impl <TT
1393 CLASS="REPLACEABLE"
1394 ><I
1395 >extension_object</I
1396 ></TT
1397 ></PRE
1398 >
1399
1400 which creates a special form of empty element which already contains a
1401 reference to the <TT
1402 CLASS="REPLACEABLE"
1403 ><I
1404 >extension_object</I
1405 ></TT
1406 >, but is
1407 otherwise empty. This special form is called an
1408 <I
1409 CLASS="EMPHASIS"
1410 >exemplar</I
1411 >. The purpose of exemplars is that they serve as
1412 patterns that can be duplicated and filled with data. The method
1413 <A
1414 HREF="x939.html#TYPE-NODE-METH-CREATE-ELEMENT"
1415 ><TT
1416 CLASS="LITERAL"
1417 >create_element</TT
1418 ></A
1419 > is designed to perform this action.</P
1420 ></DIV
1421 ><A
1422 NAME="TYPE-NODE-EX-CREATE-ELEMENT"
1423 ></A
1424 ><DIV
1425 CLASS="FORMALPARA"
1426 ><P
1427 ><B
1428 >Example. </B
1429 >First, create an exemplar by
1430
1431 <PRE
1432 CLASS="PROGRAMLISTING"
1433 >let exemplar_ext = ... in
1434 let exemplar     = new element_impl exemplar_ext in</PRE
1435 >
1436
1437 The <TT
1438 CLASS="LITERAL"
1439 >exemplar</TT
1440 > is not used in node trees, but only as
1441 a pattern when the element nodes are created:
1442
1443 <PRE
1444 CLASS="PROGRAMLISTING"
1445 >let element = exemplar # <A
1446 HREF="x939.html#TYPE-NODE-METH-CREATE-ELEMENT"
1447 >create_element</A
1448 > dtd (T_element name) attlist </PRE
1449 >
1450
1451 The <TT
1452 CLASS="LITERAL"
1453 >element</TT
1454 > is a copy of <TT
1455 CLASS="LITERAL"
1456 >exemplar</TT
1457 >
1458 (even the extension <TT
1459 CLASS="LITERAL"
1460 >exemplar_ext</TT
1461 > has been copied)
1462 which ensures that <TT
1463 CLASS="LITERAL"
1464 >element</TT
1465 > and its extension are objects
1466 of the same class as the exemplars; note that you need not to pass a
1467 class name or other meta information. The copy is initially connected
1468 with the <TT
1469 CLASS="LITERAL"
1470 >dtd</TT
1471 >, it gets a node type, and the attribute list
1472 is filled. The <TT
1473 CLASS="LITERAL"
1474 >element</TT
1475 > is now fully functional; it can
1476 be added to another element as child, and it can contain references to
1477 subnodes.</P
1478 ></DIV
1479 ></DIV
1480 ><DIV
1481 CLASS="SECT2"
1482 ><H2
1483 CLASS="SECT2"
1484 ><A
1485 NAME="AEN1281"
1486 >3.2.4. The class <TT
1487 CLASS="LITERAL"
1488 >data_impl</TT
1489 ></A
1490 ></H2
1491 ><P
1492 >This class is an implementation of <TT
1493 CLASS="LITERAL"
1494 >node</TT
1495 > which
1496 should be used for all character data nodes:
1497
1498 <PRE
1499 CLASS="PROGRAMLISTING"
1500 >class [ 'ext ] data_impl : 'ext -&#62; [ 'ext ] node</PRE
1501 >&#13;</P
1502 ><DIV
1503 CLASS="FORMALPARA"
1504 ><P
1505 ><B
1506 >Constructor. </B
1507 >You can create a new instance by
1508
1509 <PRE
1510 CLASS="PROGRAMLISTING"
1511 >new data_impl <TT
1512 CLASS="REPLACEABLE"
1513 ><I
1514 >extension_object</I
1515 ></TT
1516 ></PRE
1517 >
1518
1519 which creates an empty exemplar node which is connected to
1520 <TT
1521 CLASS="REPLACEABLE"
1522 ><I
1523 >extension_object</I
1524 ></TT
1525 >. The node does not contain a
1526 reference to any DTD, and because of this it cannot be added to node trees.</P
1527 ></DIV
1528 ><P
1529 >To get a fully working data node, apply the method
1530 <A
1531 HREF="x939.html#TYPE-NODE-METH-CREATE-DATA"
1532 ><TT
1533 CLASS="LITERAL"
1534 >create_data</TT
1535 ></A
1536 > to the exemplar (see example).</P
1537 ><A
1538 NAME="TYPE-NODE-EX-CREATE-DATA"
1539 ></A
1540 ><DIV
1541 CLASS="FORMALPARA"
1542 ><P
1543 ><B
1544 >Example. </B
1545 >First, create an exemplar by
1546
1547 <PRE
1548 CLASS="PROGRAMLISTING"
1549 >let exemplar_ext = ... in
1550 let exemplar     = new exemplar_ext data_impl in</PRE
1551 >
1552
1553 The <TT
1554 CLASS="LITERAL"
1555 >exemplar</TT
1556 > is not used in node trees, but only as
1557 a pattern when the data nodes are created:
1558
1559 <PRE
1560 CLASS="PROGRAMLISTING"
1561 >let data_node = exemplar # <A
1562 HREF="x939.html#TYPE-NODE-METH-CREATE-DATA"
1563 >create_data</A
1564 > dtd "The characters contained in the data node" </PRE
1565 >
1566
1567 The <TT
1568 CLASS="LITERAL"
1569 >data_node</TT
1570 > is a copy of <TT
1571 CLASS="LITERAL"
1572 >exemplar</TT
1573 >.
1574 The copy is initially connected
1575 with the <TT
1576 CLASS="LITERAL"
1577 >dtd</TT
1578 >, and it is filled with character material.
1579 The <TT
1580 CLASS="LITERAL"
1581 >data_node</TT
1582 > is now fully functional; it can
1583 be added to an element as child.</P
1584 ></DIV
1585 ></DIV
1586 ><DIV
1587 CLASS="SECT2"
1588 ><H2
1589 CLASS="SECT2"
1590 ><A
1591 NAME="AEN1308"
1592 >3.2.5. The type <TT
1593 CLASS="LITERAL"
1594 >spec</TT
1595 ></A
1596 ></H2
1597 ><P
1598 >The type <TT
1599 CLASS="LITERAL"
1600 >spec</TT
1601 > defines a way to handle the details of
1602 creating nodes from exemplars.
1603
1604 <PRE
1605 CLASS="PROGRAMLISTING"
1606 >type 'ext spec
1607 constraint 'ext = 'ext node #extension
1608
1609 val make_spec_from_mapping :
1610       ?super_root_exemplar : 'ext node -&#62;
1611       ?comment_exemplar : 'ext node -&#62;
1612       ?default_pinstr_exemplar : 'ext node -&#62;
1613       ?pinstr_mapping : (string, 'ext node) Hashtbl.t -&#62;
1614       data_exemplar: 'ext node -&#62;
1615       default_element_exemplar: 'ext node -&#62;
1616       element_mapping: (string, 'ext node) Hashtbl.t -&#62;
1617       unit -&#62;
1618         'ext spec
1619
1620 val make_spec_from_alist :
1621       ?super_root_exemplar : 'ext node -&#62;
1622       ?comment_exemplar : 'ext node -&#62;
1623       ?default_pinstr_exemplar : 'ext node -&#62;
1624       ?pinstr_alist : (string * 'ext node) list -&#62;
1625       data_exemplar: 'ext node -&#62;
1626       default_element_exemplar: 'ext node -&#62;
1627       element_alist: (string * 'ext node) list -&#62;
1628       unit -&#62;
1629         'ext spec</PRE
1630 >
1631
1632 The two functions <TT
1633 CLASS="LITERAL"
1634 >make_spec_from_mapping</TT
1635 > and
1636 <TT
1637 CLASS="LITERAL"
1638 >make_spec_from_alist</TT
1639 > create <TT
1640 CLASS="LITERAL"
1641 >spec</TT
1642 >
1643 values. Both functions are functionally equivalent and the only difference is
1644 that the first function prefers hashtables and the latter associative lists to
1645 describe mappings from names to exemplars.</P
1646 ><P
1647 >You can specify exemplars for the various kinds of nodes that need to be
1648 generated when an XML document is parsed:
1649
1650 <P
1651 ></P
1652 ><UL
1653 COMPACT="COMPACT"
1654 ><LI
1655 STYLE="list-style-type: disc"
1656 ><P
1657 ><TT
1658 CLASS="LITERAL"
1659 >~super_root_exemplar</TT
1660 >: This exemplar
1661 is used to create the super root. This special node is only created if the
1662 corresponding configuration option has been selected; it is the parent node of
1663 the root node which may be convenient if every working node must have a parent.</P
1664 ></LI
1665 ><LI
1666 STYLE="list-style-type: disc"
1667 ><P
1668 ><TT
1669 CLASS="LITERAL"
1670 >~comment_exemplar</TT
1671 >: This exemplar is
1672 used when a comment node must be created. Note that such nodes are only created
1673 if the corresponding configuration option is "on".</P
1674 ></LI
1675 ><LI
1676 STYLE="list-style-type: disc"
1677 ><P
1678 ><TT
1679 CLASS="LITERAL"
1680 >~default_pinstr_exemplar</TT
1681 >: If a node
1682 for a processing instruction must be created, and the instruction is not listed
1683 in the table passed by <TT
1684 CLASS="LITERAL"
1685 >~pinstr_mapping</TT
1686 > or
1687 <TT
1688 CLASS="LITERAL"
1689 >~pinstr_alist</TT
1690 >, this exemplar is used.
1691 Again the configuration option must be "on" in order to create such nodes at
1692 all. </P
1693 ></LI
1694 ><LI
1695 STYLE="list-style-type: disc"
1696 ><P
1697 ><TT
1698 CLASS="LITERAL"
1699 >~pinstr_mapping</TT
1700 > or
1701 <TT
1702 CLASS="LITERAL"
1703 >~pinstr_alist</TT
1704 >: Map the target names of processing
1705 instructions to exemplars. These mappings are only used when nodes for
1706 processing instructions are created.</P
1707 ></LI
1708 ><LI
1709 STYLE="list-style-type: disc"
1710 ><P
1711 ><TT
1712 CLASS="LITERAL"
1713 >~data_exemplar</TT
1714 >: The exemplar for
1715 ordinary data nodes.</P
1716 ></LI
1717 ><LI
1718 STYLE="list-style-type: disc"
1719 ><P
1720 ><TT
1721 CLASS="LITERAL"
1722 >~default_element_exemplar</TT
1723 >: This
1724 exemplar is used if an element node must be created, but the element type
1725 cannot be found in the tables <TT
1726 CLASS="LITERAL"
1727 >element_mapping</TT
1728 > or
1729 <TT
1730 CLASS="LITERAL"
1731 >element_alist</TT
1732 >.</P
1733 ></LI
1734 ><LI
1735 STYLE="list-style-type: disc"
1736 ><P
1737 ><TT
1738 CLASS="LITERAL"
1739 >~element_mapping</TT
1740 > or
1741 <TT
1742 CLASS="LITERAL"
1743 >~element_alist</TT
1744 >: Map the element types to exemplars. These
1745 mappings are used to create element nodes.</P
1746 ></LI
1747 ></UL
1748 >
1749
1750 In most cases, you only want to create <TT
1751 CLASS="LITERAL"
1752 >spec</TT
1753 > values to pass
1754 them to the parser functions found in <TT
1755 CLASS="LITERAL"
1756 >Pxp_yacc</TT
1757 >. However, it
1758 might be useful to apply <TT
1759 CLASS="LITERAL"
1760 >spec</TT
1761 > values directly.</P
1762 ><P
1763 >The following functions create various types of nodes by selecting the
1764 corresponding exemplar from the passed <TT
1765 CLASS="LITERAL"
1766 >spec</TT
1767 > value, and by
1768 calling <TT
1769 CLASS="LITERAL"
1770 >create_element</TT
1771 > or <TT
1772 CLASS="LITERAL"
1773 >create_data</TT
1774 > on
1775 the exemplar.
1776
1777 <PRE
1778 CLASS="PROGRAMLISTING"
1779 >val create_data_node :
1780       'ext spec -&#62;
1781       dtd -&#62;
1782       (* data material: *) string -&#62;
1783           'ext node
1784
1785 val create_element_node :
1786       ?position:(string * int * int) -&#62;
1787       'ext spec -&#62;
1788       dtd -&#62;
1789       (* element type: *) string -&#62;
1790       (* attributes: *) (string * string) list -&#62;
1791           'ext node
1792
1793 val create_super_root_node :
1794       ?position:(string * int * int) -&#62;
1795       'ext spec -&#62;
1796        dtd -&#62;
1797            'ext node
1798
1799 val create_comment_node :
1800       ?position:(string * int * int) -&#62;
1801       'ext spec -&#62;
1802       dtd -&#62;
1803       (* comment text: *) string -&#62;
1804           'ext node
1805
1806 val create_pinstr_node :
1807       ?position:(string * int * int) -&#62;
1808       'ext spec -&#62;
1809       dtd -&#62;
1810       proc_instruction -&#62;
1811           'ext node</PRE
1812 ></P
1813 ></DIV
1814 ><DIV
1815 CLASS="SECT2"
1816 ><H2
1817 CLASS="SECT2"
1818 ><A
1819 NAME="AEN1354"
1820 >3.2.6. Examples</A
1821 ></H2
1822 ><DIV
1823 CLASS="FORMALPARA"
1824 ><P
1825 ><B
1826 >Building trees. </B
1827 >Here is the piece of code that creates the tree of
1828 the figure <A
1829 HREF="x939.html#NODE-TERM"
1830 ><I
1831 ><I
1832 >A tree with element nodes, data nodes, and attributes</I
1833 ><I
1834 ></I
1835 ></I
1836 ></A
1837 >. The extension
1838 object and the DTD are beyond the scope of this example.
1839
1840 <PRE
1841 CLASS="PROGRAMLISTING"
1842 >let exemplar_ext = ... (* some extension *) in
1843 let dtd = ... (* some DTD *) in
1844
1845 let element_exemplar = new element_impl exemplar_ext in
1846 let data_exemplar    = new data_impl    exemplar_ext in
1847
1848 let a1 = element_exemplar # create_element dtd (T_element "a") ["att", "apple"]
1849 and b1 = element_exemplar # create_element dtd (T_element "b") []
1850 and c1 = element_exemplar # create_element dtd (T_element "c") []
1851 and a2 = element_exemplar # create_element dtd (T_element "a") ["att", "orange"]
1852 in
1853
1854 let cherries = data_exemplar # create_data dtd "Cherries" in
1855 let orange   = data_exemplar # create_data dtd "An orange" in
1856
1857 a1 # add_node b1;
1858 a1 # add_node c1;
1859 b1 # add_node a2;
1860 b1 # add_node cherries;
1861 a2 # add_node orange;</PRE
1862 >
1863
1864 Alternatively, the last block of statements could also be written as:
1865
1866 <PRE
1867 CLASS="PROGRAMLISTING"
1868 >a1 # set_nodes [b1; c1];
1869 b1 # set_nodes [a2; cherries];
1870 a2 # set_nodes [orange];</PRE
1871 >
1872
1873 The root of the tree is <TT
1874 CLASS="LITERAL"
1875 >a1</TT
1876 >, i.e. it is true that
1877
1878 <PRE
1879 CLASS="PROGRAMLISTING"
1880 >x # root == a1</PRE
1881 >
1882
1883 for every x from { <TT
1884 CLASS="LITERAL"
1885 >a1</TT
1886 >, <TT
1887 CLASS="LITERAL"
1888 >a2</TT
1889 >,
1890 <TT
1891 CLASS="LITERAL"
1892 >b1</TT
1893 >, <TT
1894 CLASS="LITERAL"
1895 >c1</TT
1896 >, <TT
1897 CLASS="LITERAL"
1898 >cherries</TT
1899 >,
1900 <TT
1901 CLASS="LITERAL"
1902 >orange</TT
1903 > }.</P
1904 ></DIV
1905 ><P
1906 >Furthermore, the following properties hold:
1907
1908 <PRE
1909 CLASS="PROGRAMLISTING"
1910 >  a1 # attribute "att" = Value "apple"
1911 &#38; a2 # attribute "att" = Value "orange"
1912
1913 &#38; cherries # data = "Cherries"
1914 &#38;   orange # data = "An orange"
1915 &#38;       a1 # data = "CherriesAn orange"
1916
1917 &#38;       a1 # node_type = T_element "a"
1918 &#38;       a2 # node_type = T_element "a"
1919 &#38;       b1 # node_type = T_element "b"
1920 &#38;       c1 # node_type = T_element "c"
1921 &#38; cherries # node_type = T_data
1922 &#38;   orange # node_type = T_data
1923
1924 &#38;       a1 # sub_nodes = [ b1; c1 ]
1925 &#38;       a2 # sub_nodes = [ orange ]
1926 &#38;       b1 # sub_nodes = [ a2; cherries ]
1927 &#38;       c1 # sub_nodes = []
1928 &#38; cherries # sub_nodes = []
1929 &#38;   orange # sub_nodes = []
1930
1931 &#38;       a2 # parent == a1
1932 &#38;       b1 # parent == b1
1933 &#38;       c1 # parent == a1
1934 &#38; cherries # parent == b1
1935 &#38;   orange # parent == a2</PRE
1936 ></P
1937 ><DIV
1938 CLASS="FORMALPARA"
1939 ><P
1940 ><B
1941 >Searching nodes. </B
1942 >The following function searches all nodes of a tree
1943 for which a certain condition holds:
1944
1945 <PRE
1946 CLASS="PROGRAMLISTING"
1947 >let rec search p t =
1948   if p t then
1949     t :: search_list p (t # sub_nodes)
1950   else
1951     search_list p (t # sub_nodes)
1952
1953 and search_list p l =
1954   match l with
1955     []      -&gt; []
1956   | t :: l' -&gt; (search p t) @ (search_list p l')
1957 ;;</PRE
1958 ></P
1959 ></DIV
1960 ><P
1961 >For example, if you want to search all elements of a certain
1962 type <TT
1963 CLASS="LITERAL"
1964 >et</TT
1965 >, the function <TT
1966 CLASS="LITERAL"
1967 >search</TT
1968 > can be
1969 applied as follows:
1970
1971 <PRE
1972 CLASS="PROGRAMLISTING"
1973 >let search_element_type et t =
1974   search (fun x -&gt; x # node_type = T_element et) t
1975 ;;</PRE
1976 ></P
1977 ><DIV
1978 CLASS="FORMALPARA"
1979 ><P
1980 ><B
1981 >Getting attribute values. </B
1982 >Suppose we have the declaration:
1983
1984 <PRE
1985 CLASS="PROGRAMLISTING"
1986 >&#60;!ATTLIST e a CDATA #REQUIRED
1987             b CDATA #IMPLIED
1988             c CDATA "12345"&#62;</PRE
1989 >
1990
1991 In this case, every element <TT
1992 CLASS="LITERAL"
1993 >e</TT
1994 > must have an attribute
1995 <TT
1996 CLASS="LITERAL"
1997 >a</TT
1998 >, otherwise the parser would indicate an error. If
1999 the O'Caml variable <TT
2000 CLASS="LITERAL"
2001 >n</TT
2002 > holds the node of the tree
2003 corresponding to the element, you can get the value of the attribute
2004 <TT
2005 CLASS="LITERAL"
2006 >a</TT
2007 > by
2008
2009 <PRE
2010 CLASS="PROGRAMLISTING"
2011 >let value_of_a = n # required_string_attribute "a"</PRE
2012 >
2013
2014 which is more or less an abbreviation for
2015
2016 <PRE
2017 CLASS="PROGRAMLISTING"
2018 >let value_of_a =
2019   match n # attribute "a" with
2020     Value s -&#62; s
2021   | _       -&#62; assert false</PRE
2022 >
2023
2024 - as the attribute is required, the <TT
2025 CLASS="LITERAL"
2026 >attribute</TT
2027 > method always
2028 returns a <TT
2029 CLASS="LITERAL"
2030 >Value</TT
2031 >.</P
2032 ></DIV
2033 ><P
2034 >In contrast to this, the attribute <TT
2035 CLASS="LITERAL"
2036 >b</TT
2037 > can be
2038 omitted. In this case, the method <TT
2039 CLASS="LITERAL"
2040 >required_string_attribute</TT
2041 >
2042 works only if the attribute is there, and the method will fail if the attribute
2043 is missing. To get the value, you can apply the method
2044 <TT
2045 CLASS="LITERAL"
2046 >optional_string_attribute</TT
2047 >:
2048
2049 <PRE
2050 CLASS="PROGRAMLISTING"
2051 >let value_of_b = n # optional_string_attribute "b"</PRE
2052 >
2053
2054 Now, <TT
2055 CLASS="LITERAL"
2056 >value_of_b</TT
2057 > is of type <TT
2058 CLASS="LITERAL"
2059 >string option</TT
2060 >,
2061 and <TT
2062 CLASS="LITERAL"
2063 >None</TT
2064 > represents the omitted attribute. Alternatively,
2065 you could also use <TT
2066 CLASS="LITERAL"
2067 >attribute</TT
2068 >:
2069
2070 <PRE
2071 CLASS="PROGRAMLISTING"
2072 >let value_of_b =
2073   match n # attribute "b" with
2074     Value s       -&#62; Some s
2075   | Implied_value -&#62; None
2076   | _             -&#62; assert false</PRE
2077 ></P
2078 ><P
2079 >The attribute <TT
2080 CLASS="LITERAL"
2081 >c</TT
2082 > behaves much like
2083 <TT
2084 CLASS="LITERAL"
2085 >a</TT
2086 >, because it has always a value. If the attribute is
2087 omitted, the default, here "12345", will be returned instead. Because of this,
2088 you can again use <TT
2089 CLASS="LITERAL"
2090 >required_string_attribute</TT
2091 > to get the
2092 value.</P
2093 ><P
2094 >The type <TT
2095 CLASS="LITERAL"
2096 >CDATA</TT
2097 > is the most general string
2098 type. The types <TT
2099 CLASS="LITERAL"
2100 >NMTOKEN</TT
2101 >, <TT
2102 CLASS="LITERAL"
2103 >ID</TT
2104 >,
2105 <TT
2106 CLASS="LITERAL"
2107 >IDREF</TT
2108 >, <TT
2109 CLASS="LITERAL"
2110 >ENTITY</TT
2111 >, and all enumerators and
2112 notations are special forms of string types that restrict the possible
2113 values. From O'Caml, they behave like <TT
2114 CLASS="LITERAL"
2115 >CDATA</TT
2116 >, i.e. you can
2117 use the methods <TT
2118 CLASS="LITERAL"
2119 >required_string_attribute</TT
2120 > and
2121 <TT
2122 CLASS="LITERAL"
2123 >optional_string_attribute</TT
2124 >, too.</P
2125 ><P
2126 >In contrast to this, the types <TT
2127 CLASS="LITERAL"
2128 >NMTOKENS</TT
2129 >,
2130 <TT
2131 CLASS="LITERAL"
2132 >IDREFS</TT
2133 >, and <TT
2134 CLASS="LITERAL"
2135 >ENTITIES</TT
2136 > mean lists of
2137 strings. Suppose we have the declaration:
2138
2139 <PRE
2140 CLASS="PROGRAMLISTING"
2141 >&#60;!ATTLIST f d NMTOKENS #REQUIRED
2142             e NMTOKENS #IMPLIED&#62;</PRE
2143 >
2144
2145 The type <TT
2146 CLASS="LITERAL"
2147 >NMTOKENS</TT
2148 > stands for lists of space-separated
2149 tokens; for example the value <TT
2150 CLASS="LITERAL"
2151 >"1 abc 23ef"</TT
2152 > means the list
2153 <TT
2154 CLASS="LITERAL"
2155 >["1"; "abc"; "23ef"]</TT
2156 >. (Again, <TT
2157 CLASS="LITERAL"
2158 >IDREFS</TT
2159 >
2160 and <TT
2161 CLASS="LITERAL"
2162 >ENTITIES</TT
2163 > have more restricted values.) To get the
2164 value of attribute <TT
2165 CLASS="LITERAL"
2166 >d</TT
2167 >, one can use
2168
2169 <PRE
2170 CLASS="PROGRAMLISTING"
2171 >let value_of_d = n # required_list_attribute "d"</PRE
2172 >
2173
2174 or
2175
2176 <PRE
2177 CLASS="PROGRAMLISTING"
2178 >let value_of_d =
2179   match n # attribute "d" with
2180     Valuelist l -&#62; l
2181   | _           -&#62; assert false</PRE
2182 >
2183
2184 As <TT
2185 CLASS="LITERAL"
2186 >d</TT
2187 > is required, the attribute cannot be omitted, and
2188 the <TT
2189 CLASS="LITERAL"
2190 >attribute</TT
2191 > method returns always a
2192 <TT
2193 CLASS="LITERAL"
2194 >Valuelist</TT
2195 >. </P
2196 ><P
2197 >For optional attributes like <TT
2198 CLASS="LITERAL"
2199 >e</TT
2200 >, apply
2201
2202 <PRE
2203 CLASS="PROGRAMLISTING"
2204 >let value_of_e = n # optional_list_attribute "e"</PRE
2205 >
2206
2207 or
2208
2209 <PRE
2210 CLASS="PROGRAMLISTING"
2211 >let value_of_e =
2212   match n # attribute "e" with
2213     Valuelist l   -&#62; l
2214   | Implied_value -&#62; []
2215   | _             -&#62; assert false</PRE
2216 >
2217
2218 Here, the case that the attribute is missing counts like the empty list.</P
2219 ></DIV
2220 ><DIV
2221 CLASS="SECT2"
2222 ><H2
2223 CLASS="SECT2"
2224 ><A
2225 NAME="AEN1435"
2226 >3.2.7. Iterators</A
2227 ></H2
2228 ><P
2229 >There are also several iterators in Pxp_document; please see
2230 the mli file for details. You can find examples for them in the
2231 "simple_transformation" directory.
2232
2233 <PRE
2234 CLASS="PROGRAMLISTING"
2235 >val find : ?deeply:bool -&#62;
2236            f:('ext node -&#62; bool) -&#62; 'ext node -&#62; 'ext node
2237
2238 val find_all : ?deeply:bool -&#62;
2239                f:('ext node -&#62; bool) -&#62; 'ext node -&#62; 'ext node list
2240
2241 val find_element : ?deeply:bool -&#62;
2242                    string -&#62; 'ext node -&#62; 'ext node
2243
2244 val find_all_elements : ?deeply:bool -&#62;
2245                         string -&#62; 'ext node -&#62; 'ext node list
2246
2247 exception Skip
2248 val map_tree :  pre:('exta node -&#62; 'extb node) -&#62;
2249                ?post:('extb node -&#62; 'extb node) -&#62;
2250                'exta node -&#62;
2251                    'extb node
2252
2253
2254 val map_tree_sibl :
2255         pre: ('exta node option -&#62; 'exta node -&#62; 'exta node option -&#62;
2256                   'extb node) -&#62;
2257        ?post:('extb node option -&#62; 'extb node -&#62; 'extb node option -&#62;
2258                   'extb node) -&#62;
2259        'exta node -&#62;
2260            'extb node
2261
2262 val iter_tree : ?pre:('ext node -&#62; unit) -&#62;
2263                 ?post:('ext node -&#62; unit) -&#62;
2264                 'ext node -&#62;
2265                     unit
2266
2267 val iter_tree_sibl :
2268        ?pre: ('ext node option -&#62; 'ext node -&#62; 'ext node option -&#62; unit) -&#62;
2269        ?post:('ext node option -&#62; 'ext node -&#62; 'ext node option -&#62; unit) -&#62;
2270        'ext node -&#62;
2271            unit</PRE
2272 ></P
2273 ></DIV
2274 ></DIV
2275 ><DIV
2276 CLASS="NAVFOOTER"
2277 ><HR
2278 ALIGN="LEFT"
2279 WIDTH="100%"><TABLE
2280 WIDTH="100%"
2281 BORDER="0"
2282 CELLPADDING="0"
2283 CELLSPACING="0"
2284 ><TR
2285 ><TD
2286 WIDTH="33%"
2287 ALIGN="left"
2288 VALIGN="top"
2289 ><A
2290 HREF="c893.html"
2291 >Prev</A
2292 ></TD
2293 ><TD
2294 WIDTH="34%"
2295 ALIGN="center"
2296 VALIGN="top"
2297 ><A
2298 HREF="index.html"
2299 >Home</A
2300 ></TD
2301 ><TD
2302 WIDTH="33%"
2303 ALIGN="right"
2304 VALIGN="top"
2305 ><A
2306 HREF="x1439.html"
2307 >Next</A
2308 ></TD
2309 ></TR
2310 ><TR
2311 ><TD
2312 WIDTH="33%"
2313 ALIGN="left"
2314 VALIGN="top"
2315 >The objects representing the document</TD
2316 ><TD
2317 WIDTH="34%"
2318 ALIGN="center"
2319 VALIGN="top"
2320 ><A
2321 HREF="c893.html"
2322 >Up</A
2323 ></TD
2324 ><TD
2325 WIDTH="33%"
2326 ALIGN="right"
2327 VALIGN="top"
2328 >The class type <TT
2329 CLASS="LITERAL"
2330 >extension</TT
2331 ></TD
2332 ></TR
2333 ></TABLE
2334 ></DIV
2335 ></BODY
2336 ></HTML
2337 >