1 # This file is part of NIT ( http://www.nitlanguage.org ).
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
11 # Interface for associating a SAX event with a document location.
12 module sax
::sax_locator
14 # Interface for associating a SAX event with a document location.
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.
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.
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.
35 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
37 # SEE: `sax::ContentHandler.document_locator`
38 public
interface SAXLocator
40 # Return the public identifier for the current document event.
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
48 # Return the system identifier for the current document event.
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.
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
61 # Return the line number where the current document event ends.
63 # Lines are delimited by line ends, which are defined in
64 # the XML specification.
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.
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.
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.
82 # Return -1 in absence of line number.
83 fun line_number
: Int is abstract
85 # Return the column number where the current document event ends.
87 # The number is one-based.
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.
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.
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.
105 # Return -1 in absence of column number.
106 fun column_number
: Int is abstract