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 # Interface for reading an XML document using callbacks.
12 module sax
::xml_reader
14 import entity_resolver
16 import content_handler
19 # Interface for reading an XML document using callbacks.
21 # `XMLReader` is the interface that an XML parser's SAX2 driver must
22 # implement. This interface allows an application to set and
23 # query features and properties in the parser, to register
24 # event handlers for document processing, and to initiate
27 # All SAX interfaces are assumed to be synchronous: the
28 # `parse` methods must not return until parsing
29 # is complete, and readers must wait for an event-handler callback
30 # to return before reporting the next event.
32 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
35 # Is the specified feature flag recognized by this parser?
39 # * `name`: feature name, which is a fully-qualified URI.
40 fun feature_recognized
(name
: String): Bool is abstract
42 # Is the retrieval of the specified feature flag supported given the current context?
46 # * `name`: feature name, which is a fully-qualified URI.
47 fun feature_readable
(name
: String): Bool is abstract
49 # Is the modification of the specified feature flag supported given the current context?
53 # * `name`: feature name, which is a fully-qualified URI.
54 fun feature_writable
(name
: String): Bool is abstract
56 # Look up the value of a feature flag.
58 # The feature name is any fully-qualified URI. It is
59 # possible for an `XMLReader` to recognize a feature name but
60 # temporarily be unable to return its value.
61 # Some feature values may be available only in specific
62 # contexts, such as before, during, or after a parse.
63 # Also, some feature values may not be programmatically accessible.
65 # All XMLReaders are required to recognize the
66 # `http://xml.org/sax/features/namespaces` and the
67 # `http://xml.org/sax/features/namespace-prefixes` feature names.
69 # Implementors are free (and encouraged) to invent their own features,
70 # using names built on their own URIs.
74 # * `name`: feature name, which is a fully-qualified URI.
78 # The current value of the feature.
80 # SEE: `feature_recognized`
82 # SEE: `feature_readable`
83 fun feature
(name
: String): Bool is abstract
85 # Set the value of a feature flag.
87 # The feature name is any fully-qualified URI. It is
88 # possible for an XMLReader to expose a feature value but
89 # to be unable to change the current value.
90 # Some feature values may be immutable or mutable only
91 # in specific contexts, such as before, during, or after
94 # All XMLReaders are required to support setting
95 # http://xml.org/sax/features/namespaces to true and
96 # http://xml.org/sax/features/namespace-prefixes to false.
100 # * `name`: feature name, which is a fully-qualified URI.
101 # * `value`: requested value of the feature.
103 # SEE: `feature_recognized`
105 # SEE: `feature_writable`
106 fun feature
=(name
: String, value
: Bool) is abstract
108 # Is the specified property recognized by this parser?
112 # * `name`: property name, which is a fully-qualified URI.
113 fun property_recognized
(name
: String): Bool is abstract
115 # Is the retrieval of the specified property supported given the current context?
119 # * `name`: property name, which is a fully-qualified URI.
120 fun property_readable
(name
: String): Bool is abstract
122 # Is the modification of the specified property supported given the current context?
126 # * `name`: property name, which is a fully-qualified URI.
127 fun property_writable
(name
: String): Bool is abstract
129 # Look up the value of a property.
131 # The property name is any fully-qualified URI. It is
132 # possible for an `XMLReader` to recognize a property name but
133 # temporarily be unable to return its value.
134 # Some property values may be available only in specific
135 # contexts, such as before, during, or after a parse.
137 # XMLReaders are not required to recognize any specific
138 # property names, though an initial core set is documented for
141 # Implementors are free (and encouraged) to invent their own properties,
142 # using names built on their own URIs.
146 # * `name`: property name, which is a fully-qualified URI.
150 # The current value of the property.
152 # SEE: `property_recognized`
154 # SEE: `property_supported`
155 fun property
(name
: String): nullable Object is abstract
157 # Set the value of a property.
159 # The property name is any fully-qualified URI. It is
160 # possible for an `XMLReader` to recognize a property name but
161 # to be unable to change the current value.
162 # Some property values may be immutable or mutable only
163 # in specific contexts, such as before, during, or after
166 # XMLReaders are not required to recognize setting
167 # any specific property names, though a core set is defined by
170 # This method is also the standard mechanism for setting
175 # * `name`: property name, which is a fully-qualified URI.
176 # * `value`: requested value for the property.
178 # SEE: `property_recognized`
180 # SEE: `property_writable`
181 fun property
=(name
: String, value
: nullable Object) is abstract
183 # Allow an application to register an entity resolver.
185 # If the application does not register an entity resolver,
186 # the XMLReader will perform its own default resolution.
188 # Applications may register a new or different resolver in the
189 # middle of a parse, and the SAX parser must begin using the new
190 # resolver immediately.
191 fun entity_resolver
=(resolver
: nullable EntityResolver) is abstract
193 # Return the current entity resolver.
195 # Return `null` if none has been registered.
196 fun entity_resolver
: nullable EntityResolver is abstract
198 # Allow an application to register a DTD event handler.
200 # If the application does not register a DTD handler, all DTD
201 # events reported by the SAX parser will be silently ignored.
203 # Applications may register a new or different handler in the
204 # middle of a parse, and the SAX parser must begin using the new
205 # handler immediately.
206 fun dtd_handler
=(handler
: nullable DTDHandler) is abstract
208 # Return the current DTD handler.
210 # Return `null` if none has been registered.
211 fun dtd_handler
: nullable DTDHandler is abstract
213 # Allow an application to register a content event handler.
215 # If the application does not register a content handler, all
216 # content events reported by the SAX parser will be silently
219 # Applications may register a new or different handler in the
220 # middle of a parse, and the SAX parser must begin using the new
221 # handler immediately.
222 fun content_handler
=(handler
: nullable ContentHandler) is abstract
224 # Return the current content handler.
226 # Return `null` if none has been registered.
227 fun content_handler
: nullable ContentHandler is abstract
229 # Allow an application to register an error event handler.
231 # If the application does not register an error handler, all
232 # error events reported by the SAX parser will be silently
233 # ignored; however, normal processing may not continue. It is
234 # highly recommended that all SAX applications implement an
235 # error handler to avoid unexpected bugs.
237 # Applications may register a new or different handler in the
238 # middle of a parse, and the SAX parser must begin using the new
239 # handler immediately.
240 fun error_handler
=(handler
: nullable ErrorHandler) is abstract
242 # Return the current error handler.
244 # Return `null` if none has been registered.
245 fun error_handler
: nullable ErrorHandler is abstract
247 # Parse an XML document.
249 # The application can use this method to instruct the XML
250 # reader to begin parsing an XML document from any valid input
251 # source (a byte stream or an URI).
253 # Applications may not invoke this method while a parse is in
254 # progress (they should create a new `XMLReader` instead for each
255 # nested XML document). Once a parse is complete, an
256 # application may reuse the same `XMLReader` object, possibly with a
257 # different input source.
259 # During the parse, the `XMLReader` will provide information
260 # about the XML document through the registered event
263 # This method is synchronous: it will not return until parsing
264 # has ended. If a client application wants to terminate
265 # parsing early, it should throw an exception.
269 # * `source`: input source for the top-level of the XML document.
270 fun parse
(input
: InputSource) is abstract
272 # Parse an XML document from a system identifier (URI).
274 # This method is a shortcut for the common case of reading a
275 # document from a system identifier. It is the exact
276 # equivalent of the following:
279 # var source = new InputSouce
280 # source.system_id = system_id
284 # If the system identifier is a URL, it must be fully resolved
285 # by the application before it is passed to the parser.
289 # * `systemId`: The system identifier (URI).
290 fun parse_file
(system_id
: String) is abstract