4 >The DTD classes</TITLE
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.46"><LINK
9 TITLE="The PXP user's guide"
10 HREF="index.html"><LINK
12 TITLE="Configuring and calling the parser"
13 HREF="c1567.html"><LINK
15 TITLE="Resolvers and sources"
16 HREF="x1629.html"><LINK
18 TITLE="Invoking the parser"
19 HREF="x1818.html"><LINK
22 HREF="markup.css"></HEAD
41 >The PXP user's guide</TH
56 >Chapter 4. Configuring and calling the parser</TD
76 >4.3. The DTD classes</A
82 written. Perhaps the interface definition of Pxp_dtd expresses the same:</I
86 CLASS="PROGRAMLISTING"
87 > (**********************************************************************)
90 (* Object model of document type declarations *)
92 (**********************************************************************)
94 (* ======================================================================
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
103 * class dtd_notation ...... represents a notation declaration
104 * class proc_instruction .. represents a processing instruction
105 * ======================================================================
113 * creates a new, empty DTD object without any declaration, without a root
114 * element, without an ID.
116 Pxp_types.collect_warnings ->
117 Pxp_types.rep_encoding ->
119 method root : string option
120 (* get the name of the root element if present *)
122 method set_root : string -> unit
123 (* set the name of the root element. This method can be invoked
127 method id : Pxp_types.dtd_id option
128 (* get the identifier for this DTD *)
130 method set_id : Pxp_types.dtd_id -> unit
131 (* set the identifier. This method can be invoked only once *)
133 method encoding : Pxp_types.rep_encoding
134 (* returns the encoding used for character representation *)
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.
144 method disallow_arbitrary : unit
146 method arbitrary_allowed : bool
147 (* Returns whether arbitrary contents are allowed or not. *)
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'.
156 method set_standalone_declaration : bool -> unit
157 (* Sets the 'standalone' declaration. *)
160 method add_element : dtd_element -> 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.
165 method add_gen_entity : Pxp_entity.entity -> bool -> 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 &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.
174 * 'extdecl': 'true' indicates that the entity declaration occurs in
175 * an external entity. (Used for the standalone check.)
178 method add_par_entity : Pxp_entity.entity -> 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.
184 method add_notation : dtd_notation -> 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.
189 method add_pinstr : proc_instruction -> unit
190 (* add the given processing instruction to this DTD. *)
192 method element : string -> 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.)
198 method element_names : string list
199 (* returns the list of the names of all element declarations. *)
201 method gen_entity : string -> (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
209 method gen_entity_names : string list
210 (* returns the list of all general entity names *)
212 method par_entity : string -> Pxp_entity.entity
213 (* looks up the parameter entity with the given name. Raises
214 * WF_error if the entity cannot be found.
217 method par_entity_names : string list
218 (* returns the list of all parameter entity names *)
220 method notation : string -> 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.)
226 method notation_names : string list
227 (* Returns the list of the names of all added notations *)
229 method pinstr : string -> proc_instruction list
230 (* looks up all processing instructions with the given target.
231 * The "target" is the identifier following "<?".
232 * Note: It is not possible to find out the exact position of the
233 * processing instruction.
236 method pinstr_names : string list
237 (* Returns the list of the names (targets) of all added pinstrs *)
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.
246 method only_deterministic_models : unit
247 (* Succeeds if all regexp content models are deterministic.
248 * Otherwise Validation_error.
251 method write : Pxp_types.output_stream -> Pxp_types.encoding -> bool -> 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 <!DOCTYPE root [ ... ]> is written. If 'not doctype',
255 * only the declarations are written (the material within the
259 method write_compact_as_latin1 : Pxp_types.output_stream -> bool -> unit
260 (* DEPRECATED METHOD; included only to keep compatibility with
261 * older versions of the parser
265 (*----------------------------------------*)
266 method invalidate : unit
267 (* INTERNAL METHOD *)
268 method warner : Pxp_types.collect_warnings
269 (* INTERNAL METHOD *)
274 (* ---------------------------------------------------------------------- *)
276 and dtd_element : dtd -> string ->
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.
285 (* returns the name of the declared element *)
287 method externally_declared : bool
288 (* returns whether the element declaration occurs in an external
292 method content_model : Pxp_types.content_model_type
293 (* get the content model of this element declaration, or Unspecified *)
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
301 method set_cm_and_extdecl : Pxp_types.content_model_type -> bool -> 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').
309 method encoding : Pxp_types.rep_encoding
310 (* Return the encoding of the strings *)
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.
319 method disallow_arbitrary : unit
321 method arbitrary_allowed : bool
322 (* Returns whether arbitrary attributes are allowed or not. *)
324 method attribute : string ->
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.
332 method attribute_violates_standalone_declaration :
333 string -> string option -> 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
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.
350 method attribute_names : string list
351 (* get the list of all declared attributes *)
353 method names_of_required_attributes : string list
354 (* get the list of all attributes that are specified as required
358 method id_attribute_name : string option
359 (* Returns the name of the attribute with type ID, or None. *)
361 method idref_attribute_names : string list
362 (* Returns the names of the attributes with type IDREF or IDREFS. *)
364 method add_attribute : string ->
365 Pxp_types.att_type ->
366 Pxp_types.att_default ->
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
374 * 'extdecl': if true, the attribute declaration occurs in an external
375 * entity. This property is used to check the "standalone" attribute.
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.
384 method write : Pxp_types.output_stream -> Pxp_types.encoding -> unit
385 (* write_compact_as_latin1 os enc:
386 * Writes the <!ELEMENT ... > declaration to 'os' as 'enc'-encoded string.
389 method write_compact_as_latin1 : Pxp_types.output_stream -> unit
390 (* DEPRECATED METHOD; included only to keep compatibility with
391 * older versions of the parser
395 (* ---------------------------------------------------------------------- *)
397 and dtd_notation : string -> Pxp_types.ext_id -> Pxp_types.rep_encoding ->
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
405 method ext_id : Pxp_types.ext_id
406 method encoding : Pxp_types.rep_encoding
408 method write : Pxp_types.output_stream -> Pxp_types.encoding -> unit
409 (* write_compact_as_latin1 os enc:
410 * Writes the <!NOTATION ... > declaration to 'os' as 'enc'-encoded
414 method write_compact_as_latin1 : Pxp_types.output_stream -> unit
415 (* DEPRECATED METHOD; included only to keep compatibility with
416 * older versions of the parser
421 (* ---------------------------------------------------------------------- *)
423 and proc_instruction : string -> string -> Pxp_types.rep_encoding ->
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 <?target value?>.
431 method target : string
432 method value : string
433 method encoding : Pxp_types.rep_encoding
435 method write : Pxp_types.output_stream -> Pxp_types.encoding -> unit
437 * Writes the <?...?> PI to 'os' as 'enc'-encoded string.
440 method write_compact_as_latin1 : Pxp_types.output_stream -> unit
441 (* DEPRECATED METHOD; included only to keep compatibility with
442 * older versions of the parser
445 method parse_pxp_option : (string * string * (string * string) list)
446 (* Parses a PI containing a PXP option. Such PIs are formed like:
447 * <?target option-name option-att="value" option-att="value" ... ?>
448 * The method returns a triple
449 * (target, option-name, [option-att, value; ...])
498 >Resolvers and sources</TD
511 >Invoking the parser</TD