ClickHouse/base/poco/XML/include/Poco/SAX/ContentHandler.h

//
// ContentHandler.h
//
// Library: XML
// Package: SAX
// Module:  SAX
//
// SAX2 ContentHandler Interface.
//
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
// and Contributors.
//
// SPDX-License-Identifier:	BSL-1.0
//


#ifndef SAX_ContentHandler_INCLUDED
#define SAX_ContentHandler_INCLUDED


#include "Poco/XML/XML.h"
#include "Poco/XML/XMLString.h"


namespace Poco
{
namespace XML
{


    class Locator;
    class Attributes;


    class XML_API ContentHandler
    /// Receive notification of the logical content of a document.
    ///
    /// This is the main interface that most SAX applications implement: if the
    /// application needs to be informed of basic parsing events, it implements
    /// this interface and registers an instance with the SAX parser using the setContentHandler
    /// method. The parser uses the instance to report basic document-related events
    /// like the start and end of elements and character data.
    ///
    /// The order of events in this interface is very important, and mirrors the
    /// order of information in the document itself. For example, all of an element's
    /// content (character data, processing instructions, and/or subelements) will
    /// appear, in order, between the startElement event and the corresponding endElement
    /// event.
    ///
    /// This interface is similar to the now-deprecated SAX 1.0 DocumentHandler
    /// interface, but it adds support for Namespaces and for reporting skipped
    /// entities (in non-validating XML processors).
    /// Receive notification of the logical content of a document.
    {
    public:
        virtual void setDocumentLocator(const Locator * loc) = 0;
        /// Receive an object for locating the origin of SAX document events.
        ///
        /// SAX parsers are strongly encouraged (though not absolutely required) to
        /// supply a locator: if it does so, it must supply the locator to the application
        /// by invoking this method before invoking any of the other methods in the
        /// ContentHandler interface.
        ///
        /// The locator allows the application to determine the end position of any
        /// document-related event, even if the parser is not reporting an error. Typically,
        /// the application will use this information for reporting its own errors (such
        /// as character content that does not match an application's business rules).
        /// The information returned by the locator is probably not sufficient for use
        /// with a search engine.
        ///
        /// Note that the locator will return correct information only during the invocation
        /// SAX event callbacks after startDocument returns and before endDocument is
        /// called. The application should not attempt to use it at any other time.

        virtual void startDocument() = 0;
        /// Receive notification of the beginning of a document.
        ///
        /// The SAX parser calls this function one time before calling all other
        /// functions of this class (except SetDocumentLocator).

        virtual void endDocument() = 0;
        /// Receive notification of the end of a document.
        ///
        /// The SAX parser will invoke this method only once, and it will be the last
        /// method invoked during the parse. The parser shall not invoke this method
        /// until it has either abandoned parsing (because of an unrecoverable error)
        /// or reached the end of input.

        virtual void startElement(const XMLString & uri, const XMLString & localName, const XMLString & qname, const Attributes & attrList)
            = 0;
        /// Receive notification of the beginning of an element.
        ///
        /// The Parser will invoke this method at the beginning of every element in
        /// the XML document; there will be a corresponding endElement event for every
        /// startElement event (even when the element is empty). All of the element's
        /// content will be reported, in order, before the corresponding endElement
        /// event.
        ///
        /// This event allows up to three name components for each element:
        ///    1. the Namespace URI;
        ///    2. the local name; and
        ///    3. the qualified (prefixed) name.
        ///
        /// Any or all of these may be provided, depending on the values of the http://xml.org/sax/features/namespaces
        /// and the http://xml.org/sax/features/namespace-prefixes properties:
        ///     * the Namespace URI and local name are required when the namespaces
        ///       property is true (the default), and are optional when the namespaces property
        ///       is false (if one is specified, both must be);
        ///     * the qualified name is required when the namespace-prefixes property
        ///       is true, and is optional when the namespace-prefixes property is false (the
        ///       default).
        ///
        /// Note that the attribute list provided will contain only attributes with
        /// explicit values (specified or defaulted): #IMPLIED attributes will be omitted.
        /// The attribute list will contain attributes used for Namespace declarations
        /// (xmlns* attributes) only if the http://xml.org/sax/features/namespace-prefixes
        /// property is true (it is false by default, and support for a true value is
        /// optional).
        ///
        /// Like characters(), attribute values may have characters that need more than
        /// one char value.

        virtual void endElement(const XMLString & uri, const XMLString & localName, const XMLString & qname) = 0;
        /// Receive notification of the end of an element.
        ///
        /// The SAX parser will invoke this method at the end of every element in the
        /// XML document; there will be a corresponding startElement event for every
        /// endElement event (even when the element is empty).
        ///
        /// For information on the names, see startElement.

        virtual void characters(const XMLChar ch[], int start, int length) = 0;
        /// Receive notification of character data.
        ///
        /// The Parser will call this method to report each chunk of character data.
        /// SAX parsers may return all contiguous character data in a single chunk,
        /// or they may split it into several chunks; however, all of the characters
        /// in any single event must come from the same external entity so that the
        /// Locator provides useful information.
        ///
        /// The application must not attempt to read from the array outside of the specified
        /// range.
        ///
        /// Individual characters may consist of more than one XMLChar value. There
        /// are three important cases where this happens, because characters can't be
        /// represented in just sixteen bits. In one case, characters are represented
        /// in a Surrogate Pair, using two special Unicode values. Such characters are
        /// in the so-called "Astral Planes", with a code point above U+FFFF. A second
        /// case involves composite characters, such as a base character combining with
        /// one or more accent characters. And most important, if XMLChar is a plain
        /// char, characters are encoded in UTF-8.
        ///
        /// Your code should not assume that algorithms using char-at-a-time idioms
        /// will be working in character units; in some cases they will split characters.
        /// This is relevant wherever XML permits arbitrary characters, such as attribute
        /// values, processing instruction data, and comments as well as in data reported
        /// from this method. It's also generally relevant whenever C++ code manipulates
        /// internationalized text; the issue isn't unique to XML.
        ///
        /// Note that some parsers will report whitespace in element content using the
        /// ignorableWhitespace method rather than this one (validating parsers must
        /// do so).

        virtual void ignorableWhitespace(const XMLChar ch[], int start, int length) = 0;
        /// Receive notification of ignorable whitespace in element content.
        ///
        /// Validating Parsers must use this method to report each chunk of whitespace
        /// in element content (see the W3C XML 1.0 recommendation, section 2.10): non-validating
        /// parsers may also use this method if they are capable of parsing and using
        /// content models.
        ///
        /// SAX parsers may return all contiguous whitespace in a single chunk, or they
        /// may split it into several chunks; however, all of the characters in any
        /// single event must come from the same external entity, so that the Locator
        /// provides useful information.
        ///
        /// The application must not attempt to read from the array outside of the specified
        /// range.

        virtual void processingInstruction(const XMLString & target, const XMLString & data) = 0;
        /// Receive notification of a processing instruction.
        ///
        /// The Parser will invoke this method once for each processing instruction
        /// found: note that processing instructions may occur before or after the main
        /// document element.
        ///
        /// A SAX parser must never report an XML declaration (XML 1.0, section 2.8)
        /// or a text declaration (XML 1.0, section 4.3.1) using this method.
        ///
        /// Like characters(), processing instruction data may have characters that
        /// need more than one char value.

        virtual void startPrefixMapping(const XMLString & prefix, const XMLString & uri) = 0;
        /// Begin the scope of a prefix-URI Namespace mapping.
        ///
        /// The information from this event is not necessary for normal Namespace processing:
        /// the SAX XML reader will automatically replace prefixes for element and attribute
        /// names when the http://xml.org/sax/features/namespaces feature is true (the
        /// default).
        ///
        /// There are cases, however, when applications need to use prefixes in character
        /// data or in attribute values, where they cannot safely be expanded automatically;
        /// the start/endPrefixMapping event supplies the information to the application
        /// to expand prefixes in those contexts itself, if necessary.
        ///
        /// Note that start/endPrefixMapping events are not guaranteed to be properly
        /// nested relative to each other: all startPrefixMapping events will occur
        /// immediately before the corresponding startElement event, and all endPrefixMapping
        /// events will occur immediately after the corresponding endElement event,
        /// but their order is not otherwise guaranteed.
        ///
        /// There should never be start/endPrefixMapping events for the "xml" prefix,
        /// since it is predeclared and immutable.

        virtual void endPrefixMapping(const XMLString & prefix) = 0;
        /// End the scope of a prefix-URI mapping.
        ///
        /// See startPrefixMapping for details. These events will always occur immediately
        /// after the corresponding endElement event, but the order of endPrefixMapping
        /// events is not otherwise guaranteed.

        virtual void skippedEntity(const XMLString & name) = 0;
        /// Receive notification of a skipped entity. This is not called for entity
        /// references within markup constructs such as element start tags or markup
        /// declarations. (The XML recommendation requires reporting skipped external
        /// entities. SAX also reports internal entity expansion/non-expansion, except
        /// within markup constructs.)
        ///
        /// The Parser will invoke this method each time the entity is skipped. Non-validating
        /// processors may skip entities if they have not seen the declarations (because,
        /// for example, the entity was declared in an external DTD subset). All processors
        /// may skip external entities, depending on the values of the http://xml.org/sax/features/external-general-entities
        /// and the http://xml.org/sax/features/external-parameter-entities properties.

    protected:
        virtual ~ContentHandler();
    };


}
} // namespace Poco::XML


#endif // SAX_ContentHandler_INCLUDED