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 # Receives notification of the logical content of a document.
12 module sax
::content_handler
17 # Receives notification of the logical content of a document.
19 # This is the main interface that most SAX applications
20 # implement: if the application needs to be informed of basic parsing
21 # events, it implements this interface and registers an instance with
22 # the SAX parser using the `sax::XMLReader.content_handler`
23 # attribute. The parser uses the instance to report
24 # basic document-related events like the start and end of elements
27 # The order of events in this interface is very important, and
28 # mirrors the order of information in the document itself. For
29 # example, all of an element's content (character data, processing
30 # instructions, and/or subelements) will appear, in order, between
31 # the startElement event and the corresponding endElement event.
33 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
35 # SEE: `sax::XMLReader`
37 # SEE: `sax::DTDHandler`
39 # SEE: `sax::ErrorHandler`
40 abstract class ContentHandler
42 # Receive an object for locating the origin of SAX document events.
44 # SAX parsers are strongly encouraged (though not absolutely
45 # required) to supply a locator: if it does so, it must supply
46 # the locator to the application by invoking this method before
47 # invoking any of the other methods in the ContentHandler
50 # The locator allows the application to determine the end
51 # position of any document-related event, even if the parser is
52 # not reporting an error. Typically, the application will
53 # use this information for reporting its own errors (such as
54 # character content that does not match an application's
55 # business rules). The information returned by the locator
56 # is probably not sufficient for use with a search engine.
58 # Note that the locator will return correct information only
59 # during the invocation of the events in this interface. The
60 # application should not attempt to use it at any other time.
64 # * `locator`: object that can return the location of
65 # any SAX document event.
67 # SEE: `sax::SAXLocator`
68 fun document_locator
=(locator
: SAXLocator) do end
71 # Receive notification of the beginning of a document.
73 # The SAX parser will invoke this method only once, before any
74 # other event callbacks (except for `document_locator`).
77 fun start_document
do end
80 # Receive notification of the end of a document.
82 # The SAX parser will invoke this method only once, and it will
83 # be the last method invoked during the parse. The parser shall
84 # not invoke this method until it has either abandoned parsing
85 # (because of an unrecoverable error) or reached the end of
88 # SEE: `start_document`
89 fun end_document
do end
92 # Begin the scope of a prefix-URI Namespace mapping.
94 # The information from this event is not necessary for
95 # normal Namespace processing: the SAX XML reader will
96 # automatically replace prefixes for element and attribute
97 # names when the `http://xml.org/sax/features/namespaces`
98 # feature is `true` (the default).
100 # There are cases, however, when applications need to
101 # use prefixes in character data or in attribute values,
102 # where they cannot safely be expanded automatically; the
103 # `start/end_prefix_mapping` event supplies the information
104 # to the application to expand prefixes in those contexts
105 # itself, if necessary.
107 # Note that `start/end_prefix_mapping` events are not
108 # guaranteed to be properly nested relative to each other:
109 # all `start/end_prefix_mapping` events will occur immediately before the
110 # corresponding `start_element` event,
111 # and all `end_prefix_mapping`
112 # events will occur immediately after the corresponding
113 # `end_element` event, but their order is not otherwise
116 # There should never be `start/end_prefix_mapping` events for the
117 # `xml` prefix, since it is predeclared and immutable.
121 # * `prefix`: Namespace prefix being declared.
122 #An empty string is used for the default element namespace,
123 #which has no prefix.
124 # * `uri`: Namespace URI the prefix is mapped to.
126 # SEE: `end_prefix_mapping`
127 # SEE: `start_element`
128 fun start_prefix_mapping
(prefix
: String, uri
: String) do end
131 # End the scope of a prefix-URI mapping.
133 # See `start_prefix_mapping` for
134 # details. These events will always occur immediately after the
135 # corresponding `end_prefix_mapping` event, but the order of
136 # `end_prefix_mapping` events is not otherwise
141 # * `prefix`: prefix that was being mapping.
142 # This is the empty string when a default mapping scope ends.
144 # SEE: `start_prefix_mapping`
146 fun end_prefix_mapping
(prefix
: String) do end
148 # Receive notification of the beginning of an element.
150 # The Parser will invoke this method at the beginning of every
151 # element in the XML document; there will be a corresponding
152 # `end_element` event for every startElement event
153 # (even when the element is empty). All of the element's content will be
154 # reported, in order, before the corresponding `end_element`
157 # This event allows up to three name components for each
160 # 1. the Namespace URI;
161 # 2. the local name; and
162 # 3. the qualified (prefixed) name.
164 # Any or all of these may be provided, depending on the
165 # values of the `http://xml.org/sax/features/namespaces`
166 # and the `http://xml.org/sax/features/namespace-prefixes`
169 # * the Namespace URI and local name are required when
170 # the namespaces property is `true` (the default), and are
171 # optional when the namespaces property is `false` (if one is
172 # specified, both must be);
173 # * the qualified name is required when the namespace-prefixes property
174 # is `true`, and is optional when the namespace-prefixes property
175 # is `false` (the default).
177 # Note that the attribute list provided will contain only
178 # attributes with explicit values (specified or defaulted):
179 # `#IMPLIED` attributes will be omitted. The attribute list
180 # will contain attributes used for Namespace declarations
181 # (`xmlns*` attributes) only if the
182 # `http://xml.org/sax/features/namespace-prefixes`
183 # property is true (it is `false` by default, and support for a
184 # `true` value is optional).
188 # * `uri`: Namespace URI, or the empty string if the
189 # element has no Namespace URI or if Namespace
190 # processing is not being performed.
191 # * `localName`: local name (without prefix), or the
192 # empty string if Namespace processing is not being
194 # * `qname`: The qualified XML 1.0 name (with prefix), or the
195 # empty string if qualified names are not available.
196 # * `atts`: attributes attached to the element.
199 # SEE: `sax::Attributes`
200 fun start_element
(uri
: String, local_name
: String, qname
: String,
201 atts
: Attributes) do end
203 # Receive notification of the end of an element.
205 # The SAX parser will invoke this method at the end of every
206 # element in the XML document; there will be a corresponding
207 # `start_element` event for every `end_element`
208 # event (even when the element is empty).
210 # For information on the names, see `start_element`.
214 # * `uri`: Namespace URI, or the empty string if the
215 # element has no Namespace URI or if Namespace
216 # processing is not being performed.
217 # * `localName`: local name (without prefix), or the
218 # empty string if Namespace processing is not being
220 # * `qname`: The qualified XML 1.0 name (with prefix), or the
221 # empty string if qualified names are not available.
222 fun end_element
(uri
: String, local_name
: String, qname
: String) do end
224 # Receive notification of character data.
226 # The Parser will call this method to report each chunk of
227 # character data. SAX parsers may return all contiguous character
228 # data in a single chunk, or they may split it into several
229 # chunks; however, all of the characters in any single event
230 # must come from the same external entity so that the `SAXLocator`
231 # provides useful information.
233 # Note that some parsers will report whitespace in element
234 # content using the `ignorable_whitespace`
235 # method rather than this one (validating parsers *must* do so).
239 # * `str`: characters from the XML document.
241 # SEE: `ignorable_whitespace`
242 # SEE: `sax::SAXLocator`
243 fun characters
(str
: String) do end
245 # Receive notification of ignorable whitespace in element content.
247 # Validating Parsers must use this method to report each chunk
248 # of whitespace in element content (see the W3C XML 1.0 recommendation,
249 # section 2.10): non-validating parsers may also use this method
250 # if they are capable of parsing and using content models.
252 # SAX parsers may return all contiguous whitespace in a single
253 # chunk, or they may split it into several chunks; however, all of
254 # the characters in any single event must come from the same
255 # external entity, so that the `SAXLocator` provides useful
260 # * `str`: characters from the XML document.
263 fun ignorable_whitespace
(str
: String) do end
265 # Receive notification of a processing instruction.
267 # The Parser will invoke this method once for each processing
268 # instruction found: note that processing instructions may occur
269 # before or after the main document element.
271 # A SAX parser must never report an XML declaration (XML 1.0,
272 # section 2.8) or a text declaration (XML 1.0, section 4.3.1)
277 # * `target`: processing instruction target.
278 # * `data`: processing instruction data, or `null` if
279 # none was supplied. The data does not include any
280 # whitespace separating it from the target.
281 fun processing_instruction
(target
: String, data
: nullable String) do end
283 # Receive notification of a skipped entity.
285 # This is not called for entity references within markup constructs
286 # such as element start tags or markup declarations. (The XML
287 # recommendation requires reporting skipped external entities.
288 # SAX also reports internal entity expansion/non-expansion, except
289 # within markup constructs.)
291 # The Parser will invoke this method each time the entity is
292 # skipped. Non-validating processors may skip entities if they
293 # have not seen the declarations (because, for example, the
294 # entity was declared in an external DTD subset). All processors
295 # may skip external entities, depending on the values of the
296 # `http://xml.org/sax/features/external-general-entities`
298 # `http://xml.org/sax/features/external-parameter-entities`
303 # * `name`: The name of the skipped entity. If it is a
304 # parameter entity, the name will begin with `%`, and if
305 # it is the external DTD subset, it will be the string
307 fun skipped_entity
(name
: String) do end