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

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >The DTD classes</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="Configuring and calling the parser"
  13 HREF="c1567.html"><LINK
  14 REL="PREVIOUS"
  15 TITLE="Resolvers and sources"
  16 HREF="x1629.html"><LINK
  17 REL="NEXT"
  18 TITLE="Invoking the parser"
  19 HREF="x1818.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="x1629.html"
  50 >Prev</A
  51 ></TD
  52 ><TD
  53 WIDTH="80%"
  54 ALIGN="center"
  55 VALIGN="bottom"
  56 >Chapter 4. Configuring and calling the parser</TD
  57 ><TD
  58 WIDTH="10%"
  59 ALIGN="right"
  60 VALIGN="bottom"
  61 ><A
  62 HREF="x1818.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="AEN1812"
  76 >4.3. The DTD classes</A
  77 ></H1
  78 ><P
  79 ><I
  80 CLASS="EMPHASIS"
  81 >Sorry, not yet
  82 written. Perhaps the interface definition of Pxp_dtd expresses the same:</I
  83 ></P
  84 ><P
  85 ><PRE
  86 CLASS="PROGRAMLISTING"
  87 >&#13;(**********************************************************************)
  88 (*                                                                    *)
  89 (* Pxp_dtd:                                                           *)
  90 (*     Object model of document type declarations                     *)
  91 (*                                                                    *)
  92 (**********************************************************************)
  93
  94 (* ======================================================================
  95  * OVERVIEW
  96  *
  97  * class dtd ............... represents the whole DTD, including element
  98  *                           declarations, entity declarations, notation
  99  *                           declarations, and processing instructions
 100  * class dtd_element ....... represents an element declaration consisting
 101  *                           of a content model and an attribute list
 102  *                           declaration
 103  * class dtd_notation ...... represents a notation declaration
 104  * class proc_instruction .. represents a processing instruction
 105  * ======================================================================
 106  *
 107  *)
 108
 109
 110 class dtd :
 111   (* Creation:
 112    *   new dtd
 113    * creates a new, empty DTD object without any declaration, without a root
 114    * element, without an ID.
 115    *)
 116   Pxp_types.collect_warnings -&gt;
 117   Pxp_types.rep_encoding -&gt;
 118   object
 119     method root : string option
 120       (* get the name of the root element if present *)
 121
 122     method set_root : string -&gt; unit
 123       (* set the name of the root element. This method can be invoked
 124        * only once
 125        *)
 126
 127     method id : Pxp_types.dtd_id option
 128       (* get the identifier for this DTD *)
 129
 130     method set_id : Pxp_types.dtd_id -&gt; unit
 131       (* set the identifier. This method can be invoked only once *)
 132
 133     method encoding : Pxp_types.rep_encoding
 134       (* returns the encoding used for character representation *)
 135
 136
 137     method allow_arbitrary : unit
 138       (* After this method has been invoked, the object changes its behaviour:
 139        * - elements and notations that have not been added may be used in an
 140        *   arbitrary way; the methods "element" and "notation" indicate this
 141        *   by raising Undeclared instead of Validation_error.
 142        *)
 143
 144     method disallow_arbitrary : unit
 145
 146     method arbitrary_allowed : bool
 147       (* Returns whether arbitrary contents are allowed or not. *)
 148
 149     method standalone_declaration : bool
 150       (* Whether there is a 'standalone' declaration or not. Strictly
 151        * speaking, this declaration is not part of the DTD, but it is
 152        * included here because of practical reasons.
 153        * If not set, this property defaults to 'false'.
 154        *)
 155
 156     method set_standalone_declaration : bool -&gt; unit
 157       (* Sets the 'standalone' declaration. *)
 158
 159
 160     method add_element : dtd_element -&gt; unit
 161       (* add the given element declaration to this DTD. Raises Not_found
 162        * if there is already an element declaration with the same name.
 163        *)
 164
 165     method add_gen_entity : Pxp_entity.entity -&gt; bool -&gt; unit
 166       (* add_gen_entity e extdecl:
 167        * add the entity 'e' as general entity to this DTD (general entities
 168        * are those represented by &amp;name;). If there is already a declaration
 169        * with the same name, the second definition is ignored; as exception from
 170        * this rule, entities with names "lt", "gt", "amp", "quot", and "apos"
 171        * may only be redeclared with a definition that is equivalent to the
 172        * standard definition; otherwise a Validation_error is raised.
 173        *
 174        * 'extdecl': 'true' indicates that the entity declaration occurs in
 175        * an external entity. (Used for the standalone check.)
 176        *)
 177
 178     method add_par_entity : Pxp_entity.entity -&gt; unit
 179       (* add the given entity as parameter entity to this DTD (parameter
 180        * entities are those represented by %name;). If there is already a
 181        * declaration with the same name, the second definition is ignored.
 182        *)
 183
 184     method add_notation : dtd_notation -&gt; unit
 185       (* add the given notation to this DTD. If there is already a declaration
 186        * with the same name, a Validation_error is raised.
 187        *)
 188
 189     method add_pinstr : proc_instruction -&gt; unit
 190       (* add the given processing instruction to this DTD. *)
 191
 192     method element : string -&gt; dtd_element
 193       (* looks up the element declaration with the given name. Raises
 194        * Validation_error if the element cannot be found. (If "allow_arbitrary"
 195        * has been invoked before, Unrestricted is raised instead.)
 196        *)
 197
 198     method element_names : string list
 199       (* returns the list of the names of all element declarations. *)
 200
 201     method gen_entity : string -&gt; (Pxp_entity.entity * bool)
 202       (* let e, extdecl = obj # gen_entity n:
 203        * looks up the general entity 'e' with the name 'n'. Raises
 204        * WF_error if the entity cannot be found.
 205        * 'extdecl': indicates whether the entity declaration occured in an
 206        * external entity.
 207        *)
 208
 209     method gen_entity_names : string list
 210       (* returns the list of all general entity names *)
 211
 212     method par_entity : string -&gt; Pxp_entity.entity
 213       (* looks up the parameter entity with the given name. Raises
 214        * WF_error if the entity cannot be found.
 215        *)
 216
 217     method par_entity_names : string list
 218       (* returns the list of all parameter entity names *)
 219
 220     method notation : string -&gt; dtd_notation
 221       (* looks up the notation declaration with the given name. Raises
 222        * Validation_error if the notation cannot be found. (If "allow_arbitrary"
 223        * has been invoked before, Unrestricted is raised instead.)
 224        *)
 225
 226     method notation_names : string list
 227       (* Returns the list of the names of all added notations *)
 228
 229     method pinstr : string -&gt; proc_instruction list
 230       (* looks up all processing instructions with the given target.
 231        * The "target" is the identifier following "&lt;?".
 232        * Note: It is not possible to find out the exact position of the
 233        * processing instruction.
 234        *)
 235
 236     method pinstr_names : string list
 237       (* Returns the list of the names (targets) of all added pinstrs *)
 238
 239     method validate : unit
 240       (* ensures that the DTD is valid. This method is optimized such that
 241        * actual validation is only performed if DTD has changed.
 242        * If the DTD is invalid, mostly a Validation_error is raised,
 243        * but other exceptions are possible, too.
 244        *)
 245
 246     method only_deterministic_models : unit
 247       (* Succeeds if all regexp content models are deterministic.
 248        * Otherwise Validation_error.
 249        *)
 250
 251     method write : Pxp_types.output_stream -&gt; Pxp_types.encoding -&gt; bool -&gt; unit
 252       (* write_compact_as_latin1 os enc doctype:
 253        * Writes the DTD as 'enc'-encoded string to 'os'. If 'doctype', a
 254        * DTD like &lt;!DOCTYPE root [ ... ]&gt; is written. If 'not doctype',
 255        * only the declarations are written (the material within the
 256        * square brackets).
 257        *)
 258
 259     method write_compact_as_latin1 : Pxp_types.output_stream -&gt; bool -&gt; unit
 260       (* DEPRECATED METHOD; included only to keep compatibility with
 261        * older versions of the parser
 262        *)
 263
 264
 265     (*----------------------------------------*)
 266     method invalidate : unit
 267       (* INTERNAL METHOD *)
 268     method warner : Pxp_types.collect_warnings
 269       (* INTERNAL METHOD *)
 270   end
 271
 272
 273
 274 (* ---------------------------------------------------------------------- *)
 275
 276 and dtd_element : dtd -&gt; string -&gt;
 277   (* Creation:
 278    *   new dtd_element init_dtd init_name:
 279    * creates a new dtd_element object for init_dtd with init_name.
 280    * The strings are represented in the same encoding as init_dtd.
 281    *)
 282   object
 283
 284     method name : string
 285       (* returns the name of the declared element *)
 286
 287     method externally_declared : bool
 288       (* returns whether the element declaration occurs in an external
 289        * entity.
 290        *)
 291
 292     method content_model : Pxp_types.content_model_type
 293       (* get the content model of this element declaration, or Unspecified *)
 294
 295     method content_dfa : Pxp_dfa.dfa_definition option
 296       (* return the DFA of the content model if there is a DFA, or None.
 297        * A DFA exists only for regexp style content models which are
 298        * deterministic.
 299        *)
 300
 301     method set_cm_and_extdecl : Pxp_types.content_model_type -&gt; bool -&gt; unit
 302       (* set_cm_and_extdecl cm extdecl:
 303        * set the content model to 'cm'. Once the content model is not
 304        * Unspecified, it cannot be set to a different value again.
 305        * Furthermore, it is set whether the element occurs in an external
 306        * entity ('extdecl').
 307        *)
 308
 309     method encoding : Pxp_types.rep_encoding
 310       (* Return the encoding of the strings *)
 311
 312     method allow_arbitrary : unit
 313       (* After this method has been invoked, the object changes its behaviour:
 314        * - attributes that have not been added may be used in an
 315        *   arbitrary way; the method "attribute" indicates this
 316        *   by raising Undeclared instead of Validation_error.
 317        *)
 318
 319     method disallow_arbitrary : unit
 320
 321     method arbitrary_allowed : bool
 322       (* Returns whether arbitrary attributes are allowed or not. *)
 323
 324     method attribute : string -&gt;
 325                          Pxp_types.att_type * Pxp_types.att_default
 326       (* get the type and default value of a declared attribute, or raise
 327        * Validation_error if the attribute does not exist.
 328        * If 'arbitrary_allowed', the exception Undeclared is raised instead
 329        * of Validation_error.
 330        *)
 331
 332     method attribute_violates_standalone_declaration :
 333                string -&gt; string option -&gt; bool
 334       (* attribute_violates_standalone_declaration name v:
 335        * Checks whether the attribute 'name' violates the "standalone"
 336        * declaration if it has value 'v'.
 337        * The method returns true if:
 338        * - The attribute declaration occurs in an external entity,
 339        * and if one of the two conditions holds:
 340        * - v = None, and there is a default for the attribute value
 341        * - v = Some s, and the type of the attribute is not CDATA,
 342        *   and s changes if normalized according to the rules of the
 343        *   attribute type.
 344        *
 345        * The method raises Validation_error if the attribute does not exist.
 346        * If 'arbitrary_allowed', the exception Undeclared is raised instead
 347        * of Validation_error.
 348        *)
 349
 350     method attribute_names : string list
 351       (* get the list of all declared attributes *)
 352
 353     method names_of_required_attributes : string list
 354       (* get the list of all attributes that are specified as required
 355        * attributes
 356        *)
 357
 358     method id_attribute_name : string option
 359       (* Returns the name of the attribute with type ID, or None. *)
 360
 361     method idref_attribute_names : string list
 362       (* Returns the names of the attributes with type IDREF or IDREFS. *)
 363
 364     method add_attribute : string -&gt;
 365                            Pxp_types.att_type -&gt;
 366                            Pxp_types.att_default -&gt;
 367                            bool -&gt;
 368                              unit
 369       (* add_attribute name type default extdecl:
 370        * add an attribute declaration for an attribute with the given name,
 371        * type, and default value. If there is more than one declaration for
 372        * an attribute name, the first declaration counts; the other declarations
 373        * are ignored.
 374        * 'extdecl': if true, the attribute declaration occurs in an external
 375        * entity. This property is used to check the "standalone" attribute.
 376        *)
 377
 378     method validate : unit
 379       (* checks whether this element declaration (i.e. the content model and
 380        * all attribute declarations) is valid for the associated DTD.
 381        * Raises mostly Validation_error if the validation fails.
 382        *)
 383
 384     method write : Pxp_types.output_stream -&gt; Pxp_types.encoding -&gt; unit
 385       (* write_compact_as_latin1 os enc:
 386        * Writes the &lt;!ELEMENT ... &gt; declaration to 'os' as 'enc'-encoded string.
 387        *)
 388
 389     method write_compact_as_latin1 : Pxp_types.output_stream -&gt; unit
 390       (* DEPRECATED METHOD; included only to keep compatibility with
 391        * older versions of the parser
 392        *)
 393   end
 394
 395 (* ---------------------------------------------------------------------- *)
 396
 397 and dtd_notation : string -&gt; Pxp_types.ext_id -&gt; Pxp_types.rep_encoding -&gt;
 398   (* Creation:
 399    *    new dtd_notation a_name an_external_ID init_encoding
 400    * creates a new dtd_notation object with the given name and the given
 401    * external ID.
 402    *)
 403   object
 404     method name : string
 405     method ext_id : Pxp_types.ext_id
 406     method encoding : Pxp_types.rep_encoding
 407
 408     method write : Pxp_types.output_stream -&gt; Pxp_types.encoding -&gt; unit
 409       (* write_compact_as_latin1 os enc:
 410        * Writes the &lt;!NOTATION ... &gt; declaration to 'os' as 'enc'-encoded
 411        * string.
 412        *)
 413
 414     method write_compact_as_latin1 : Pxp_types.output_stream -&gt; unit
 415       (* DEPRECATED METHOD; included only to keep compatibility with
 416        * older versions of the parser
 417        *)
 418
 419   end
 420
 421 (* ---------------------------------------------------------------------- *)
 422
 423 and proc_instruction : string -&gt; string -&gt; Pxp_types.rep_encoding -&gt;
 424   (* Creation:
 425    *   new proc_instruction a_target a_value
 426    * creates a new proc_instruction object with the given target string and
 427    * the given value string.
 428    * Note: A processing instruction is written as &lt;?target value?&gt;.
 429    *)
 430   object
 431     method target : string
 432     method value : string
 433     method encoding : Pxp_types.rep_encoding
 434
 435     method write : Pxp_types.output_stream -&gt; Pxp_types.encoding -&gt; unit
 436       (* write os enc:
 437        * Writes the &lt;?...?&gt; PI to 'os' as 'enc'-encoded string.
 438        *)
 439
 440     method write_compact_as_latin1 : Pxp_types.output_stream -&gt; unit
 441       (* DEPRECATED METHOD; included only to keep compatibility with
 442        * older versions of the parser
 443        *)
 444
 445     method parse_pxp_option : (string * string * (string * string) list)
 446       (* Parses a PI containing a PXP option. Such PIs are formed like:
 447        *   &lt;?target option-name option-att="value" option-att="value" ... ?&gt;
 448        * The method returns a triple
 449        *   (target, option-name, [option-att, value; ...])
 450        * or raises Error.
 451        *)
 452
 453   end
 454
 455 ;;&#13;</PRE
 456 ></P
 457 ></DIV
 458 ><DIV
 459 CLASS="NAVFOOTER"
 460 ><HR
 461 ALIGN="LEFT"
 462 WIDTH="100%"><TABLE
 463 WIDTH="100%"
 464 BORDER="0"
 465 CELLPADDING="0"
 466 CELLSPACING="0"
 467 ><TR
 468 ><TD
 469 WIDTH="33%"
 470 ALIGN="left"
 471 VALIGN="top"
 472 ><A
 473 HREF="x1629.html"
 474 >Prev</A
 475 ></TD
 476 ><TD
 477 WIDTH="34%"
 478 ALIGN="center"
 479 VALIGN="top"
 480 ><A
 481 HREF="index.html"
 482 >Home</A
 483 ></TD
 484 ><TD
 485 WIDTH="33%"
 486 ALIGN="right"
 487 VALIGN="top"
 488 ><A
 489 HREF="x1818.html"
 490 >Next</A
 491 ></TD
 492 ></TR
 493 ><TR
 494 ><TD
 495 WIDTH="33%"
 496 ALIGN="left"
 497 VALIGN="top"
 498 >Resolvers and sources</TD
 499 ><TD
 500 WIDTH="34%"
 501 ALIGN="center"
 502 VALIGN="top"
 503 ><A
 504 HREF="c1567.html"
 505 >Up</A
 506 ></TD
 507 ><TD
 508 WIDTH="33%"
 509 ALIGN="right"
 510 VALIGN="top"
 511 >Invoking the parser</TD
 512 ></TR
 513 ></TABLE
 514 ></DIV
 515 ></BODY
 516 ></HTML
 517 >