1//
2// LexicalHandler.h
3//
4// Library: XML
5// Package: SAX
6// Module: SAX
7//
8// SAX2-ext LexicalHandler 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_LexicalHandler_INCLUDED
18#define SAX_LexicalHandler_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 LexicalHandler
30 /// This is an optional extension handler for SAX2 to provide lexical information
31 /// about an XML document, such as comments and CDATA section boundaries.
32 /// XML readers are not required to recognize this handler, and it is not part of
33 /// core-only SAX2 distributions.
34 ///
35 /// The events in the lexical handler apply to the entire document, not just to the
36 /// document element, and all lexical handler events must appear between the content
37 /// handler's startDocument and endDocument events.
38 ///
39 /// To set the LexicalHandler for an XML reader, use the setProperty method with the
40 /// property name http://xml.org/sax/properties/lexical-handler and an object implementing
41 /// this interface (or null) as the value. If the reader does not report lexical events,
42 /// it will throw a SAXNotRecognizedException when you attempt to register the handler.
43{
44public:
45 virtual void startDTD(const XMLString& name, const XMLString& publicId, const XMLString& systemId) = 0;
46 /// Report the start of DTD declarations, if any.
47 ///
48 /// This method is intended to report the beginning of the DOCTYPE declaration;
49 /// if the document has no DOCTYPE declaration, this method will not be invoked.
50 ///
51 /// All declarations reported through DTDHandler or DeclHandler events must appear
52 /// between the startDTD and endDTD events. Declarations are assumed to belong to
53 /// the internal DTD subset unless they appear between startEntity and endEntity
54 /// events. Comments and processing instructions from the DTD should also be reported
55 /// between the startDTD and endDTD events, in their original order of (logical) occurrence;
56 /// they are not required to appear in their correct locations relative to DTDHandler or
57 /// DeclHandler events, however.
58 ///
59 /// Note that the start/endDTD events will appear within the start/endDocument events from
60 /// ContentHandler and before the first startElement event.
61
62 virtual void endDTD() = 0;
63 /// Report the end of DTD declarations.
64 ///
65 /// This method is intended to report the end of the DOCTYPE declaration; if the document
66 /// has no DOCTYPE declaration, this method will not be invoked.
67
68 virtual void startEntity(const XMLString& name) = 0;
69 /// Report the beginning of some internal and external XML entities.
70 ///
71 /// The reporting of parameter entities (including the external DTD subset) is optional,
72 /// and SAX2 drivers that report LexicalHandler events may not implement it; you can use the
73 /// http://xml.org/sax/features/lexical-handler/parameter-entities feature to query or control
74 /// the reporting of parameter entities.
75 ///
76 /// General entities are reported with their regular names, parameter entities have '%'
77 /// prepended to their names, and the external DTD subset has the pseudo-entity name "[dtd]".
78 ///
79 /// When a SAX2 driver is providing these events, all other events must be properly nested
80 /// within start/end entity events. There is no additional requirement that events from
81 /// DeclHandler or DTDHandler be properly ordered.
82 ///
83 /// Note that skipped entities will be reported through the skippedEntity event, which is part of
84 /// the ContentHandler interface.
85 ///
86 /// Because of the streaming event model that SAX uses, some entity boundaries cannot be reported under
87 /// any circumstances:
88 ///
89 /// * general entities within attribute values
90 /// * parameter entities within declarations
91 ///
92 /// These will be silently expanded, with no indication of where the original entity boundaries were.
93 ///
94 /// Note also that the boundaries of character references (which are not really entities anyway) are not reported.
95 ///
96 /// All start/endEntity events must be properly nested.
97
98 virtual void endEntity(const XMLString& name) = 0;
99 /// Report the end of an entity.
100
101 virtual void startCDATA() = 0;
102 /// Report the start of a CDATA section.
103 ///
104 /// The contents of the CDATA section will be reported through the regular characters event;
105 /// this event is intended only to report the boundary.
106
107 virtual void endCDATA() = 0;
108 /// Report the end of a CDATA section.
109
110 virtual void comment(const XMLChar ch[], int start, int length) = 0;
111 /// Report an XML comment anywhere in the document.
112 ///
113 /// This callback will be used for comments inside or outside the document element,
114 /// including comments in the external DTD subset (if read). Comments in the DTD must
115 /// be properly nested inside start/endDTD and start/endEntity events (if used).
116
117protected:
118 virtual ~LexicalHandler();
119};
120
121
122} } // namespace Poco::XML
123
124
125#endif // SAX_LexicalHandler_INCLUDED
126