1 <!ENTITY markup-dtd1.mli '
3 (**********************************************************************)
6 (* Object model of document type declarations *)
8 (**********************************************************************)
10 (* ======================================================================
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
19 * class dtd_notation ...... represents a notation declaration
20 * class proc_instruction .. represents a processing instruction
21 * ======================================================================
29 * creates a new, empty DTD object without any declaration, without a root
30 * element, without an ID.
32 Pxp_types.collect_warnings ->
33 Pxp_types.rep_encoding ->
35 method root : string option
36 (* get the name of the root element if present *)
38 method set_root : string -> unit
39 (* set the name of the root element. This method can be invoked
43 method id : Pxp_types.dtd_id option
44 (* get the identifier for this DTD *)
46 method set_id : Pxp_types.dtd_id -> unit
47 (* set the identifier. This method can be invoked only once *)
49 method encoding : Pxp_types.rep_encoding
50 (* returns the encoding used for character representation *)
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.
60 method disallow_arbitrary : unit
62 method arbitrary_allowed : bool
63 (* Returns whether arbitrary contents are allowed or not. *)
65 method standalone_declaration : bool
66 (* Whether there is a 'standalone' 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 'false'.
72 method set_standalone_declaration : bool -> unit
73 (* Sets the 'standalone' declaration. *)
76 method add_element : dtd_element -> 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.
81 method add_gen_entity : Pxp_entity.entity -> bool -> unit
82 (* add_gen_entity e extdecl:
83 * add the entity 'e' as general entity to this DTD (general entities
84 * are those represented by &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.
90 * 'extdecl': 'true' indicates that the entity declaration occurs in
91 * an external entity. (Used for the standalone check.)
94 method add_par_entity : Pxp_entity.entity -> 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.
100 method add_notation : dtd_notation -> 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.
105 method add_pinstr : proc_instruction -> unit
106 (* add the given processing instruction to this DTD. *)
108 method element : string -> 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.)
114 method element_names : string list
115 (* returns the list of the names of all element declarations. *)
117 method gen_entity : string -> (Pxp_entity.entity * bool)
118 (* let e, extdecl = obj # gen_entity n:
119 * looks up the general entity 'e' with the name 'n'. Raises
120 * WF_error if the entity cannot be found.
121 * 'extdecl': indicates whether the entity declaration occured in an
125 method gen_entity_names : string list
126 (* returns the list of all general entity names *)
128 method par_entity : string -> Pxp_entity.entity
129 (* looks up the parameter entity with the given name. Raises
130 * WF_error if the entity cannot be found.
133 method par_entity_names : string list
134 (* returns the list of all parameter entity names *)
136 method notation : string -> 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.)
142 method notation_names : string list
143 (* Returns the list of the names of all added notations *)
145 method pinstr : string -> proc_instruction list
146 (* looks up all processing instructions with the given target.
147 * The "target" is the identifier following "<?".
148 * Note: It is not possible to find out the exact position of the
149 * processing instruction.
152 method pinstr_names : string list
153 (* Returns the list of the names (targets) of all added pinstrs *)
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.
162 method only_deterministic_models : unit
163 (* Succeeds if all regexp content models are deterministic.
164 * Otherwise Validation_error.
167 method write : Pxp_types.output_stream -> Pxp_types.encoding -> bool -> unit
168 (* write_compact_as_latin1 os enc doctype:
169 * Writes the DTD as 'enc'-encoded string to 'os'. If 'doctype', a
170 * DTD like <!DOCTYPE root [ ... ]> is written. If 'not doctype',
171 * only the declarations are written (the material within the
175 method write_compact_as_latin1 : Pxp_types.output_stream -> bool -> unit
176 (* DEPRECATED METHOD; included only to keep compatibility with
177 * older versions of the parser
181 (*----------------------------------------*)
182 method invalidate : unit
183 (* INTERNAL METHOD *)
184 method warner : Pxp_types.collect_warnings
185 (* INTERNAL METHOD *)
189 <!ENTITY markup-dtd2.mli '
191 (* ---------------------------------------------------------------------- *)
193 and dtd_element : dtd -> string ->
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.
202 (* returns the name of the declared element *)
204 method externally_declared : bool
205 (* returns whether the element declaration occurs in an external
209 method content_model : Pxp_types.content_model_type
210 (* get the content model of this element declaration, or Unspecified *)
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
218 method set_cm_and_extdecl : Pxp_types.content_model_type -> bool -> unit
219 (* set_cm_and_extdecl cm extdecl:
220 * set the content model to 'cm'. 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 ('extdecl').
226 method encoding : Pxp_types.rep_encoding
227 (* Return the encoding of the strings *)
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.
236 method disallow_arbitrary : unit
238 method arbitrary_allowed : bool
239 (* Returns whether arbitrary attributes are allowed or not. *)
241 method attribute : string ->
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 'arbitrary_allowed', the exception Undeclared is raised instead
246 * of Validation_error.
249 method attribute_violates_standalone_declaration :
250 string -> string option -> bool
251 (* attribute_violates_standalone_declaration name v:
252 * Checks whether the attribute 'name' violates the "standalone"
253 * declaration if it has value 'v'.
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
262 * The method raises Validation_error if the attribute does not exist.
263 * If 'arbitrary_allowed', the exception Undeclared is raised instead
264 * of Validation_error.
267 method attribute_names : string list
268 (* get the list of all declared attributes *)
270 method names_of_required_attributes : string list
271 (* get the list of all attributes that are specified as required
275 method id_attribute_name : string option
276 (* Returns the name of the attribute with type ID, or None. *)
278 method idref_attribute_names : string list
279 (* Returns the names of the attributes with type IDREF or IDREFS. *)
281 method add_attribute : string ->
282 Pxp_types.att_type ->
283 Pxp_types.att_default ->
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
291 * 'extdecl': if true, the attribute declaration occurs in an external
292 * entity. This property is used to check the "standalone" attribute.
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.
301 method write : Pxp_types.output_stream -> Pxp_types.encoding -> unit
302 (* write_compact_as_latin1 os enc:
303 * Writes the <!ELEMENT ... > declaration to 'os' as 'enc'-encoded string.
306 method write_compact_as_latin1 : Pxp_types.output_stream -> unit
307 (* DEPRECATED METHOD; included only to keep compatibility with
308 * older versions of the parser
312 (* ---------------------------------------------------------------------- *)
314 and dtd_notation : string -> Pxp_types.ext_id -> Pxp_types.rep_encoding ->
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
322 method ext_id : Pxp_types.ext_id
323 method encoding : Pxp_types.rep_encoding
325 method write : Pxp_types.output_stream -> Pxp_types.encoding -> unit
326 (* write_compact_as_latin1 os enc:
327 * Writes the <!NOTATION ... > declaration to 'os' as 'enc'-encoded
331 method write_compact_as_latin1 : Pxp_types.output_stream -> unit
332 (* DEPRECATED METHOD; included only to keep compatibility with
333 * older versions of the parser
338 (* ---------------------------------------------------------------------- *)
340 and proc_instruction : string -> string -> Pxp_types.rep_encoding ->
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 <?target value?>.
348 method target : string
349 method value : string
350 method encoding : Pxp_types.rep_encoding
352 method write : Pxp_types.output_stream -> Pxp_types.encoding -> unit
354 * Writes the <?...?> PI to 'os' as 'enc'-encoded string.
357 method write_compact_as_latin1 : Pxp_types.output_stream -> unit
358 (* DEPRECATED METHOD; included only to keep compatibility with
359 * older versions of the parser
362 method parse_pxp_option : (string * string * (string * string) list)
363 (* Parses a PI containing a PXP option. Such PIs are formed like:
364 * <?target option-name option-att="value" option-att="value" ... ?>
365 * The method returns a triple
366 * (target, option-name, [option-att, value; ...])