1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # This file is free software, which comes along with NIT. This software is
4 # distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
5 # without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
6 # PARTICULAR PURPOSE. You can modify it is you want, provided this header
7 # is kept unaltered, and a notification of the changes is added.
8 # You are allowed to redistribute it and sell it, alone or is a part of
11 # SAX2 extension handler for lexical events.
12 module sax
::ext
::lexical_handler
14 # SAX2 extension handler for lexical events.
17 # This is an optional extension handler for SAX2 to provide
18 # lexical information about an XML document, such as comments
19 # and `CDATA` section boundaries.
20 # XML readers are not required to recognize this handler, and it
21 # is not part of core-only SAX2 distributions.
23 # The events in the lexical handler apply to the entire document,
24 # not just to the document element, and all lexical handler events
25 # must appear between the content handler's startDocument and
28 # To set the LexicalHandler for an XML reader, use the
29 # `setProperty` method
30 # with the property name
31 # `http://xml.org/sax/properties/lexical-handler`
32 # and an object implementing this interface (or `null`) as the value.
34 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
35 abstract class LexicalHandler
37 # Report the start of DTD declarations, if any.
39 # This method is intended to report the beginning of the
40 # `DOCTYPE` declaration; if the document has no `DOCTYPE` declaration,
41 # this method will not be invoked.
43 # All declarations reported through `DTDHandler` or `DeclHandler` events
44 # must appear between the `start_dtd` and `end_dtd` events.
45 # Declarations are assumed to belong to the internal DTD subset
46 # unless they appear between `start_entity` and `end_entity` events.
47 # Comments and processing instructions from the DTD should also be reported
48 # between the `start_dtd` and `end_dtd` events, in their original
49 # order of (logical) occurrence; they are not required to
50 # appear in their correct locations relative to `DTDHandler`
51 # or `DeclHandler` events, however.
53 # Note that the `start_dtd`/`end_dtd` events will appear within
54 # the `start_document` and `end_document` events from `ContentHandler` and
55 # before the first `start_element` event.
59 # * `name`: document type name.
60 # * `public_id`: declared public identifier for the
61 # external DTD subset, or `null` if none was declared.
62 # * `system_id`: declared system identifier for the
63 # external DTD subset, or `null` if none was declared.
64 # (Note that this is not resolved against the document
70 fun start_dtd
(name
: String, public_id
: nullable String,
71 system_id
: nullable String) do end
73 # Report the end of DTD declarations.
75 # This method is intended to report the end of the
76 # `DOCTYPE` declaration; if the document has no `DOCTYPE` declaration,
77 # this method will not be invoked.
82 # Report the beginning of some internal and external XML entities.
84 # The reporting of parameter entities (including
85 # the external DTD subset) is optional, and SAX2 drivers that
86 # report `LexicalHandler` events may not implement it; you can use the
87 # `http://xml.org/sax/features/lexical-handler/parameter-entities`
88 # feature to query or control the reporting of parameter entities.
90 # General entities are reported with their regular names,
91 # parameter entities have `%` prepended to their names, and
92 # the external DTD subset has the pseudo-entity name `[dtd]`.
94 # When a SAX2 driver is providing these events, all other
95 # events must be properly nested within start/end entity
96 # events. There is no additional requirement that events from
97 # `DeclHandler` or `org.xml.sax.DTDHandler DTDHandler` be properly ordered.
99 # Note that skipped entities will be reported through the
100 # `skippedEntity` event, which is part of the `ContentHandler` interface.
102 # Because of the streaming event model that SAX uses, some
103 # entity boundaries cannot be reported under any
106 # * general entities within attribute values
107 # * parameter entities within declarations
109 # These will be silently expanded, with no indication of where
110 # the original entity boundaries were.
112 # Note also that the boundaries of character references (which
113 # are not really entities anyway) are not reported.
115 # All `start_entity` and `end_entity` events must be properly nested.
119 # * `name`: name of the entity. If it is a parameter
120 # entity, the name will begin with `%`, and if it is the
121 # external DTD subset, it will be `[dtd]`.
125 # SEE: `sax::ext::DeclHandler.internal_entity_decl`
127 # SEE: `sax::ext::DeclHandler.external_entity_decl`
128 fun start_entity
(name
: String) do end
130 # Report the end of an entity.
132 # * `name`: name of the entity that is ending.
134 # SEE: `start_entity`
135 fun end_entity
(name
: String) do end
137 # Report the start of a `CDATA` section.
139 # The contents of the `CDATA` section will be reported through
140 # the regular `characters` event; this event is intended only to report
144 fun start_cdata
do end
146 # Report the end of a CDATA section.
151 # Report an XML comment anywhere in the document.
153 # This callback will be used for comments inside or outside the
154 # document element, including comments in the external DTD
155 # subset (if read). Comments in the DTD must be properly
156 # nested inside `start/end_dtd` and `start/end_entity` events (if
161 # * `str`: characters in the comment.
162 fun comment
(str
: String) do end