lib/sax/sax_locator.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 # Interface for associating a SAX event with a document location.
  12 module sax::sax_locator
  13
  14 # Interface for associating a SAX event with a document location.
  15 #
  16 # If a SAX parser provides location information to the SAX
  17 # application, it does so by implementing this interface and then
  18 # passing an instance to the application using the
  19 # `ContentHandler.document_locator=` method. The application can use
  20 # the object to obtain the location of any other SAX event
  21 # in the XML source document.
  22 #
  23 # Note that the results returned by the object will be valid only
  24 # during the scope of each callback method: the application
  25 # will receive unpredictable results if it attempts to use the
  26 # locator at any other time, or after parsing completes.
  27 #
  28 # SAX parsers are not required to supply a locator, but they are
  29 # very strongly encouraged to do so. If the parser supplies a
  30 # locator, it must do so before reporting any other document events.
  31 # If no locator has been set by the time the application receives
  32 # the `ContentHandler.start_document` event, the application should
  33 # assume that a locator is not available.
  34 #
  35 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
  36 #
  37 # SEE: `sax::ContentHandler.document_locator`
  38 public interface SAXLocator
  39
  40         # Return the public identifier for the current document event.
  41         #
  42         # Return the public identifier of the document
  43         # entity or of the external parsed entity in which the markup
  44         # triggering the event appears.
  45         # Return `null` if no public identifier is available.
  46         fun public_id: nullable String is abstract
  47
  48         # Return the system identifier for the current document event.
  49         #
  50         # Return the system identifier of the document
  51         # entity or of the external parsed entity in which the markup
  52         # triggering the event appears.
  53         # Return `null` if no system identifier is available.
  54         #
  55         # If the system identifier is a URL, the parser must resolve it
  56         # fully before passing it to the application. For example, a file
  57         # name must always be provided as a `file:` URL, and other
  58         # kinds of relative URI are also resolved against their bases.
  59         fun system_id: nullable String is abstract
  60
  61         # Return the line number where the current document event ends.
  62         #
  63         # Lines are delimited by line ends, which are defined in
  64         # the XML specification.
  65         #
  66         # **Warning:** The return value from this method
  67         # is intended only as an approximation for the sake of diagnostics;
  68         # it is not intended to provide sufficient information
  69         # to edit the character content of the original XML document.
  70         # In some cases, these "line" numbers match what would be displayed
  71         # as columns, and in others they may not match the source text
  72         # due to internal entity expansion.
  73         #
  74         # Return an approximation of the line number
  75         # in the document entity or external parsed entity where the
  76         # markup triggering the event appears.
  77         #
  78         # If possible, the SAX driver should provide the line position
  79         # of the first character after the text associated with the document
  80         # event. The first line is line 1.
  81         #
  82         # Return -1 in absence of line number.
  83         fun line_number: Int is abstract
  84
  85         # Return the column number where the current document event ends.
  86         #
  87         # The number is one-based.
  88         #
  89         # **Warning:** The return value from this method
  90         # is intended only as an approximation for the sake of diagnostics;
  91         # it is not intended to provide sufficient information
  92         # to edit the character content of the original XML document.
  93         # For example, when lines contain combining character sequences, wide
  94         # characters, surrogate pairs, or bi-directional text, the value may
  95         # not correspond to the column in a text editor's display.
  96         #
  97         # The return value is an approximation of the column number
  98         # in the document entity or external parsed entity where the
  99         # markup triggering the event appears.
 100         #
 101         # If possible, the SAX driver should provide the line position
 102         # of the first character after the text associated with the document
 103         # event. The first column in each line is column 1.
 104         #
 105         # Return -1 in absence of column number.
 106         fun column_number: Int is abstract
 107 end