File Information
Library: XML
Package: XML
Header: Poco/XML/XMLWriter.h
Description
This class serializes SAX2 ContentHandler, LexicalHandler and DTDHandler events back into a stream.
Various consistency checks are performed on the written data (i.e. there must be exactly one root element and every startElement() must have a matching endElement()).
The XMLWriter supports optional pretty-printing of the serialized XML. Note, however, that pretty-printing XML data alters the information set of the document being written, since in XML all whitespace is potentially relevant to an application.
The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes.
If the client does not provide namespace prefixes (either by specifying them as part of the qualified name given to startElement(), or by calling startPrefixMapping()), the XMLWriter automatically generates namespace prefixes in the form ns1, ns2, etc.
Inheritance
Direct Base Classes: ContentHandler, LexicalHandler, DTDHandler
All Base Classes: ContentHandler, DTDHandler, LexicalHandler
Member Summary
Member Functions: addAttributes, addNamespaceAttributes, characters, closeStartTag, comment, dataElement, declareAttributeNamespaces, declareNamespaces, depth, emptyElement, endCDATA, endDTD, endDocument, endElement, endEntity, endFragment, endPrefixMapping, getIndent, getNewLine, ignorableWhitespace, isNamespaceMapped, nameToString, notationDecl, prettyPrint, processingInstruction, rawCharacters, setDocumentLocator, setIndent, setNewLine, skippedEntity, startCDATA, startDTD, startDocument, startElement, startEntity, startFragment, startPrefixMapping, uniquePrefix, unparsedEntityDecl, writeAttributes, writeCanonicalStartElement, writeEndElement, writeIndent, writeMarkup, writeName, writeNewLine, writeStartElement, writeXML, writeXMLDeclaration
Inherited Functions: characters, comment, endCDATA, endDTD, endDocument, endElement, endEntity, endPrefixMapping, ignorableWhitespace, notationDecl, processingInstruction, setDocumentLocator, skippedEntity, startCDATA, startDTD, startDocument, startElement, startEntity, startPrefixMapping, unparsedEntityDecl
Types
AttributeMap
typedef std::map < XMLString, XMLString > AttributeMap;
CanonicalAttributeMap
typedef std::map < XMLString, std::pair < XMLString, XMLString >> CanonicalAttributeMap;
Enumerations
Options
CANONICAL = 0x00
Do not write an XML declaration (default).
CANONICAL_XML = 0x01
Enables basic support for Canonical XML:
- do not write an XML declaration
- do not use special empty element syntax
- set the New Line character to NEWLINE_LF
- write namespace declarations and attributes in canonical order
- use default namespace as much as possible
WRITE_XML_DECLARATION = 0x02
Write an XML declaration.
PRETTY_PRINT = 0x04
Pretty-print XML markup.
PRETTY_PRINT_ATTRIBUTES = 0x08
Write each attribute on a separate line. PRETTY_PRINT must be specified as well.
Constructors
XMLWriter
XMLWriter(
XMLByteOutputStream & str,
int options
);
Creates the XMLWriter and sets the specified options.
The resulting stream will be UTF-8 encoded.
XMLWriter
XMLWriter(
XMLByteOutputStream & str,
int options,
const std::string & encodingName,
Poco::TextEncoding & textEncoding
);
Creates the XMLWriter and sets the specified options.
The encoding is reflected in the XML declaration. The caller is responsible for that the given encodingName matches with the given textEncoding.
XMLWriter
XMLWriter(
XMLByteOutputStream & str,
int options,
const std::string & encodingName,
Poco::TextEncoding * pTextEncoding
);
Destructor
~XMLWriter
~XMLWriter();
Destroys the XMLWriter.
Member Functions
characters
void characters(
const XMLChar ch[],
int start,
int length
);
Writes XML character data. Quotes, ampersand's, less-than and greater-than signs are escaped, unless a CDATA section has been opened by calling startCDATA().
The characters must be encoded in UTF-8 (if XMLChar is char) or UTF-16 (if XMLChar is wchar_t).
See also: Poco::XML::ContentHandler::characters()
characters
void characters(
const XMLString & str
);
Writes XML character data. Quotes, ampersand's, less-than and greater-than signs are escaped, unless a CDATA section has been opened by calling startCDATA().
The characters must be encoded in UTF-8 (if XMLChar is char) or UTF-16 (if XMLChar is wchar_t).
comment
void comment(
const XMLChar ch[],
int start,
int length
);
Writes a comment.
See also: Poco::XML::LexicalHandler::comment()
dataElement
void dataElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const XMLString & data,
const XMLString & attr1 = XMLString (),
const XMLString & value1 = XMLString (),
const XMLString & attr2 = XMLString (),
const XMLString & value2 = XMLString (),
const XMLString & attr3 = XMLString (),
const XMLString & value3 = XMLString ()
);
Writes a data element in the form <name attr1="value1"...>data</name>.
depth
int depth() const;
Return the number of nested XML elements.
Will be -1 if no document or fragment has been started, 0 if the document or fragment has been started, 1 if the document element has been written and > 1 for every element nested within the document element.
emptyElement
void emptyElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname
);
Writes an empty XML element tag (<elem/>).
emptyElement
void emptyElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const Attributes & attributes
);
Writes an empty XML element tag with the given attributes (<elem attr1="value1"... />).
endCDATA
void endCDATA();
Writes the ]]> string that ends a CDATA section.
See also: Poco::XML::LexicalHandler::endCDATA()
endDTD
void endDTD();
Writes the closing characters of a DTD declaration.
See also: Poco::XML::LexicalHandler::endDTD()
endDocument
void endDocument();
Checks that all elements are closed and prints a final newline.
See also: Poco::XML::ContentHandler::endDocument()
endElement
void endElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname
);
Writes an XML end element tag.
Throws an exception if the name of doesn't match the one of the most recent startElement().
See also: Poco::XML::ContentHandler::endElement()
endEntity
void endEntity(
const XMLString & name
);
Does nothing.
See also: Poco::XML::LexicalHandler::endEntity()
endFragment
void endFragment();
Checks that all elements are closed and prints a final newline.
endPrefixMapping
void endPrefixMapping(
const XMLString & prefix
);
End the scope of a prefix-URI mapping.
getIndent
const std::string & getIndent() const;
Returns the string used for one indentation step.
getNewLine
const std::string & getNewLine() const;
Returns the line ending currently in use.
ignorableWhitespace
void ignorableWhitespace(
const XMLChar ch[],
int start,
int length
);
Writes whitespace characters by simply passing them to characters().
isNamespaceMapped
bool isNamespaceMapped(
const XMLString & namespc
) const;
Returns true if the given namespace has been mapped to a prefix in the current element or its ancestors.
notationDecl
void notationDecl(
const XMLString & name,
const XMLString * publicId,
const XMLString * systemId
);
See also: Poco::XML::DTDHandler::notationDecl()
processingInstruction
void processingInstruction(
const XMLString & target,
const XMLString & data
);
Writes a processing instruction.
rawCharacters
void rawCharacters(
const XMLString & str
);
Writes the characters in the given string as they are. The caller is responsible for escaping characters as necessary to produce valid XML.
The characters must be encoded in UTF-8 (if XMLChar is char) or UTF-16 (if XMLChar is wchar_t).
setDocumentLocator
void setDocumentLocator(
const Locator * loc
);
Currently unused.
setIndent
void setIndent(
const std::string & indent
);
Sets the string used for one indentation step.
The default is a single TAB character. The given string should only contain TAB or SPACE characters (e.g., a single TAB character, or two to four SPACE characters).
setNewLine
void setNewLine(
const std::string & newLineCharacters
);
Sets the line ending for the resulting XML file.
Possible values are:
- NEWLINE_DEFAULT (whatever is appropriate for the current platform)
- NEWLINE_CRLF (Windows),
- NEWLINE_LF (Unix),
- NEWLINE_CR (Macintosh)
skippedEntity
void skippedEntity(
const XMLString & name
);
Does nothing.
startCDATA
void startCDATA();
Writes the [CDATA[ string that begins a CDATA section. Use characters() to write the actual character data.
See also: Poco::XML::LexicalHandler::startCDATA()
startDTD
void startDTD(
const XMLString & name,
const XMLString & publicId,
const XMLString & systemId
);
Writes a DTD declaration.
See also: Poco::XML::LexicalHandler::startDTD()
startDocument
void startDocument();
Writes a generic XML declaration to the stream. If a document type has been set (see SetDocumentType), a DOCTYPE declaration is also written.
startElement
void startElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const Attributes & attributes
);
Writes an XML start element tag.
Namespaces are handled as follows.
- If a qname, but no namespaceURI and localName are given, the qname is taken as element name.
- If a namespaceURI and a localName, but no qname is given, and the given namespaceURI has been declared earlier, the namespace prefix for the given namespaceURI together with the localName is taken as element name. If the namespace has not been declared, a prefix in the form "ns1", "ns2", etc. is generated and the namespace is declared with the generated prefix.
- If all three are given, and the namespace given in namespaceURI has not been declared, it is declared now. Otherwise, see 2.
startElement
void startElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname
);
Writes an XML start element tag with no attributes. See the other startElement() method for more information.
startEntity
void startEntity(
const XMLString & name
);
Does nothing.
See also: Poco::XML::LexicalHandler::startEntity()
startFragment
void startFragment();
Use this instead of StartDocument() if you want to write a fragment rather than a document (no XML declaration and more than one "root" element allowed).
startPrefixMapping
void startPrefixMapping(
const XMLString & prefix,
const XMLString & namespaceURI
);
Begin the scope of a prefix-URI Namespace mapping. A namespace declaration is written with the next element.
uniquePrefix
XMLString uniquePrefix();
Creates and returns a unique namespace prefix that can be used with startPrefixMapping().
unparsedEntityDecl
void unparsedEntityDecl(
const XMLString & name,
const XMLString * publicId,
const XMLString & systemId,
const XMLString & notationName
);
addAttributes
void addAttributes(
AttributeMap & attributeMap,
const Attributes & attributes,
const XMLString & elementNamespaceURI
);
addAttributes
void addAttributes(
CanonicalAttributeMap & attributeMap,
const Attributes & attributes,
const XMLString & elementNamespaceURI
);
addNamespaceAttributes
void addNamespaceAttributes(
AttributeMap & attributeMap
);
addNamespaceAttributes
void addNamespaceAttributes(
CanonicalAttributeMap & attributeMap
);
closeStartTag
void closeStartTag();
declareAttributeNamespaces
void declareAttributeNamespaces(
const Attributes & attributes
);
declareNamespaces
void declareNamespaces(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const Attributes & attributes
);
nameToString
static std::string nameToString(
const XMLString & localName,
const XMLString & qname
);
prettyPrint
void prettyPrint() const;
writeAttributes
void writeAttributes(
const AttributeMap & attributeMap
);
writeAttributes
void writeAttributes(
const CanonicalAttributeMap & attributeMap
);
writeCanonicalStartElement
void writeCanonicalStartElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const Attributes & attributes
);
writeEndElement
void writeEndElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname
);
writeIndent
void writeIndent() const;
writeIndent
void writeIndent(
int indent
) const;
writeMarkup
void writeMarkup(
const std::string & str
) const;
writeName
void writeName(
const XMLString & prefix,
const XMLString & localName
);
writeNewLine
void writeNewLine() const;
writeStartElement
void writeStartElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const Attributes & attributes
);
writeXML
void writeXML(
const XMLString & str
) const;
writeXML
void writeXML(
XMLChar ch
) const;
writeXMLDeclaration
void writeXMLDeclaration();
Variables
NEWLINE_CR
static const std::string NEWLINE_CR;
NEWLINE_CRLF
static const std::string NEWLINE_CRLF;
NEWLINE_DEFAULT
static const std::string NEWLINE_DEFAULT;
NEWLINE_LF
static const std::string NEWLINE_LF;