lib/sax/dtd_handler.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 # Receives notification of basic DTD-related events.
  12 module sax::dtd_handler
  13
  14 # Receives notification of basic DTD-related events.
  15 #
  16 # If a SAX application needs information about notations and
  17 # unparsed entities, then the application implements this
  18 # interface and registers an instance with the SAX parser using
  19 # the parser's `dtd_handler` property. The parser uses the
  20 # instance to report notation and unparsed entity declarations to
  21 # the application.
  22 #
  23 # Note that this interface includes only those DTD events that
  24 # the XML recommendation *requires* processors to report:
  25 # notation and unparsed entity declarations.
  26 #
  27 # The SAX parser may report these events in any order, regardless
  28 # of the order in which the notations and unparsed entities were
  29 # declared; however, all DTD events must be reported after the
  30 # document handler's `start_document` event, and before the first
  31 # `start_element` event.
  32 # (If the `sax::ext::LexicalHandler` is
  33 # used, these events must also be reported before the `end_dtd` event.)
  34 #
  35 # It is up to the application to store the information for
  36 # future use (perhaps in a hash table or object tree).
  37 # If the application encounters attributes of type `NOTATION`,
  38 # `ENTITY`, or `ENTITIES`, it can use the information that it
  39 # obtained through this interface to find the entity and/or
  40 # notation corresponding with the attribute value.
  41 #
  42 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
  43 #
  44 # SEE: `sax::XMLReader.dtd_handler`
  45 abstract class DTDHandler
  46
  47         # Receive notification of a notation declaration event.
  48         #
  49         # It is up to the application to record the notation for later
  50         # reference, if necessary;
  51         # notations may appear as attribute values and in unparsed entity
  52         # declarations, and are sometime used with processing instruction
  53         # target names.
  54         #
  55         # At least one of `public_id` and `system_id` must be non-null.
  56         # If a system identifier is present, and it is a URL, the SAX
  57         # parser must resolve it fully before passing it to the
  58         # application through this event.
  59         #
  60         # There is no guarantee that the notation declaration will be
  61         # reported before any unparsed entities that use it.
  62         #
  63         # Parameters:
  64         #
  65         # * `name`: notation name.
  66         # * `public_id`: notation's public identifier, or null if none was given.
  67         # * `system_id`: notation's system identifier, or null if none was given.
  68         #
  69         # SEE: `sax::Attributes`
  70         fun notation_decl(name: String, public_id: String, system_id: String) do end
  71
  72         # Receive notification of an unparsed entity declaration event.
  73         #
  74         # Note that the notation name corresponds to a notation
  75         # reported by the `notation_decl` event.
  76         # It is up to the application to record the entity for later
  77         # reference, if necessary;
  78         # unparsed entities may appear as attribute values.
  79         #
  80         # If the system identifier is a URL, the parser must resolve it
  81         # fully before passing it to the application.
  82         #
  83         # Parameters:
  84         #
  85         # * `name`: unparsed entity's name.
  86         # * `public_id`: entity's public identifier, or null if none was given.
  87         # * `system_id`: entity's system identifier, or null if none was given.
  88         #
  89         # SEE: `sax::Attributes`
  90         fun unparsed_entity_decl(name: String, public_id: String,
  91                         system_id: String) do end
  92 end