lib/sax/ext/lexical_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 # SAX2 extension handler for lexical events.
  12 module sax::ext::lexical_handler
  13
  14 # SAX2 extension handler for lexical events.
  15 #
  16 #
  17 # This is an optional extension handler for SAX2 to provide
  18 # lexical information about an XML document, such as comments
  19 # and `CDATA` section boundaries.
  20 # XML readers are not required to recognize this handler, and it
  21 # is not part of core-only SAX2 distributions.
  22 #
  23 # The events in the lexical handler apply to the entire document,
  24 # not just to the document element, and all lexical handler events
  25 # must appear between the content handler's startDocument and
  26 # endDocument events.
  27 #
  28 # To set the LexicalHandler for an XML reader, use the
  29 # `setProperty` method
  30 # with the property name
  31 # `http://xml.org/sax/properties/lexical-handler`
  32 # and an object implementing this interface (or `null`) as the value.
  33 #
  34 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
  35 abstract class LexicalHandler
  36
  37         # Report the start of DTD declarations, if any.
  38         #
  39         # This method is intended to report the beginning of the
  40         # `DOCTYPE` declaration; if the document has no `DOCTYPE` declaration,
  41         # this method will not be invoked.
  42         #
  43         # All declarations reported through `DTDHandler` or `DeclHandler` events
  44         # must appear between the `start_dtd` and `end_dtd` events.
  45         # Declarations are assumed to belong to the internal DTD subset
  46         # unless they appear between `start_entity` and `end_entity` events.
  47         # Comments and processing instructions from the DTD should also be reported
  48         # between the `start_dtd` and `end_dtd` events, in their original
  49         # order of (logical) occurrence; they are not required to
  50         # appear in their correct locations relative to `DTDHandler`
  51         # or `DeclHandler` events, however.
  52         #
  53         # Note that the `start_dtd`/`end_dtd` events will appear within
  54         # the `start_document` and `end_document` events from `ContentHandler` and
  55         # before the first `start_element` event.
  56         #
  57         # Parameters:
  58         #
  59         # * `name`: document type name.
  60         # * `public_id`: declared public identifier for the
  61         # external DTD subset, or `null` if none was declared.
  62         # * `system_id`: declared system identifier for the
  63         # external DTD subset, or `null` if none was declared.
  64         # (Note that this is not resolved against the document
  65         # base URI.)
  66         #
  67         # SEE: `end_dtd`
  68         #
  69         # SEE: `start_entity`
  70         fun start_dtd(name: String, public_id: nullable String,
  71                         system_id: nullable String) do end
  72
  73         # Report the end of DTD declarations.
  74         #
  75         # This method is intended to report the end of the
  76         # `DOCTYPE` declaration; if the document has no `DOCTYPE` declaration,
  77         # this method will not be invoked.
  78         #
  79         # SEE: `start_dtd`
  80         fun end_dtd do end
  81
  82         # Report the beginning of some internal and external XML entities.
  83         #
  84         # The reporting of parameter entities (including
  85         # the external DTD subset) is optional, and SAX2 drivers that
  86         # report `LexicalHandler` events may not implement it; you can use the
  87         # `http://xml.org/sax/features/lexical-handler/parameter-entities`
  88         # feature to query or control the reporting of parameter entities.
  89         #
  90         # General entities are reported with their regular names,
  91         # parameter entities have `%` prepended to their names, and
  92         # the external DTD subset has the pseudo-entity name `[dtd]`.
  93         #
  94         # When a SAX2 driver is providing these events, all other
  95         # events must be properly nested within start/end entity
  96         # events. There is no additional requirement that events from
  97         # `DeclHandler` or `org.xml.sax.DTDHandler DTDHandler` be properly ordered.
  98         #
  99         # Note that skipped entities will be reported through the
 100         # `skippedEntity` event, which is part of the `ContentHandler` interface.
 101         #
 102         # Because of the streaming event model that SAX uses, some
 103         # entity boundaries cannot be reported under any
 104         # circumstances:
 105         #
 106         # * general entities within attribute values
 107         # * parameter entities within declarations
 108         #
 109         # These will be silently expanded, with no indication of where
 110         # the original entity boundaries were.
 111         #
 112         # Note also that the boundaries of character references (which
 113         # are not really entities anyway) are not reported.
 114         #
 115         # All `start_entity` and `end_entity` events must be properly nested.
 116         #
 117         # Parameter:
 118         #
 119         # * `name`: name of the entity. If it is a parameter
 120         # entity, the name will begin with `%`, and if it is the
 121         # external DTD subset, it will be `[dtd]`.
 122         #
 123         # SEE: `end_entity`
 124         #
 125         # SEE: `sax::ext::DeclHandler.internal_entity_decl`
 126         #
 127         # SEE: `sax::ext::DeclHandler.external_entity_decl`
 128         fun start_entity(name: String) do end
 129
 130         # Report the end of an entity.
 131         #
 132         # * `name`: name of the entity that is ending.
 133         #
 134         # SEE: `start_entity`
 135         fun end_entity(name: String) do end
 136
 137         # Report the start of a `CDATA` section.
 138         #
 139         # The contents of the `CDATA` section will be reported through
 140         # the regular `characters` event; this event is intended only to report
 141         # the boundary.
 142         #
 143         # SEE: `end_cdata`
 144         fun start_cdata do end
 145
 146         # Report the end of a CDATA section.
 147         #
 148         # SEE: `start_cdata`
 149         fun end_cdata do end
 150
 151         # Report an XML comment anywhere in the document.
 152         #
 153         # This callback will be used for comments inside or outside the
 154         # document element, including comments in the external DTD
 155         # subset (if read). Comments in the DTD must be properly
 156         # nested inside `start/end_dtd` and `start/end_entity` events (if
 157         # used).
 158         #
 159         # Parameters:
 160         #
 161         # * `str`: characters in the comment.
 162         fun comment(str: String) do end
 163 end