lib/sax/input_source.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 # A single input source for an XML entity.
  12 module sax::input_source
  13
  14 # A single input source for an XML entity.
  15 #
  16 # This class allows a SAX application to encapsulate information
  17 # about an input source in a single object, which may include
  18 # a public identifier, a system identifier and a stream (possibly
  19 # with a specified encoding).
  20 #
  21 # There are two places that the application can deliver an
  22 # input source to the parser: as the argument to the `XMLReader.parse`
  23 # method, or as the return value of the `EntityResolver.resolve_entity`
  24 # method.
  25 #
  26 # The SAX parser will use the `InputSource` object to determine how to read XML
  27 # input. If there is a byte stream, the parser will use that byte stream, using
  28 # the encoding specified in the InputSource or else (if no encoding is
  29 # specified) autodetecting the character encoding using an algorithm
  30 # such as the one in the XML specification. If no byte stream is available, the
  31 # parser will attempt to open a URI connection to the resource identified by
  32 # the system identifier.
  33 #
  34 # An InputSource object belongs to the application: the SAX parser
  35 # shall never modify it in any way (it may modify a copy if
  36 # necessary). However, standard processing of the stream is to close it on as
  37 # part of end-of-parse cleanup, so applications should not attempt to re-use
  38 # such streams after they have been handed to a parser.
  39 #
  40 # Note: The original documentation comes, in part,
  41 # from [SAX 2.0](http://www.saxproject.org).
  42 class InputSource
  43
  44         # Create a new input source with the specified system identifier.
  45         #
  46         # Applications may use `public_id=` to include a public identifier as well,
  47         # or `encoding=` to specify the character encoding, if known.
  48         #
  49         # If the system identifier is a URL, it must be fully resolved (it may not
  50         # be a relative URL).
  51         init with_system_id(system_id: String) do
  52                 self.system_id = system_id
  53         end
  54
  55         # Create a new input source with the specified stream.
  56         #
  57         # Application writers should use `system_id=` to provide a base for
  58         # resolving relative URIs, may use `public_id=` to include a public
  59         # identifier, and may use `encoding=` to specify the object's character
  60         # encoding.
  61         init with_stream(stream: IStream) do
  62                 self.stream = stream
  63         end
  64
  65         # The public identifier as a string.
  66         #
  67         # The public identifier is always optional: if the application
  68         # writer includes one, it will be provided as part of the
  69         # location information.
  70         var public_id: nullable String = null is writable
  71
  72         # The system identifier as a string.
  73         #
  74         # If its an URL, it must be fully resolved (it may not be a relative URL).
  75         #
  76         # Applications may set `public_id` to include a
  77         # public identifier as well, or set `encoding` to specify
  78         # the character encoding, if known.
  79         var system_id: nullable String = null is writable
  80
  81         # The stream containing the document.
  82         #
  83         # Application writers should set `system_id` to provide a base
  84         # for resolving relative URIs, may set `public_id` to include a
  85         # public identifier, and may set `encoding` to specify the object's
  86         # character encoding.
  87         var stream: nullable IStream = null is writable
  88
  89         # The character encoding, if known.
  90         #
  91         # The encoding must be a string acceptable for an
  92         # XML encoding declaration (see section 4.3.3 of the XML 1.0
  93         # recommendation).
  94         var encoding: nullable String = null is writable
  95 end