1 | // |
---|
2 | // Locator.h |
---|
3 | // |
---|
4 | // $Id: //poco/1.3/XML/include/Poco/SAX/Locator.h#1 $ |
---|
5 | // |
---|
6 | // Library: XML |
---|
7 | // Package: SAX |
---|
8 | // Module: SAX |
---|
9 | // |
---|
10 | // SAX Locator Interface. |
---|
11 | // |
---|
12 | // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH. |
---|
13 | // and Contributors. |
---|
14 | // |
---|
15 | // Permission is hereby granted, free of charge, to any person or organization |
---|
16 | // obtaining a copy of the software and accompanying documentation covered by |
---|
17 | // this license (the "Software") to use, reproduce, display, distribute, |
---|
18 | // execute, and transmit the Software, and to prepare derivative works of the |
---|
19 | // Software, and to permit third-parties to whom the Software is furnished to |
---|
20 | // do so, all subject to the following: |
---|
21 | // |
---|
22 | // The copyright notices in the Software and this entire statement, including |
---|
23 | // the above license grant, this restriction and the following disclaimer, |
---|
24 | // must be included in all copies of the Software, in whole or in part, and |
---|
25 | // all derivative works of the Software, unless such copies or derivative |
---|
26 | // works are solely in the form of machine-executable object code generated by |
---|
27 | // a source language processor. |
---|
28 | // |
---|
29 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
---|
30 | // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
---|
31 | // FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT |
---|
32 | // SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE |
---|
33 | // FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, |
---|
34 | // ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
---|
35 | // DEALINGS IN THE SOFTWARE. |
---|
36 | // |
---|
37 | |
---|
38 | |
---|
39 | #ifndef SAX_Locator_INCLUDED |
---|
40 | #define SAX_Locator_INCLUDED |
---|
41 | |
---|
42 | |
---|
43 | #include "Poco/XML/XML.h" |
---|
44 | #include "Poco/XML/XMLString.h" |
---|
45 | |
---|
46 | |
---|
47 | namespace Poco { |
---|
48 | namespace XML { |
---|
49 | |
---|
50 | |
---|
51 | class XML_API Locator |
---|
52 | /// Interface for associating a SAX event with a document location. |
---|
53 | /// |
---|
54 | /// If a SAX parser provides location information to the SAX application, it does so by |
---|
55 | /// implementing this interface and then passing an instance to the application using the |
---|
56 | /// content handler's setDocumentLocator method. The application can use the object to obtain |
---|
57 | /// the location of any other SAX event in the XML source document. |
---|
58 | /// |
---|
59 | /// Note that the results returned by the object will be valid only during the scope of each |
---|
60 | /// callback method: the application will receive unpredictable results if it attempts to use |
---|
61 | /// the locator at any other time, or after parsing completes. |
---|
62 | /// |
---|
63 | /// SAX parsers are not required to supply a locator, but they are very strongly encouraged to |
---|
64 | /// do so. If the parser supplies a locator, it must do so before reporting any other document |
---|
65 | /// events. If no locator has been set by the time the application receives the startDocument event, |
---|
66 | /// the application should assume that a locator is not available. |
---|
67 | { |
---|
68 | public: |
---|
69 | virtual XMLString getPublicId() const = 0; |
---|
70 | /// Return the public identifier for the current document event. |
---|
71 | /// |
---|
72 | /// The return value is the public identifier of the document entity or of the external |
---|
73 | /// parsed entity in which the markup triggering the event appears. |
---|
74 | |
---|
75 | virtual XMLString getSystemId() const = 0; |
---|
76 | /// Return the system identifier for the current document event. |
---|
77 | /// |
---|
78 | /// The return value is the system identifier of the document entity or of the external |
---|
79 | /// parsed entity in which the markup triggering the event appears. |
---|
80 | /// |
---|
81 | /// If the system identifier is a URL, the parser must resolve it fully before passing |
---|
82 | /// it to the application. For example, a file name must always be provided as a |
---|
83 | /// file:... URL, and other kinds of relative URI are also resolved against their bases. |
---|
84 | |
---|
85 | virtual int getLineNumber() const = 0; |
---|
86 | /// Return the line number where the current document event ends. |
---|
87 | /// Lines are delimited by line ends, which are defined in the XML specification. |
---|
88 | /// |
---|
89 | /// Warning: The return value from the method is intended only as an approximation for |
---|
90 | /// the sake of diagnostics; it is not intended to provide sufficient information to |
---|
91 | /// edit the character content of the original XML document. In some cases, these "line" |
---|
92 | /// numbers match what would be displayed as columns, and in others they may not match the |
---|
93 | /// source text due to internal entity expansion. |
---|
94 | /// |
---|
95 | /// The return value is an approximation of the line number in the document entity or external |
---|
96 | /// parsed entity where the markup triggering the event appears. |
---|
97 | /// |
---|
98 | /// If possible, the SAX driver should provide the line position of the first character after |
---|
99 | /// the text associated with the document event. The first line is line 1. |
---|
100 | |
---|
101 | virtual int getColumnNumber() const = 0; |
---|
102 | /// Return the column number where the current document event ends. |
---|
103 | /// This is one-based number of characters since the last line end. |
---|
104 | /// |
---|
105 | /// Warning: The return value from the method is intended only as an approximation |
---|
106 | /// for the sake of diagnostics; it is not intended to provide sufficient information |
---|
107 | /// to edit the character content of the original XML document. For example, when lines |
---|
108 | /// contain combining character sequences, wide characters, surrogate pairs, or bi-directional |
---|
109 | /// text, the value may not correspond to the column in a text editor's display. |
---|
110 | /// |
---|
111 | /// The return value is an approximation of the column number in the document entity or external |
---|
112 | /// parsed entity where the markup triggering the event appears. |
---|
113 | /// |
---|
114 | /// If possible, the SAX driver should provide the line position of the first character after |
---|
115 | /// the text associated with the document event. The first column in each line is column 1. |
---|
116 | |
---|
117 | protected: |
---|
118 | virtual ~Locator(); |
---|
119 | }; |
---|
120 | |
---|
121 | |
---|
122 | } } // namespace Poco::XML |
---|
123 | |
---|
124 | |
---|
125 | #endif // SAX_Locator_INCLUDED |
---|