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

  1. struct XMLWriter(OR)
    struct XMLWriter (
    OR
    ) if (
    isOutputRange!(OR, char)
    ) {
    enum compileInTests;
    bool _writtenRootEnd;
    }
  2. auto xmlWriter(OR output, string baseIndent = " ")

Disabled Default Constructor

A disabled default is present on this object. To use it, use one of the other constructors or a factory function.

Constructors

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

Copying this object is disabled.

A postblit is present on this object, but not explicitly documented in the source.

Members

Functions

closeStartTag
void closeStartTag(EmptyTag emptyTag = EmptyTag.no)

Writes the end of a start tag to the ouput range.

openStartTag
void openStartTag(string name, Newline newline = Newline.yes)

Writes the first portion of a start tag to the given output range.

writeAttr
void writeAttr(string name, R value, Newline newline = Newline.no)

Writes an attribute for a start tag to the output range.

writeCDATA
void writeCDATA(R text, Newline newline = Newline.yes, InsertIndent insertIndent = InsertIndent.yes)
void writeCDATA(R text, InsertIndent insertIndent, Newline newline = Newline.yes)

Writes a <![CDATA[...]]> section with the given text between the brackets.

writeComment
void writeComment(R text, Newline newline = Newline.yes, InsertIndent insertIndent = InsertIndent.yes)
void writeComment(R text, InsertIndent insertIndent, Newline newline = Newline.yes)

Writes a comment to the output range.

writeEndTag
void writeEndTag(string name, Newline newline = Newline.yes)
void writeEndTag(Newline newline = Newline.yes)

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 = Newline.yes)
void writePI(R1 name, R2 text, Newline newline = Newline.yes, InsertIndent insertIndent = InsertIndent.yes)
void writePI(R1 name, R2 text, InsertIndent insertIndent, Newline newline = Newline.yes)

Writes a parsing instruction to the output range.

writeStartTag
void writeStartTag(string name, EmptyTag emptyTag = EmptyTag.no, Newline newline = Newline.yes)
void writeStartTag(string name, Newline newline, EmptyTag emptyTag = EmptyTag.no)

Writes a start tag with no attributes.

writeText
void writeText(R text, Newline newline = Newline.yes, InsertIndent insertIndent = InsertIndent.yes)
void writeText(R text, InsertIndent insertIndent, Newline newline = Newline.yes)

This writes the text that goes between start tags and end tags.

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

1 import std.array : appender;
2 {
3     auto writer = xmlWriter(appender!string());
4     writer.writeStartTag("root");
5 
6     writer.openStartTag("foo");
7     writer.writeAttr("a", "42");
8     writer.closeStartTag();
9 
10     writer.writeText("bar");
11 
12     writer.writeEndTag("foo");
13 
14     writer.writeEndTag("root");
15 
16     assert(writer.output.data ==
17            "\n" ~
18            "<root>\n" ~
19            `    <foo a="42">` ~ "\n" ~
20            "        bar\n" ~
21            "    </foo>\n" ~
22            "</root>");
23 }
24 
25 // Newline.no can be used to avoid inserting newlines.
26 {
27     auto writer = xmlWriter(appender!string());
28 
29     // Unless writeXMLDecl was used, Newline.no is needed on the first
30     // entity to avoid having the document start with a newline.
31     writer.writeStartTag("root", Newline.no);
32 
33     writer.openStartTag("foo");
34     writer.writeAttr("a", "42");
35     writer.closeStartTag();
36 
37     writer.writeText("bar", Newline.no);
38 
39     writer.writeEndTag("foo", Newline.no);
40 
41     writer.writeEndTag("root");
42 
43     assert(writer.output.data ==
44            "<root>\n" ~
45            `    <foo a="42">bar</foo>` ~ "\n" ~
46            "</root>");
47 }

See Also

Meta