lib/sax/sax.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   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
   9 # another product.
  10
  11 # Core SAX APIs.
  12 #
  13 # This is a (partial) port of the original SAX API. See
  14 # [http://www.saxproject.org](http://www.saxproject.org) for more information
  15 # about SAX.
  16 #
  17 # SAX2 Standard Feature Flags:
  18 #
  19 # One of the essential characteristics of SAX2 is that it added
  20 # feature flags which can be used to examine and perhaps modify
  21 # parser modes, in particular modes such as validation.
  22 # Since features are identified by (absolute) URIs, anyone
  23 # can define such features.
  24 #
  25 # For default values not specified by SAX2,
  26 # each `XMLReader` implementation specifies its default,
  27 # or may choose not to expose the feature flag.
  28 # Unless otherwise specified here,
  29 # implementations may support changing current values
  30 # of these standard feature flags, but not while parsing.
  31 #
  32 # Currently defined standard feature URIs have the prefix
  33 # `http://xml.org/sax/features/` before an identifier such as
  34 # `validation`. Support for the default values of the
  35 # `namespaces` and `namespace-prefixes`
  36 # properties is required. Turn features on or off using
  37 # `feature=`. Those standard identifiers are:
  38 #
  39 # `external-general-entities`:
  40 #
  41 # * Access: read/write
  42 # * Default: unspecified
  43 # * Description: Reports whether this parser processes external general
  44 # entities; always `true` if validating.
  45 #
  46 # `external-parameter-entities`:
  47 #
  48 # * Access: read/write
  49 # * Default: unspecified
  50 # * Description: Reports whether this parser processes external parameter
  51 # entities; always `true` if validating.
  52 #
  53 # `is-standalone`:
  54 #
  55 # * Access: read-only while parsing, none while not parsing
  56 # * Default: not applicable
  57 # * Description: May be examined only during a parse, after the `start_document`
  58 # callback has been completed; read-only. The value is `true` if the document
  59 # specified `standalone="yes"` in its XML declaration, and otherwise is `false`.
  60 #
  61 # `lexical-handler/parameter-entities`:
  62 #
  63 # * Access: read/write
  64 # * Default: unspecified
  65 # * Description: `true` indicates that the LexicalHandler will report the
  66 # beginning and end of parameter entities.
  67 #
  68 # `namespaces`:
  69 #
  70 # * Access: read/write
  71 # * Default: `true`
  72 # * Description: `true` indicates namespace URIs and unprefixed local names
  73 # for element and attribute names will be available.
  74 #
  75 # `namespace-prefixes`:
  76 #
  77 # * Access: read/write
  78 # * Default: `false`
  79 # * Description: `true` indicates XML 1.0 names (with prefixes) and attributes
  80 # (including `xmlns*` attributes) will be available.
  81 #
  82 # `resolve-dtd-uris`:
  83 #
  84 # * Access: read/write
  85 # * Default: `true`
  86 # * Description: `true` indicates that system IDs in declarations will be
  87 # absolutized (relative to their base URIs) before reporting. (That is the
  88 # default behavior for all SAX2 XML parsers.) A value of "false" indicates those
  89 # IDs will not be absolutized; parsers will provide the base URI from
  90 # `SAXLocator.system_id`. This applies to system IDs passed in
  91 # `DTDHandler.notation_decl`, DTDHandler.unparsed_entity_decl`, and
  92 # `DeclHandler.external_entity_decl`. It does not apply to
  93 # `EntityResolver.resolve_entity`, which is not used to report declarations, or
  94 # to `LexicalHandler.start_dtd`, which already provides the non-absolutized URI.
  95 #
  96 # `string-interning`:
  97 #
  98 # * Access: read-only
  99 # * Default: `false`
 100 # * Description: (Java-specific. Not supported in Nit.)
 101 #
 102 # `unicode-normalization-checking`:
 103 #
 104 # * Access: read/write
 105 # * Default: `false`
 106 # * Description: Controls whether the parser reports Unicode normalization
 107 # errors as described in section 2.13 and Appendix B of the XML 1.1
 108 # Recommendation. If `true`, Unicode normalization errors are reported using
 109 # the `ErrorHandler.error` callback. Such errors are not fatal in themselves
 110 # (though, obviously, other Unicode-related encoding errors may be).
 111 #
 112 # `use-attributes2`:
 113 #
 114 # * Access: read-only
 115 # * Default: not applicable
 116 # * Description: Returns `true` if the `Attributes` objects passed by this
 117 # parser in `ContentHandler.start_element` implement the
 118 # `sax::ext::Attributes2` interface. That interface exposes additional
 119 # DTD-related information, such as whether the attribute was specified in the
 120 # source text rather than defaulted.
 121 #
 122 # TODO: interface not yet available in Nit.
 123 #
 124 # `use-locator2`:
 125 #
 126 # * Access: read-only
 127 # * Default: not applicable
 128 # * Description: Returns `true` if the `SAXLocator` objects passed by this
 129 # parser in `ContentHandler.document_locator=` implement the
 130 # `sax::ext::SAXLocator2` interface. That interface exposes additional
 131 # entity information, such as the character encoding and XML version used.
 132 #
 133 # TODO: interface not yet available in Nit.
 134 #
 135 # `use-entity-resolver2`:
 136 #
 137 # * Access: read/write
 138 # * Default: true
 139 # * Description: Returns `true` if, when `entity_resolver` is given an object
 140 # implementing the `sax::ext::EntityResolver2` interface, those new methods
 141 # will be used. Returns `false` to indicate that those methods will not be used.
 142 #
 143 # `validation`:
 144 #
 145 # * Access: read/write
 146 # * Default: unspecified
 147 # * Description: controls whether the parser is reporting all validity errors;
 148 # if true, all external entities will be read.
 149 #
 150 # `xmlns-uris`:
 151 #
 152 # * Access: read/write
 153 # * Default: `false`
 154 # * Description: Controls whether, when the `namespace-prefixes` feature is set,
 155 # the parser treats namespace declaration attributes as being in the
 156 # `http://www.w3.org/2000/xmlns/` namespace. By default, SAX2 conforms to the
 157 # original "Namespaces in XML" Recommendation, which explicitly states that such
 158 # attributes are not in any namespace. Setting this optional flag to `true`
 159 # makes the SAX2 events conform to a later backwards-incompatible revision of
 160 # that recommendation, placing those attributes in a namespace.
 161 #
 162 # `xml-1.1`:
 163 #
 164 # * Access: read-only
 165 # * Default: not applicable
 166 # * Description: Returns `true` if the parser supports both XML 1.1 and XML 1.0.
 167 # Returns "false" if the parser supports only XML 1.0.
 168 #
 169 #
 170 # SAX2 Standard Handler and Property IDs:
 171 #
 172 # For parser interface characteristics that are described as objects, a
 173 # separate namespace is defined. The objects in this namespace are again
 174 # identified by URI, and the standard property URIs have the prefix
 175 # `http://xml.org/sax/properties/` before an identifier such as
 176 # `lexical-handler` or `dom-node`. All of these standard properties are
 177 # optional; `XMLReader` implementations need not support them. Manage those
 178 # properties using `property=`. Those identifiers are:
 179 #
 180 # `declaration-handler`:
 181 #
 182 # Used to see most DTD declarations except those treated as lexical (“document
 183 # element name is...”) or which are mandatory for all SAX parsers
 184 # (`DTDHandler`). The object must implement `sax::ext::DeclHandler`.
 185 #
 186 # `document-xml-version`:
 187 #
 188 # May be examined only during a parse, after the `start_document` callback
 189 # has been completed; read-only. This property is a literal string describing
 190 # the actual XML version of the document, such as `"1.0"` or `"1.1"`.
 191 #
 192 # `dom-node`:
 193 #
 194 # For “DOM Walker” style parsers, which ignore their `parser.parse` parameters,
 195 # this is used to specify the DOM (sub)tree being walked by the parser. The
 196 # object must implement the `xml.dom.Node` interface.
 197 #
 198 # TODO: interface not yet available in Nit.
 199 #
 200 # `lexical-handler`:
 201 #
 202 # Used to see some syntax events that are essential in some applications:
 203 # comments, `CDATA` delimeters, selected general entity inclusions, and the
 204 # start and end of the DTD (and declaration of document element name).
 205 # The object must implement `sax::ext::LexicalHandler`.
 206 #
 207 # `xml-string`:
 208 #
 209 # Readable only during a parser callback, this exposes a **TBS** chunk of
 210 # characters responsible for the current event.
 211 #
 212 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
 213 module sax
 214
 215 import attributes
 216 import content_handler
 217 import dtd_handler
 218 import entity_resolver
 219 import error_handler
 220 import input_source
 221 import sax_locator
 222 import sax_parse_exception
 223 import xml_filter
 224 import xml_reader