]> matita.cs.unibo.it Git - helm.git/blob - helm/DEVEL/pxp/pxp/pxp_dtd.mli
exported hbugsClient class so that it can be used from outside
[helm.git] / helm / DEVEL / pxp / pxp / pxp_dtd.mli
1 (* $Id$
2  * ----------------------------------------------------------------------
3  * PXP: The polymorphic XML parser for Objective Caml.
4  * Copyright by Gerd Stolpmann. See LICENSE for details.
5  *)
6
7 (*$ markup-dtd1.mli *)
8
9 (**********************************************************************)
10 (*                                                                    *)
11 (* Pxp_dtd:                                                           *)
12 (*     Object model of document type declarations                     *)
13 (*                                                                    *)
14 (**********************************************************************)
15
16 (* ======================================================================
17  * OVERVIEW
18  *
19  * class dtd ............... represents the whole DTD, including element
20  *                           declarations, entity declarations, notation
21  *                           declarations, and processing instructions
22  * class dtd_element ....... represents an element declaration consisting
23  *                           of a content model and an attribute list
24  *                           declaration
25  * class dtd_notation ...... represents a notation declaration
26  * class proc_instruction .. represents a processing instruction
27  * ======================================================================
28  *
29  *)
30
31
32 class dtd :
33   (* Creation:
34    *   new dtd
35    * creates a new, empty DTD object without any declaration, without a root
36    * element, without an ID.
37    *)
38   Pxp_types.collect_warnings -> 
39   Pxp_types.rep_encoding ->
40   object
41     method root : string option
42       (* get the name of the root element if present *)
43
44     method set_root : string -> unit
45       (* set the name of the root element. This method can be invoked 
46        * only once
47        *)
48
49     method id : Pxp_types.dtd_id option
50       (* get the identifier for this DTD *)
51
52     method set_id : Pxp_types.dtd_id -> unit
53       (* set the identifier. This method can be invoked only once *)
54
55     method encoding : Pxp_types.rep_encoding
56       (* returns the encoding used for character representation *)
57
58
59     method allow_arbitrary : unit
60       (* After this method has been invoked, the object changes its behaviour:
61        * - elements and notations that have not been added may be used in an
62        *   arbitrary way; the methods "element" and "notation" indicate this
63        *   by raising Undeclared instead of Validation_error.
64        *)
65
66     method disallow_arbitrary : unit
67
68     method arbitrary_allowed : bool
69       (* Returns whether arbitrary contents are allowed or not. *)
70
71     method standalone_declaration : bool
72       (* Whether there is a 'standalone' declaration or not. Strictly 
73        * speaking, this declaration is not part of the DTD, but it is
74        * included here because of practical reasons. 
75        * If not set, this property defaults to 'false'.
76        *)
77
78     method set_standalone_declaration : bool -> unit
79       (* Sets the 'standalone' declaration. *)
80
81
82     method add_element : dtd_element -> unit
83       (* add the given element declaration to this DTD. Raises Not_found
84        * if there is already an element declaration with the same name.
85        *)
86
87     method add_gen_entity : Pxp_entity.entity -> bool -> unit
88       (* add_gen_entity e extdecl:
89        * add the entity 'e' as general entity to this DTD (general entities
90        * are those represented by &name;). If there is already a declaration
91        * with the same name, the second definition is ignored; as exception from
92        * this rule, entities with names "lt", "gt", "amp", "quot", and "apos"
93        * may only be redeclared with a definition that is equivalent to the
94        * standard definition; otherwise a Validation_error is raised.
95        *
96        * 'extdecl': 'true' indicates that the entity declaration occurs in
97        * an external entity. (Used for the standalone check.)
98        *)
99
100     method add_par_entity : Pxp_entity.entity -> unit
101       (* add the given entity as parameter entity to this DTD (parameter
102        * entities are those represented by %name;). If there is already a 
103        * declaration with the same name, the second definition is ignored.
104        *)
105
106     method add_notation : dtd_notation -> unit
107       (* add the given notation to this DTD. If there is already a declaration
108        * with the same name, a Validation_error is raised.
109        *)
110
111     method add_pinstr : proc_instruction -> unit
112       (* add the given processing instruction to this DTD. *)
113
114     method element : string -> dtd_element
115       (* looks up the element declaration with the given name. Raises 
116        * Validation_error if the element cannot be found. (If "allow_arbitrary"
117        * has been invoked before, Unrestricted is raised instead.)
118        *)
119
120     method element_names : string list
121       (* returns the list of the names of all element declarations. *)
122
123     method gen_entity : string -> (Pxp_entity.entity * bool)
124       (* let e, extdecl = obj # gen_entity n:
125        * looks up the general entity 'e' with the name 'n'. Raises
126        * WF_error if the entity cannot be found.
127        * 'extdecl': indicates whether the entity declaration occured in an 
128        * external entity.
129        *)
130
131     method gen_entity_names : string list
132       (* returns the list of all general entity names *)
133
134     method par_entity : string -> Pxp_entity.entity
135       (* looks up the parameter entity with the given name. Raises
136        * WF_error if the entity cannot be found.
137        *)
138
139     method par_entity_names : string list
140       (* returns the list of all parameter entity names *)
141
142     method notation : string -> dtd_notation
143       (* looks up the notation declaration with the given name. Raises
144        * Validation_error if the notation cannot be found. (If "allow_arbitrary"
145        * has been invoked before, Unrestricted is raised instead.)
146        *)
147
148     method notation_names : string list
149       (* Returns the list of the names of all added notations *)
150
151     method pinstr : string -> proc_instruction list
152       (* looks up all processing instructions with the given target.
153        * The "target" is the identifier following "<?".
154        * Note: It is not possible to find out the exact position of the
155        * processing instruction.
156        *)
157
158     method pinstr_names : string list
159       (* Returns the list of the names (targets) of all added pinstrs *)
160
161     method validate : unit
162       (* ensures that the DTD is valid. This method is optimized such that
163        * actual validation is only performed if DTD has changed.
164        * If the DTD is invalid, mostly a Validation_error is raised,
165        * but other exceptions are possible, too.
166        *)
167
168     method only_deterministic_models : unit
169       (* Succeeds if all regexp content models are deterministic. 
170        * Otherwise Validation_error.
171        *)
172
173     method write : Pxp_types.output_stream -> Pxp_types.encoding -> bool -> unit
174       (* write_compact_as_latin1 os enc doctype:
175        * Writes the DTD as 'enc'-encoded string to 'os'. If 'doctype', a 
176        * DTD like <!DOCTYPE root [ ... ]> is written. If 'not doctype',
177        * only the declarations are written (the material within the
178        * square brackets).
179        *)
180
181     method write_compact_as_latin1 : Pxp_types.output_stream -> bool -> unit
182       (* DEPRECATED METHOD; included only to keep compatibility with
183        * older versions of the parser
184        *)
185
186
187     (*----------------------------------------*)
188     method invalidate : unit
189       (* INTERNAL METHOD *)
190     method warner : Pxp_types.collect_warnings
191       (* INTERNAL METHOD *)
192   end
193
194 (*$-*)
195
196 (*$ markup-dtd2.mli *)
197
198 (* ---------------------------------------------------------------------- *)
199
200 and dtd_element : dtd -> string -> 
201   (* Creation:
202    *   new dtd_element init_dtd init_name:
203    * creates a new dtd_element object for init_dtd with init_name.
204    * The strings are represented in the same encoding as init_dtd.
205    *)
206   object
207
208     method name : string
209       (* returns the name of the declared element *)
210
211     method externally_declared : bool
212       (* returns whether the element declaration occurs in an external
213        * entity.
214        *)
215
216     method content_model : Pxp_types.content_model_type
217       (* get the content model of this element declaration, or Unspecified *)
218
219     method content_dfa : Pxp_dfa.dfa_definition option
220       (* return the DFA of the content model if there is a DFA, or None.
221        * A DFA exists only for regexp style content models which are
222        * deterministic.
223        *)
224
225     method set_cm_and_extdecl : Pxp_types.content_model_type -> bool -> unit
226       (* set_cm_and_extdecl cm extdecl:
227        * set the content model to 'cm'. Once the content model is not 
228        * Unspecified, it cannot be set to a different value again.
229        * Furthermore, it is set whether the element occurs in an external
230        * entity ('extdecl').
231        *)
232
233     method encoding : Pxp_types.rep_encoding
234       (* Return the encoding of the strings *)
235
236     method allow_arbitrary : unit
237       (* After this method has been invoked, the object changes its behaviour:
238        * - attributes that have not been added may be used in an
239        *   arbitrary way; the method "attribute" indicates this
240        *   by raising Undeclared instead of Validation_error.
241        *)
242
243     method disallow_arbitrary : unit
244
245     method arbitrary_allowed : bool
246       (* Returns whether arbitrary attributes are allowed or not. *)
247
248     method attribute : string -> 
249                          Pxp_types.att_type * Pxp_types.att_default
250       (* get the type and default value of a declared attribute, or raise
251        * Validation_error if the attribute does not exist.
252        * If 'arbitrary_allowed', the exception Undeclared is raised instead
253        * of Validation_error.
254        *)
255
256     method attribute_violates_standalone_declaration : 
257                string -> string option -> bool
258       (* attribute_violates_standalone_declaration name v:
259        * Checks whether the attribute 'name' violates the "standalone"
260        * declaration if it has value 'v'.
261        * The method returns true if:
262        * - The attribute declaration occurs in an external entity, 
263        * and if one of the two conditions holds:
264        * - v = None, and there is a default for the attribute value
265        * - v = Some s, and the type of the attribute is not CDATA,
266        *   and s changes if normalized according to the rules of the
267        *   attribute type.
268        *
269        * The method raises Validation_error if the attribute does not exist.
270        * If 'arbitrary_allowed', the exception Undeclared is raised instead
271        * of Validation_error.
272        *)
273
274     method attribute_names : string list
275       (* get the list of all declared attributes *)
276
277     method names_of_required_attributes : string list
278       (* get the list of all attributes that are specified as required 
279        * attributes
280        *)
281
282     method id_attribute_name : string option
283       (* Returns the name of the attribute with type ID, or None. *)
284
285     method idref_attribute_names : string list
286       (* Returns the names of the attributes with type IDREF or IDREFS. *)
287
288     method add_attribute : string -> 
289                            Pxp_types.att_type -> 
290                            Pxp_types.att_default -> 
291                            bool ->
292                              unit
293       (* add_attribute name type default extdecl:
294        * add an attribute declaration for an attribute with the given name,
295        * type, and default value. If there is more than one declaration for
296        * an attribute name, the first declaration counts; the other declarations
297        * are ignored.
298        * 'extdecl': if true, the attribute declaration occurs in an external
299        * entity. This property is used to check the "standalone" attribute.
300        *)
301
302     method validate : unit
303       (* checks whether this element declaration (i.e. the content model and
304        * all attribute declarations) is valid for the associated DTD.
305        * Raises mostly Validation_error if the validation fails.
306        *)
307
308     method write : Pxp_types.output_stream -> Pxp_types.encoding -> unit
309       (* write_compact_as_latin1 os enc:
310        * Writes the <!ELEMENT ... > declaration to 'os' as 'enc'-encoded string.
311        *)
312
313     method write_compact_as_latin1 : Pxp_types.output_stream -> unit
314       (* DEPRECATED METHOD; included only to keep compatibility with
315        * older versions of the parser
316        *)
317   end
318
319 (* ---------------------------------------------------------------------- *)
320
321 and dtd_notation : string -> Pxp_types.ext_id -> Pxp_types.rep_encoding ->
322   (* Creation:
323    *    new dtd_notation a_name an_external_ID init_encoding
324    * creates a new dtd_notation object with the given name and the given
325    * external ID.
326    *)
327   object
328     method name : string
329     method ext_id : Pxp_types.ext_id
330     method encoding : Pxp_types.rep_encoding
331
332     method write : Pxp_types.output_stream -> Pxp_types.encoding -> unit
333       (* write_compact_as_latin1 os enc:
334        * Writes the <!NOTATION ... > declaration to 'os' as 'enc'-encoded 
335        * string.
336        *)
337
338     method write_compact_as_latin1 : Pxp_types.output_stream -> unit
339       (* DEPRECATED METHOD; included only to keep compatibility with
340        * older versions of the parser
341        *)
342
343   end
344
345 (* ---------------------------------------------------------------------- *)
346
347 and proc_instruction : string -> string -> Pxp_types.rep_encoding ->
348   (* Creation:
349    *   new proc_instruction a_target a_value
350    * creates a new proc_instruction object with the given target string and
351    * the given value string. 
352    * Note: A processing instruction is written as <?target value?>. 
353    *)
354   object
355     method target : string
356     method value : string
357     method encoding : Pxp_types.rep_encoding
358
359     method write : Pxp_types.output_stream -> Pxp_types.encoding -> unit
360       (* write os enc:
361        * Writes the <?...?> PI to 'os' as 'enc'-encoded string.
362        *)
363
364     method write_compact_as_latin1 : Pxp_types.output_stream -> unit
365       (* DEPRECATED METHOD; included only to keep compatibility with
366        * older versions of the parser
367        *)
368
369     method parse_pxp_option : (string * string * (string * string) list)
370       (* Parses a PI containing a PXP option. Such PIs are formed like:
371        *   <?target option-name option-att="value" option-att="value" ... ?>
372        * The method returns a triple
373        *   (target, option-name, [option-att, value; ...])
374        * or raises Error.
375        *)
376
377   end
378
379 ;;
380
381 (*$-*)
382
383 (* ======================================================================
384  * History:
385  * 
386  * $Log$
387  * Revision 1.1  2000/11/17 09:57:29  lpadovan
388  * Initial revision
389  *
390  * Revision 1.8  2000/08/18 21:18:45  gerd
391  *      Updated wrong comments for methods par_entity and gen_entity.
392  * These can raise WF_error and not Validation_error, and this is the
393  * correct behaviour.
394  *
395  * Revision 1.7  2000/07/25 00:30:01  gerd
396  *      Added support for pxp:dtd PI options.
397  *
398  * Revision 1.6  2000/07/23 02:16:33  gerd
399  *      Support for DFAs.
400  *
401  * Revision 1.5  2000/07/16 16:34:41  gerd
402  *      New method 'write', the successor of 'write_compact_as_latin1'.
403  *
404  * Revision 1.4  2000/07/14 13:56:49  gerd
405  *      Added methods id_attribute_name and idref_attribute_names.
406  *
407  * Revision 1.3  2000/07/09 00:13:37  gerd
408  *      Added methods gen_entity_names, par_entity_names.
409  *
410  * Revision 1.2  2000/06/14 22:19:06  gerd
411  *      Added checks such that it is impossible to mix encodings.
412  *
413  * Revision 1.1  2000/05/29 23:48:38  gerd
414  *      Changed module names:
415  *              Markup_aux          into Pxp_aux
416  *              Markup_codewriter   into Pxp_codewriter
417  *              Markup_document     into Pxp_document
418  *              Markup_dtd          into Pxp_dtd
419  *              Markup_entity       into Pxp_entity
420  *              Markup_lexer_types  into Pxp_lexer_types
421  *              Markup_reader       into Pxp_reader
422  *              Markup_types        into Pxp_types
423  *              Markup_yacc         into Pxp_yacc
424  * See directory "compatibility" for (almost) compatible wrappers emulating
425  * Markup_document, Markup_dtd, Markup_reader, Markup_types, and Markup_yacc.
426  *
427  * ======================================================================
428  * Old logs from markup_dtd.ml:
429  *
430  * Revision 1.11  2000/05/29 21:14:57  gerd
431  *      Changed the type 'encoding' into a polymorphic variant.
432  *
433  * Revision 1.10  2000/05/27 19:20:38  gerd
434  *      Changed the interfaces for the standalone check: New
435  * methods: standalone_declaration, set_standalone_declaration,
436  * externally_declared, attribute_violates_standalone_declaration.
437  *      The method set_content_model has been renamed to
438  * set_cm_and_extdecl; it now initializes also whether the element
439  * has been declared in an external entity.
440  *      Methods add_gen_entity and gen_entity pass an additional
441  * boolean argument containing whether the declaration of the
442  * general entity happened in an external entity.
443  *      Method add_attribute expects this argument, too, which
444  * states whether the declaration of the attribute happened in an
445  * external entity.
446  *
447  * Revision 1.9  2000/05/20 20:31:40  gerd
448  *      Big change: Added support for various encodings of the
449  * internal representation.
450  *
451  * Revision 1.8  2000/05/06 23:10:26  gerd
452  *      allow_arbitrary for elements, too.
453  *
454  * Revision 1.7  2000/05/01 20:42:52  gerd
455  *         New method write_compact_as_latin1.
456  *
457  * Revision 1.6  2000/03/11 22:58:15  gerd
458  *      Updated to support Markup_codewriter.
459  *
460  * Revision 1.5  2000/02/22 02:32:02  gerd
461  *      Updated.
462  *
463  * Revision 1.4  1999/11/09 22:15:41  gerd
464  *      Added method "arbitrary_allowed".
465  *
466  * Revision 1.3  1999/09/01 16:21:56  gerd
467  *      "dtd" classes have now an argument that passes a "warner".
468  *
469  * Revision 1.2  1999/08/15 02:20:23  gerd
470  *         New feature: a DTD can allow arbitrary elements.
471  *
472  * Revision 1.1  1999/08/10 00:35:51  gerd
473  *      Initial revision.
474  *
475  * 
476  *)