helm/DEVEL/pxp/pxp/doc/manual/src/dtd.mli.ent

   1 <!ENTITY markup-dtd1.mli '
   2
   3 (**********************************************************************)
   4 (*                                                                    *)
   5 (* Pxp_dtd:                                                           *)
   6 (*     Object model of document type declarations                     *)
   7 (*                                                                    *)
   8 (**********************************************************************)
   9
  10 (* ======================================================================
  11  * OVERVIEW
  12  *
  13  * class dtd ............... represents the whole DTD, including element
  14  *                           declarations, entity declarations, notation
  15  *                           declarations, and processing instructions
  16  * class dtd_element ....... represents an element declaration consisting
  17  *                           of a content model and an attribute list
  18  *                           declaration
  19  * class dtd_notation ...... represents a notation declaration
  20  * class proc_instruction .. represents a processing instruction
  21  * ======================================================================
  22  *
  23  *)
  24
  25
  26 class dtd :
  27   (* Creation:
  28    *   new dtd
  29    * creates a new, empty DTD object without any declaration, without a root
  30    * element, without an ID.
  31    *)
  32   Pxp_types.collect_warnings -&gt;
  33   Pxp_types.rep_encoding -&gt;
  34   object
  35     method root : string option
  36       (* get the name of the root element if present *)
  37
  38     method set_root : string -&gt; unit
  39       (* set the name of the root element. This method can be invoked
  40        * only once
  41        *)
  42
  43     method id : Pxp_types.dtd_id option
  44       (* get the identifier for this DTD *)
  45
  46     method set_id : Pxp_types.dtd_id -&gt; unit
  47       (* set the identifier. This method can be invoked only once *)
  48
  49     method encoding : Pxp_types.rep_encoding
  50       (* returns the encoding used for character representation *)
  51
  52
  53     method allow_arbitrary : unit
  54       (* After this method has been invoked, the object changes its behaviour:
  55        * - elements and notations that have not been added may be used in an
  56        *   arbitrary way; the methods "element" and "notation" indicate this
  57        *   by raising Undeclared instead of Validation_error.
  58        *)
  59
  60     method disallow_arbitrary : unit
  61
  62     method arbitrary_allowed : bool
  63       (* Returns whether arbitrary contents are allowed or not. *)
  64
  65     method standalone_declaration : bool
  66       (* Whether there is a &apos;standalone&apos; declaration or not. Strictly
  67        * speaking, this declaration is not part of the DTD, but it is
  68        * included here because of practical reasons.
  69        * If not set, this property defaults to &apos;false&apos;.
  70        *)
  71
  72     method set_standalone_declaration : bool -&gt; unit
  73       (* Sets the &apos;standalone&apos; declaration. *)
  74
  75
  76     method add_element : dtd_element -&gt; unit
  77       (* add the given element declaration to this DTD. Raises Not_found
  78        * if there is already an element declaration with the same name.
  79        *)
  80
  81     method add_gen_entity : Pxp_entity.entity -&gt; bool -&gt; unit
  82       (* add_gen_entity e extdecl:
  83        * add the entity &apos;e&apos; as general entity to this DTD (general entities
  84        * are those represented by &amp;name;). If there is already a declaration
  85        * with the same name, the second definition is ignored; as exception from
  86        * this rule, entities with names "lt", "gt", "amp", "quot", and "apos"
  87        * may only be redeclared with a definition that is equivalent to the
  88        * standard definition; otherwise a Validation_error is raised.
  89        *
  90        * &apos;extdecl&apos;: &apos;true&apos; indicates that the entity declaration occurs in
  91        * an external entity. (Used for the standalone check.)
  92        *)
  93
  94     method add_par_entity : Pxp_entity.entity -&gt; unit
  95       (* add the given entity as parameter entity to this DTD (parameter
  96        * entities are those represented by &percent;name;). If there is already a
  97        * declaration with the same name, the second definition is ignored.
  98        *)
  99
 100     method add_notation : dtd_notation -&gt; unit
 101       (* add the given notation to this DTD. If there is already a declaration
 102        * with the same name, a Validation_error is raised.
 103        *)
 104
 105     method add_pinstr : proc_instruction -&gt; unit
 106       (* add the given processing instruction to this DTD. *)
 107
 108     method element : string -&gt; dtd_element
 109       (* looks up the element declaration with the given name. Raises
 110        * Validation_error if the element cannot be found. (If "allow_arbitrary"
 111        * has been invoked before, Unrestricted is raised instead.)
 112        *)
 113
 114     method element_names : string list
 115       (* returns the list of the names of all element declarations. *)
 116
 117     method gen_entity : string -&gt; (Pxp_entity.entity * bool)
 118       (* let e, extdecl = obj # gen_entity n:
 119        * looks up the general entity &apos;e&apos; with the name &apos;n&apos;. Raises
 120        * WF_error if the entity cannot be found.
 121        * &apos;extdecl&apos;: indicates whether the entity declaration occured in an
 122        * external entity.
 123        *)
 124
 125     method gen_entity_names : string list
 126       (* returns the list of all general entity names *)
 127
 128     method par_entity : string -&gt; Pxp_entity.entity
 129       (* looks up the parameter entity with the given name. Raises
 130        * WF_error if the entity cannot be found.
 131        *)
 132
 133     method par_entity_names : string list
 134       (* returns the list of all parameter entity names *)
 135
 136     method notation : string -&gt; dtd_notation
 137       (* looks up the notation declaration with the given name. Raises
 138        * Validation_error if the notation cannot be found. (If "allow_arbitrary"
 139        * has been invoked before, Unrestricted is raised instead.)
 140        *)
 141
 142     method notation_names : string list
 143       (* Returns the list of the names of all added notations *)
 144
 145     method pinstr : string -&gt; proc_instruction list
 146       (* looks up all processing instructions with the given target.
 147        * The "target" is the identifier following "&lt;?".
 148        * Note: It is not possible to find out the exact position of the
 149        * processing instruction.
 150        *)
 151
 152     method pinstr_names : string list
 153       (* Returns the list of the names (targets) of all added pinstrs *)
 154
 155     method validate : unit
 156       (* ensures that the DTD is valid. This method is optimized such that
 157        * actual validation is only performed if DTD has changed.
 158        * If the DTD is invalid, mostly a Validation_error is raised,
 159        * but other exceptions are possible, too.
 160        *)
 161
 162     method only_deterministic_models : unit
 163       (* Succeeds if all regexp content models are deterministic.
 164        * Otherwise Validation_error.
 165        *)
 166
 167     method write : Pxp_types.output_stream -&gt; Pxp_types.encoding -&gt; bool -&gt; unit
 168       (* write_compact_as_latin1 os enc doctype:
 169        * Writes the DTD as &apos;enc&apos;-encoded string to &apos;os&apos;. If &apos;doctype&apos;, a
 170        * DTD like &lt;!DOCTYPE root [ ... ]&gt; is written. If &apos;not doctype&apos;,
 171        * only the declarations are written (the material within the
 172        * square brackets).
 173        *)
 174
 175     method write_compact_as_latin1 : Pxp_types.output_stream -&gt; bool -&gt; unit
 176       (* DEPRECATED METHOD; included only to keep compatibility with
 177        * older versions of the parser
 178        *)
 179
 180
 181     (*----------------------------------------*)
 182     method invalidate : unit
 183       (* INTERNAL METHOD *)
 184     method warner : Pxp_types.collect_warnings
 185       (* INTERNAL METHOD *)
 186   end
 187
 188 '>
 189 <!ENTITY markup-dtd2.mli '
 190
 191 (* ---------------------------------------------------------------------- *)
 192
 193 and dtd_element : dtd -&gt; string -&gt;
 194   (* Creation:
 195    *   new dtd_element init_dtd init_name:
 196    * creates a new dtd_element object for init_dtd with init_name.
 197    * The strings are represented in the same encoding as init_dtd.
 198    *)
 199   object
 200
 201     method name : string
 202       (* returns the name of the declared element *)
 203
 204     method externally_declared : bool
 205       (* returns whether the element declaration occurs in an external
 206        * entity.
 207        *)
 208
 209     method content_model : Pxp_types.content_model_type
 210       (* get the content model of this element declaration, or Unspecified *)
 211
 212     method content_dfa : Pxp_dfa.dfa_definition option
 213       (* return the DFA of the content model if there is a DFA, or None.
 214        * A DFA exists only for regexp style content models which are
 215        * deterministic.
 216        *)
 217
 218     method set_cm_and_extdecl : Pxp_types.content_model_type -&gt; bool -&gt; unit
 219       (* set_cm_and_extdecl cm extdecl:
 220        * set the content model to &apos;cm&apos;. Once the content model is not
 221        * Unspecified, it cannot be set to a different value again.
 222        * Furthermore, it is set whether the element occurs in an external
 223        * entity (&apos;extdecl&apos;).
 224        *)
 225
 226     method encoding : Pxp_types.rep_encoding
 227       (* Return the encoding of the strings *)
 228
 229     method allow_arbitrary : unit
 230       (* After this method has been invoked, the object changes its behaviour:
 231        * - attributes that have not been added may be used in an
 232        *   arbitrary way; the method "attribute" indicates this
 233        *   by raising Undeclared instead of Validation_error.
 234        *)
 235
 236     method disallow_arbitrary : unit
 237
 238     method arbitrary_allowed : bool
 239       (* Returns whether arbitrary attributes are allowed or not. *)
 240
 241     method attribute : string -&gt;
 242                          Pxp_types.att_type * Pxp_types.att_default
 243       (* get the type and default value of a declared attribute, or raise
 244        * Validation_error if the attribute does not exist.
 245        * If &apos;arbitrary_allowed&apos;, the exception Undeclared is raised instead
 246        * of Validation_error.
 247        *)
 248
 249     method attribute_violates_standalone_declaration :
 250                string -&gt; string option -&gt; bool
 251       (* attribute_violates_standalone_declaration name v:
 252        * Checks whether the attribute &apos;name&apos; violates the "standalone"
 253        * declaration if it has value &apos;v&apos;.
 254        * The method returns true if:
 255        * - The attribute declaration occurs in an external entity,
 256        * and if one of the two conditions holds:
 257        * - v = None, and there is a default for the attribute value
 258        * - v = Some s, and the type of the attribute is not CDATA,
 259        *   and s changes if normalized according to the rules of the
 260        *   attribute type.
 261        *
 262        * The method raises Validation_error if the attribute does not exist.
 263        * If &apos;arbitrary_allowed&apos;, the exception Undeclared is raised instead
 264        * of Validation_error.
 265        *)
 266
 267     method attribute_names : string list
 268       (* get the list of all declared attributes *)
 269
 270     method names_of_required_attributes : string list
 271       (* get the list of all attributes that are specified as required
 272        * attributes
 273        *)
 274
 275     method id_attribute_name : string option
 276       (* Returns the name of the attribute with type ID, or None. *)
 277
 278     method idref_attribute_names : string list
 279       (* Returns the names of the attributes with type IDREF or IDREFS. *)
 280
 281     method add_attribute : string -&gt;
 282                            Pxp_types.att_type -&gt;
 283                            Pxp_types.att_default -&gt;
 284                            bool -&gt;
 285                              unit
 286       (* add_attribute name type default extdecl:
 287        * add an attribute declaration for an attribute with the given name,
 288        * type, and default value. If there is more than one declaration for
 289        * an attribute name, the first declaration counts; the other declarations
 290        * are ignored.
 291        * &apos;extdecl&apos;: if true, the attribute declaration occurs in an external
 292        * entity. This property is used to check the "standalone" attribute.
 293        *)
 294
 295     method validate : unit
 296       (* checks whether this element declaration (i.e. the content model and
 297        * all attribute declarations) is valid for the associated DTD.
 298        * Raises mostly Validation_error if the validation fails.
 299        *)
 300
 301     method write : Pxp_types.output_stream -&gt; Pxp_types.encoding -&gt; unit
 302       (* write_compact_as_latin1 os enc:
 303        * Writes the &lt;!ELEMENT ... &gt; declaration to &apos;os&apos; as &apos;enc&apos;-encoded string.
 304        *)
 305
 306     method write_compact_as_latin1 : Pxp_types.output_stream -&gt; unit
 307       (* DEPRECATED METHOD; included only to keep compatibility with
 308        * older versions of the parser
 309        *)
 310   end
 311
 312 (* ---------------------------------------------------------------------- *)
 313
 314 and dtd_notation : string -&gt; Pxp_types.ext_id -&gt; Pxp_types.rep_encoding -&gt;
 315   (* Creation:
 316    *    new dtd_notation a_name an_external_ID init_encoding
 317    * creates a new dtd_notation object with the given name and the given
 318    * external ID.
 319    *)
 320   object
 321     method name : string
 322     method ext_id : Pxp_types.ext_id
 323     method encoding : Pxp_types.rep_encoding
 324
 325     method write : Pxp_types.output_stream -&gt; Pxp_types.encoding -&gt; unit
 326       (* write_compact_as_latin1 os enc:
 327        * Writes the &lt;!NOTATION ... &gt; declaration to &apos;os&apos; as &apos;enc&apos;-encoded
 328        * string.
 329        *)
 330
 331     method write_compact_as_latin1 : Pxp_types.output_stream -&gt; unit
 332       (* DEPRECATED METHOD; included only to keep compatibility with
 333        * older versions of the parser
 334        *)
 335
 336   end
 337
 338 (* ---------------------------------------------------------------------- *)
 339
 340 and proc_instruction : string -&gt; string -&gt; Pxp_types.rep_encoding -&gt;
 341   (* Creation:
 342    *   new proc_instruction a_target a_value
 343    * creates a new proc_instruction object with the given target string and
 344    * the given value string.
 345    * Note: A processing instruction is written as &lt;?target value?&gt;.
 346    *)
 347   object
 348     method target : string
 349     method value : string
 350     method encoding : Pxp_types.rep_encoding
 351
 352     method write : Pxp_types.output_stream -&gt; Pxp_types.encoding -&gt; unit
 353       (* write os enc:
 354        * Writes the &lt;?...?&gt; PI to &apos;os&apos; as &apos;enc&apos;-encoded string.
 355        *)
 356
 357     method write_compact_as_latin1 : Pxp_types.output_stream -&gt; unit
 358       (* DEPRECATED METHOD; included only to keep compatibility with
 359        * older versions of the parser
 360        *)
 361
 362     method parse_pxp_option : (string * string * (string * string) list)
 363       (* Parses a PI containing a PXP option. Such PIs are formed like:
 364        *   &lt;?target option-name option-att="value" option-att="value" ... ?&gt;
 365        * The method returns a triple
 366        *   (target, option-name, [option-att, value; ...])
 367        * or raises Error.
 368        *)
 369
 370   end
 371
 372 ;;
 373
 374 '>