XMLWriter

Writes XML to an output range of characters.

Note that default initialization, copying, and assignment are disabled for XMLWriter. This is because XMLWriter is essentially a reference type, but in many cases, it doesn't need to be passed around, and forcing it to be allocated on the heap in order to be a reference type seemed like an unnecessary heap allocation. So, it's a struct with default initialization, copying, and assignment disabled so that like a reference type, it will not be copied or overwritten. Code that needs to pass it around can pass it by $(K_REF) or use the $(LREF_ALTTEXT constructor, _XMLWriter.this) to explicitly allocate it on the heap and then pass around the resulting pointer.

The optional Newline and InsertIndent parameters to the various write functions are used to control the formatting of the XML, and writeIndent and _output can be used for additional control over the formatting.

The indent provided to the XMLWriter is the base indent that will be used whenever writeIndent and any write functions using Newline.yes or InsertIndent.yes are called - e.g. if the base indent is 4 spaces, $(LREF2 tagDepth, _XMLWriter) == 3, and Newline.yes is passed to writeComment, then a newline followed by 12 spaces will be written to the output range after the comment.

writeXMLDecl can be used to write the <?xml...?> declaration to the output range before constructing an XML writer, but if an application wishes to do anything with a DTD section, it will have to write that to the output range on its own before constructing the XMLWriter. XMLWriter expects to start writing XML after any <?xml...?> or <!DOCTYPE...> declarations.

The write functions check the arguments prior to writing anything to the output range, so the XMLWriter is not in an invalid state after an XMLWritingException is thrown, but it is in an invalid state if any other exception is thrown (which will only occur if an input range that is passed to a write function throws or if the ouput range throws when XMLWriter calls $(PHOBOS_REF_ALTTEXT put, put, std, range, primitives) on it).

Constructors

this this(): Undocumented in source.
this this(OR output, string baseIndent): In general, it's more user-friendly to use xmlWriter rather than calling the constructor directly, because then the type of the output range can be inferred. However, in the case where a pointer is desirable, then the constructor needs to be called instead of xmlWriter.

Postblit

this(this) this(this): Undocumented in source.

Members

Functions

_writeStartTag void _writeStartTag(string name, EmptyTag emptyTag, Newline newline): Undocumented in source. Be warned that the author may not have intended to support it.
closeStartTag void closeStartTag(EmptyTag emptyTag): Writes the end of a start tag to the ouput range.
opAssign void opAssign(XMLWriter ): Undocumented in source.
openStartTag void openStartTag(string name, Newline newline): Writes the first portion of a start tag to the given output range.
writeAttr void writeAttr(string name, R value, Newline newline): Writes an attribute for a start tag to the output range.
writeCDATA void writeCDATA(R text, Newline newline, InsertIndent insertIndent)
void writeCDATA(R text, InsertIndent insertIndent, Newline newline): Writes a <![CDATA[...]]> section with the given text between the brackets.
writeComment void writeComment(R text, Newline newline, InsertIndent insertIndent)
void writeComment(R text, InsertIndent insertIndent, Newline newline): Writes a comment to the output range.
writeEndTag void writeEndTag(string name, Newline newline)
void writeEndTag(Newline newline): Writes an end tag to the output range with the name of the start tag that was most recently written and does not yet have a matching end tag.
writeIndent void writeIndent(): Writes a newline followed by an indent to the output range.
writePI void writePI(R name, Newline newline)
void writePI(R1 name, R2 text, Newline newline, InsertIndent insertIndent)
void writePI(R1 name, R2 text, InsertIndent insertIndent, Newline newline): Writes a parsing instruction to the output range.
writeStartTag void writeStartTag(string name, EmptyTag emptyTag, Newline newline)
void writeStartTag(string name, Newline newline, EmptyTag emptyTag): Writes a start tag with no attributes.
writeText void writeText(R text, Newline newline, InsertIndent insertIndent)
void writeText(R text, InsertIndent insertIndent, Newline newline): This writes the text that goes between start tags and end tags.

Manifest constants

compileInTests enum compileInTests;: Undocumented in source.

Properties

baseIndent string baseIndent [@property getter]: The text that will be written for each level of the tag depth when an indent is written.
output ref output [@property getter]: Provides access to the output range that's used by XMLWriter.
tagDepth int tagDepth [@property getter]: The current depth of the tag stack.

Examples

import std.array : appender;
{
    auto writer = xmlWriter(appender!string());
    writer.writeStartTag("root");

    writer.openStartTag("foo");
    writer.writeAttr("a", "42");
    writer.closeStartTag();

    writer.writeText("bar");

    writer.writeEndTag("foo");

    writer.writeEndTag("root");

    assert(writer.output.data ==
           "\n" ~
           "<root>\n" ~
           `    <foo a="42">` ~ "\n" ~
           "        bar\n" ~
           "    </foo>\n" ~
           "</root>");
}

// Newline.no can be used to avoid inserting newlines.
{
    auto writer = xmlWriter(appender!string());

    // Unless writeXMLDecl was used, Newline.no is needed on the first
    // entity to avoid having the document start with a newline.
    writer.writeStartTag("root", Newline.no);

    writer.openStartTag("foo");
    writer.writeAttr("a", "42");
    writer.closeStartTag();

    writer.writeText("bar", Newline.no);

    writer.writeEndTag("foo", Newline.no);

    writer.writeEndTag("root");

    assert(writer.output.data ==
           "<root>\n" ~
           `    <foo a="42">bar</foo>` ~ "\n" ~
           "</root>");
}