1//
2// Locator.h
3//
4// Library: XML
5// Package: SAX
6// Module: SAX
7//
8// SAX Locator Interface.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef SAX_Locator_INCLUDED
18#define SAX_Locator_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/XML/XMLString.h"
23
24
25namespace Poco {
26namespace XML {
27
28
29class XML_API Locator
30 /// Interface for associating a SAX event with a document location.
31 ///
32 /// If a SAX parser provides location information to the SAX application, it does so by
33 /// implementing this interface and then passing an instance to the application using the
34 /// content handler's setDocumentLocator method. The application can use the object to obtain
35 /// the location of any other SAX event in the XML source document.
36 ///
37 /// Note that the results returned by the object will be valid only during the scope of each
38 /// callback method: the application will receive unpredictable results if it attempts to use
39 /// the locator at any other time, or after parsing completes.
40 ///
41 /// SAX parsers are not required to supply a locator, but they are very strongly encouraged to
42 /// do so. If the parser supplies a locator, it must do so before reporting any other document
43 /// events. If no locator has been set by the time the application receives the startDocument event,
44 /// the application should assume that a locator is not available.
45{
46public:
47 virtual XMLString getPublicId() const = 0;
48 /// Return the public identifier for the current document event.
49 ///
50 /// The return value is the public identifier of the document entity or of the external
51 /// parsed entity in which the markup triggering the event appears.
52
53 virtual XMLString getSystemId() const = 0;
54 /// Return the system identifier for the current document event.
55 ///
56 /// The return value is the system identifier of the document entity or of the external
57 /// parsed entity in which the markup triggering the event appears.
58 ///
59 /// If the system identifier is a URL, the parser must resolve it fully before passing
60 /// it to the application. For example, a file name must always be provided as a
61 /// file:... URL, and other kinds of relative URI are also resolved against their bases.
62
63 virtual int getLineNumber() const = 0;
64 /// Return the line number where the current document event ends.
65 /// Lines are delimited by line ends, which are defined in the XML specification.
66 ///
67 /// Warning: The return value from the method is intended only as an approximation for
68 /// the sake of diagnostics; it is not intended to provide sufficient information to
69 /// edit the character content of the original XML document. In some cases, these "line"
70 /// numbers match what would be displayed as columns, and in others they may not match the
71 /// source text due to internal entity expansion.
72 ///
73 /// The return value is an approximation of the line number in the document entity or external
74 /// parsed entity where the markup triggering the event appears.
75 ///
76 /// If possible, the SAX driver should provide the line position of the first character after
77 /// the text associated with the document event. The first line is line 1.
78
79 virtual int getColumnNumber() const = 0;
80 /// Return the column number where the current document event ends.
81 /// This is one-based number of characters since the last line end.
82 ///
83 /// Warning: The return value from the method is intended only as an approximation
84 /// for the sake of diagnostics; it is not intended to provide sufficient information
85 /// to edit the character content of the original XML document. For example, when lines
86 /// contain combining character sequences, wide characters, surrogate pairs, or bi-directional
87 /// text, the value may not correspond to the column in a text editor's display.
88 ///
89 /// The return value is an approximation of the column number in the document entity or external
90 /// parsed entity where the markup triggering the event appears.
91 ///
92 /// If possible, the SAX driver should provide the line position of the first character after
93 /// the text associated with the document event. The first column in each line is column 1.
94
95protected:
96 virtual ~Locator();
97};
98
99
100} } // namespace Poco::XML
101
102
103#endif // SAX_Locator_INCLUDED
104