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)
  2. auto xmlWriter(OR output, string baseIndent = " ")
    xmlWriter
    (
    OR
    )
    (
    ,
    string baseIndent = " "
    )

Parameters

output
Type: OR

The _output range that the XML will be written to.

baseIndent
Type: string

Optional argument indicating the base indent to be used when an indent is inserted after a newline in the XML (with the actual indent being the base indent inserted once for each level of the tagDepth). The default is four spaces. baseIndent may only contain spaces and/or tabs.

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