# Poco::XML

# class XMLWriter

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
);

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. If pTextEncoding is null, the given encodingName is ignored and the default UTF-8 encoding is used.

## 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.

See also: Poco::XML::ContentHandler::endPrefixMapping()

### 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().

See also: Poco::XML::ContentHandler::ignorableWhitespace()

### 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.

See also: Poco::XML::ContentHandler::processingInstruction()

### 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.

See also: Poco::XML::ContentHandler::setDocumentLocator()

### 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.

See also: Poco::XML::ContentHandler::skippedEntity()

### 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.

See also: Poco::XML::ContentHandler::startDocument()

### 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.

1. If a qname, but no namespaceURI and localName are given, the qname is taken as element name.
2. 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.
3. If all three are given, and the namespace given in namespaceURI has not been declared, it is declared now. Otherwise, see 2.

See also: Poco::XML::ContentHandler::startElement()

### 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.

See also: Poco::XML::ContentHandler::startPrefixMapping()

### 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
);

See also: Poco::XML::DTDHandler::unparsedEntityDecl()

### 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;