dxml.parser

auto xml = "<!-- comment -->\n" ~
           "<root>\n" ~
           "    <foo>some text<whatever/></foo>\n" ~
           "    <bar/>\n" ~
           "    <baz></baz>\n" ~
           "</root>";
{
    auto range = parseXML(xml);
    assert(range.front.type == EntityType.comment);
    assert(range.front.text == " comment ");
    range.popFront();

    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "root");
    range.popFront();

    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "foo");
    range.popFront();

    assert(range.front.type == EntityType.text);
    assert(range.front.text == "some text");
    range.popFront();

    assert(range.front.type == EntityType.elementEmpty);
    assert(range.front.name == "whatever");
    range.popFront();

    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "foo");
    range.popFront();

    assert(range.front.type == EntityType.elementEmpty);
    assert(range.front.name == "bar");
    range.popFront();

    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "baz");
    range.popFront();

    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "baz");
    range.popFront();

    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "root");
    range.popFront();

    assert(range.empty);
}
{
    auto range = parseXML!simpleXML(xml);

    // simpleXML skips comments

    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "root");
    range.popFront();

    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "foo");
    range.popFront();

    assert(range.front.type == EntityType.text);
    assert(range.front.text == "some text");
    range.popFront();

    // simpleXML splits empty element tags into a start tag and end tag
    // so that the code doesn't have to care whether a start tag with no
    // content is an empty tag or a start tag and end tag with nothing but
    // whitespace in between.
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "whatever");
    range.popFront();

    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "whatever");
    range.popFront();

    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "foo");
    range.popFront();

    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "bar");
    range.popFront();

    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "bar");
    range.popFront();

    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "baz");
    range.popFront();

    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "baz");
    range.popFront();

    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "root");
    range.popFront();

    assert(range.empty);
}

class XMLParsingException: object.Exception;

The exception type thrown when the XML parser encounters invalid XML.

TextPos pos;

The position in the XML input where the problem is.

struct TextPos;

Where in the XML document an entity is.

The line and column numbers are 1-based.

The primary use case for TextPos is XMLParsingException, but an application may have other uses for it. The TextPos for an Entity can be obtained from Entity.pos.

See Also: XMLParsingException.pos
EntityRange.Entity.pos

int line;

A line number in the XML file.

int col;

A column number in a line of the XML file.

Each code unit is considered a column, so depending on what a program is looking to do with the column number, it may need to examine the actual text on that line and calculate the number that represents what the program wants to display (e.g. the number of graphemes).

struct Config;

Used to configure how the parser works.

See Also: makeConfig
parseXML
simpleXML

Flag skipComments;

Whether the comments should be skipped while parsing.

If skipComments == SkipComments.yes, any entities of type EntityType.comment will be omitted from the parsing results, and they will not be validated beyond what is required to parse past them.

Defaults to SkipComments.no.

Flag skipPI;

Whether processing instructions should be skipped.

If skipPI == SkipPI.yes, any entities of type EntityType.pi will be skipped, and they will not be validated beyond what is required to parse past them.

Defaults to SkipPI.no.

Flag splitEmpty;

Whether the parser should report empty element tags as if they were a start tag followed by an end tag with nothing in between.

If splitEmpty == SplitEmpty.yes, then whenever an EntityType.elementEmpty is encountered, the parser will claim that that entity is an EntityType.elementStart, and then it will provide an EntityType.elementEnd as the next entity before the entity that actually follows it.

The purpose of this is to simplify the code using the parser, since most code does not care about the difference between an empty tag and a start and end tag with nothing in between. But since some code may care about the difference, the behavior is configurable.

Defaults to SplitEmpty.no.

Examples:

enum configSplitYes = makeConfig(SplitEmpty.yes);

{
    auto range = parseXML("<root></root>");
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "root");
    range.popFront();
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "root");
    range.popFront();
    assert(range.empty);
}
{
    // No difference if the tags are already split.
    auto range = parseXML!configSplitYes("<root></root>");
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "root");
    range.popFront();
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "root");
    range.popFront();
    assert(range.empty);
}
{
    // This treats <root></root> and <root/> as distinct.
    auto range = parseXML("<root/>");
    assert(range.front.type == EntityType.elementEmpty);
    assert(range.front.name == "root");
    range.popFront();
    assert(range.empty);
}
{
    // This is parsed as if it were <root></root> insead of <root/>.
    auto range = parseXML!configSplitYes("<root/>");
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "root");
    range.popFront();
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "root");
    range.popFront();
    assert(range.empty);
}

alias SkipComments = std.typecons.Flag!"SkipComments".Flag;

See Also: skipComments

alias SkipPI = std.typecons.Flag!"SkipPI".Flag;

See Also: skipPI

alias SplitEmpty = std.typecons.Flag!"SplitEmpty".Flag;

See Also: splitEmpty

Config makeConfig(Args...)(Args args);

Helper function for creating a custom config. It makes it easy to set one or more of the member variables to something other than the default without having to worry about explicitly setting them individually or setting them all at once via a constructor.

The order of the arguments does not matter. The types of each of the members of Config are unique, so that information alone is sufficient to determine which argument should be assigned to which member.

Examples:

{
    auto config = makeConfig(SkipComments.yes);
    assert(config.skipComments == SkipComments.yes);
    assert(config.skipPI == Config.init.skipPI);
    assert(config.splitEmpty == Config.init.splitEmpty);
}
{
    auto config = makeConfig(SkipComments.yes, SkipPI.yes);
    assert(config.skipComments == SkipComments.yes);
    assert(config.skipPI == SkipPI.yes);
    assert(config.splitEmpty == Config.init.splitEmpty);
}
{
    auto config = makeConfig(SplitEmpty.yes, SkipComments.yes);
    assert(config.skipComments == SkipComments.yes);
    assert(config.skipPI == Config.init.skipPI);
    assert(config.splitEmpty == SplitEmpty.yes);
}

enum Config simpleXML;

This Config is intended for making it easy to parse XML by skipping everything that isn't the actual data as well as making it simpler to deal with empty element tags by treating them the same as a start tag and end tag with nothing but whitespace between them.

Examples:

static assert(simpleXML.skipComments == SkipComments.yes);
static assert(simpleXML.skipPI == SkipPI.yes);
static assert(simpleXML.splitEmpty == SplitEmpty.yes);

enum EntityType: int;

Represents the type of an XML entity. Used by EntityRange.Entity.

cdata

A cdata section: <![CDATA[ ... ]]>.

See Also: http://www.w3.org/TR/REC-xml/#sec-cdata-sect

comment

An XML comment: <!-- ... -->.

See Also: http://www.w3.org/TR/REC-xml/#sec-comments

elementStart

The start tag for an element. e.g. <foo name="value">.

See Also: http://www.w3.org/TR/REC-xml/#sec-starttags

elementEnd

The end tag for an element. e.g. </foo>.

See Also: http://www.w3.org/TR/REC-xml/#sec-starttags

elementEmpty

The tag for an element with no contents or matching end tag. e.g. <foo name="value"/>.

See Also: http://www.w3.org/TR/REC-xml/#sec-starttags

pi

A processing instruction such as <?foo?>. Note that the <?xml ... ?> is skipped and not treated as an EntityType.pi.

See Also: http://www.w3.org/TR/REC-xml/#sec-pi

text

The content of an element tag that is simple text.

If there is an entity other than the end tag following the text, then the text includes up to that entity.

Note however that character references (e.g. "&#42") and the predefined entity references (e.g. "&apos;") are left unprocessed in the text. In order for them to be processed, the text should be passed to either normalize or asNormalized . Entity references which are not predefined are considered invalid XML, because the DTD section is skipped, and thus they cannot be processed properly.

See Also: http://www.w3.org/TR/REC-xml/#sec-starttags
dxml.util.normalize
dxml.util.asNormalized
dxml.util.parseStdEntityRef
dxml.util.parseCharRef
EntityRange.Entity.text

struct EntityRange(Config cfg, R) if (isForwardRange!R && isSomeChar!(ElementType!R));

EntityRange!(config, R) parseXML(Config config = Config.init, R)(R xmlText)
if(isForwardRange!R && isSomeChar!(ElementType!R));

Lazily parses the given range of characters as an XML document.

EntityRange is essentially a StAX parser, though it evolved into that rather than being based on what Java did, and it's range-based rather than iterator-based, so its API is likely to differ from other implementations. The basic concept should be the same though.

One of the core design goals of this parser is to slice the original input rather than having to allocate strings for the output or wrap it in a lazy range that produces a mutated version of the data. So, all of the text that the parser provides is either a slice or std.range.takeExactly of the input. However, in some cases, for the parser to be fully compliant with the XML spec, dxml.util.normalize must be called on the text to mutate certain constructs (e.g. removing any '\r' in the text or converting "&lt;" to '<'). But that's left up to the application.

The parser is not @nogc, but it allocates memory very minimally. It allocates some of its state on the heap so it can validate attributes and end tags. However, that state is shared among all the ranges that came from the same call to parseXML (only the range farthest along in parsing validates attributes or end tags), so save does not allocate memory unless save on the underlying range allocates memory. The shared state currently uses a couple of dynamic arrays to validate the tags and attributes, and if the document has a particularly deep tag-depth or has a lot of attributes on on a start tag, then some reallocations may occur until the maximum is reached, but enough is reserved that for most documents, no reallocations will occur. The only other times that the parser would allocate would be if an exception were thrown or if the range that is passed to parseXML allocates for any reason when calling any of the range primitives.

If invalid XML is encountered at any point during the parsing process, an XMLParsingException will be thrown. If an exception has been thrown, then the parser is in an invalid state, and it is an error to call any functions on it.

However, note that XML validation is reduced for any entities that are skipped (e.g. for anything in the DTD section, validation is reduced to what is required to correctly parse past it, and when Config.skipPI == SkipPI.yes, processing instructions are only validated enough to correctly skip past them).

As the module documentation says, this parser does not provide any DTD support. It's not possible to properly support the DTD section while returning slices of the original input, and the DTD portion of the spec makes parsing XML far, far more complicated.

A quick note about carriage returns: per the XML spec, they're all supposed to either be stripped out or replaced with newlines before the XML parser even processes the text. That doesn't work when the parser is slicing the original text and not mutating it at all. So, for the purposes of parsing, this parser treats all carriage returns as if they were newlines or spaces (though they won't count as newlines when counting the lines for TextPos). However, they will appear in any text fields or attribute values if they are in the document (since the text fields and attribute values are slices of the original text). dxml.util.normalize can be used to strip them along with converting any character references in the text. Alternatively, the application can remove them all before calling parseXML, but it's not necessary.

Examples:

auto xml = "<?xml version='1.0'?>\n" ~
           "<?instruction start?>\n" ~
           "<foo attr='42'>\n" ~
           "    <bar/>\n" ~
           "    <!-- no comment -->\n" ~
           "    <baz hello='world'>\n" ~
           "    nothing to say.\n" ~
           "    nothing at all...\n" ~
           "    </baz>\n" ~
           "</foo>\n" ~
           "<?some foo?>";

{
    auto range = parseXML(xml);
    assert(range.front.type == EntityType.pi);
    assert(range.front.name == "instruction");
    assert(range.front.text == "start");

    range.popFront();
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "foo");

    {
        auto attrs = range.front.attributes;
        assert(walkLength(attrs.save) == 1);
        assert(attrs.front.name == "attr");
        assert(attrs.front.value == "42");
    }

    range.popFront();
    assert(range.front.type == EntityType.elementEmpty);
    assert(range.front.name == "bar");

    range.popFront();
    assert(range.front.type == EntityType.comment);
    assert(range.front.text == " no comment ");

    range.popFront();
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "baz");

    {
        auto attrs = range.front.attributes;
        assert(walkLength(attrs.save) == 1);
        assert(attrs.front.name == "hello");
        assert(attrs.front.value == "world");
    }

    range.popFront();
    assert(range.front.type == EntityType.text);
    assert(range.front.text ==
           "\n    nothing to say.\n    nothing at all...\n    ");

    range.popFront();
    assert(range.front.type == EntityType.elementEnd); // </baz>
    range.popFront();
    assert(range.front.type == EntityType.elementEnd); // </foo>

    range.popFront();
    assert(range.front.type == EntityType.pi);
    assert(range.front.name == "some");
    assert(range.front.text == "foo");

    range.popFront();
    assert(range.empty);
}
{
    auto range = parseXML!simpleXML(xml);

    // simpleXML is set to skip processing instructions.

    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "foo");

    {
        auto attrs = range.front.attributes;
        assert(walkLength(attrs.save) == 1);
        assert(attrs.front.name == "attr");
        assert(attrs.front.value == "42");
    }

    // simpleXML is set to split empty tags so that <bar/> is treated
    // as the same as <bar></bar> so that code does not have to
    // explicitly handle empty tags.
    range.popFront();
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "bar");
    range.popFront();
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "bar");

    // simpleXML is set to skip comments.

    range.popFront();
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "baz");

    {
        auto attrs = range.front.attributes;
        assert(walkLength(attrs.save) == 1);
        assert(attrs.front.name == "hello");
        assert(attrs.front.value == "world");
    }

    range.popFront();
    assert(range.front.type == EntityType.text);
    assert(range.front.text ==
           "\n    nothing to say.\n    nothing at all...\n    ");

    range.popFront();
    assert(range.front.type == EntityType.elementEnd); // </baz>
    range.popFront();
    assert(range.front.type == EntityType.elementEnd); // </foo>
    range.popFront();
    assert(range.empty);
}

alias config = cfg;

The Config used for when parsing the XML.

alias Input = R;

The type of the range that EntityRange is parsing.

alias SliceOfR = R;

The type used when any slice of the original input is used. If R is a string or supports slicing, then SliceOfR is the same as R; otherwise, it's the result of calling std.range.takeExactly on the input.

import std.algorithm : filter;
import std.range : takeExactly;

static assert(is(EntityRange!(Config.init, string).SliceOfR == string));

auto range = filter!(a => true)("some xml");

static assert(is(EntityRange!(Config.init, typeof(range)).SliceOfR ==
                 typeof(takeExactly(range, 42))));

struct Entity;

Represents an entity in the XML document.

Note that the type determines which properties can be used, and it can determine whether functions which an Entity or EntityRange is passed to are allowed to be called. Each function lists which EntityTypes are allowed, and it is an error to call them with any other EntityType.

const pure nothrow @nogc @property @safe EntityType type();

The EntityType for this Entity.

Examples:

auto xml = "<root>\n" ~
           "    <!--no comment-->\n" ~
           "    <![CDATA[cdata run]]>\n" ~
           "    <text>I am text!</text>\n" ~
           "    <empty/>\n" ~
           "    <?pi?>\n" ~
           "</root>";

auto range = parseXML(xml);
assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "root");
range.popFront();

assert(range.front.type == EntityType.comment);
assert(range.front.text == "no comment");
range.popFront();

assert(range.front.type == EntityType.cdata);
assert(range.front.text == "cdata run");
range.popFront();

assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "text");
range.popFront();

assert(range.front.type == EntityType.text);
assert(range.front.text == "I am text!");
range.popFront();

assert(range.front.type == EntityType.elementEnd);
assert(range.front.name == "text");
range.popFront();

assert(range.front.type == EntityType.elementEmpty);
assert(range.front.name == "empty");
range.popFront();

assert(range.front.type == EntityType.pi);
assert(range.front.name == "pi");
range.popFront();

assert(range.front.type == EntityType.elementEnd);
assert(range.front.name == "root");
range.popFront();

assert(range.empty);

const pure nothrow @nogc @property @safe TextPos pos();

The position in the the original text where the entity starts.

See Also: TextPos
XMLParsingException.pos

Examples:

auto xml = "<root>\n" ~
           "    <foo>\n" ~
           "        Foo and bar. Always foo and bar...\n" ~
           "    </foo>\n" ~
           "</root>";

auto range = parseXML(xml);
assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "root");
assert(range.front.pos == TextPos(1, 1));
range.popFront();

assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "foo");
assert(range.front.pos == TextPos(2, 5));
range.popFront();

assert(range.front.type == EntityType.text);
assert(range.front.text ==
       "\n" ~
       "        Foo and bar. Always foo and bar...\n" ~
       "    ");
assert(range.front.pos == TextPos(2, 10));
range.popFront();

assert(range.front.type == EntityType.elementEnd);
assert(range.front.name == "foo");
assert(range.front.pos == TextPos(4, 5));
range.popFront();

assert(range.front.type == EntityType.elementEnd);
assert(range.front.name == "root");
assert(range.front.pos == TextPos(5, 1));
range.popFront();

assert(range.empty);

@property SliceOfR name();

Gives the name of this Entity.

Note that this is the direct name in the XML for this entity and does not contain any of the names of any of the parent entities that this entity has. If an application wants the full "path" of the entity, then it will have to keep track of that itself. The parser does not do that as it would require allocating memory.

Supported EntityTypes:
elementStart
elementEnd
elementEmpty
pi

Examples:

auto xml = "<root>\n" ~
           "    <empty/>\n" ~
           "    <?pi?>\n" ~
           "</root>";

auto range = parseXML(xml);
assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "root");
range.popFront();

assert(range.front.type == EntityType.elementEmpty);
assert(range.front.name == "empty");
range.popFront();

assert(range.front.type == EntityType.pi);
assert(range.front.name == "pi");
range.popFront();

assert(range.front.type == EntityType.elementEnd);
assert(range.front.name == "root");
range.popFront();

assert(range.empty);

@property auto attributes();

Returns a lazy range of attributes for a start tag where each attribute is represented as a
Tuple!( SliceOfR, "name", SliceOfR, "value", TextPos, "pos").

Supported EntityTypes:
elementStart
elementEmpty

See Also: dxml.util.normalize
dxml.util.asNormalized

Examples:

import std.algorithm.comparison : equal;
import std.algorithm.iteration : filter;
{
    auto xml = "<root/>";
    auto range = parseXML(xml);
    assert(range.front.type == EntityType.elementEmpty);
    assert(range.front.attributes.empty);
}
{
    auto xml = "<root a='42' q='29' w='hello'/>";
    auto range = parseXML(xml);
    assert(range.front.type == EntityType.elementEmpty);

    auto attrs = range.front.attributes;
    assert(attrs.front.name == "a");
    assert(attrs.front.value == "42");
    assert(attrs.front.pos == TextPos(1, 7));
    attrs.popFront();

    assert(attrs.front.name == "q");
    assert(attrs.front.value == "29");
    assert(attrs.front.pos == TextPos(1, 14));
    attrs.popFront();

    assert(attrs.front.name == "w");
    assert(attrs.front.value == "hello");
    assert(attrs.front.pos == TextPos(1, 21));
    attrs.popFront();

    assert(attrs.empty);
}
// Because the type of name and value is SliceOfR, == with a string
// only works if the range passed to parseXML was string.
{
    auto xml = filter!(a => true)("<root a='42' q='29' w='hello'/>");
    auto range = parseXML(xml);
    assert(range.front.type == EntityType.elementEmpty);

    auto attrs = range.front.attributes;
    assert(equal(attrs.front.name, "a"));
    assert(equal(attrs.front.value, "42"));
    assert(attrs.front.pos == TextPos(1, 7));
    attrs.popFront();

    assert(equal(attrs.front.name, "q"));
    assert(equal(attrs.front.value, "29"));
    assert(attrs.front.pos == TextPos(1, 14));
    attrs.popFront();

    assert(equal(attrs.front.name, "w"));
    assert(equal(attrs.front.value, "hello"));
    assert(attrs.front.pos == TextPos(1, 21));
    attrs.popFront();

    assert(attrs.empty);
}

@property SliceOfR text();

Returns the textual value of this Entity.

In the case of EntityType.pi, this is the text that follows the name, whereas in the other cases, the text is the entire contents of the entity (save for the delimeters on the ends if that entity has them).

Supported EntityTypes:
cdata
comment
pi
text

See Also: dxml.util.normalize
dxml.util.asNormalized
dxml.util.stripIndent
dxml.util.withoutIndent

Examples:

auto xml = "<?xml version='1.0'?>\n" ~
           "<?instructionName?>\n" ~
           "<?foo here is something to say?>\n" ~
           "<root>\n" ~
           "    <![CDATA[ Yay! random text >> << ]]>\n" ~
           "    <!-- some random comment -->\n" ~
           "    <p>something here</p>\n" ~
           "    <p>\n" ~
           "       something else\n" ~
           "       here</p>\n" ~
           "</root>";
auto range = parseXML(xml);

// "<?instructionName?>\n" ~
assert(range.front.type == EntityType.pi);
assert(range.front.name == "instructionName");
assert(range.front.text.empty);

// "<?foo here is something to say?>\n" ~
range.popFront();
assert(range.front.type == EntityType.pi);
assert(range.front.name == "foo");
assert(range.front.text == "here is something to say");

// "<root>\n" ~
range.popFront();
assert(range.front.type == EntityType.elementStart);

// "    <![CDATA[ Yay! random text >> << ]]>\n" ~
range.popFront();
assert(range.front.type == EntityType.cdata);
assert(range.front.text == " Yay! random text >> << ");

// "    <!-- some random comment -->\n" ~
range.popFront();
assert(range.front.type == EntityType.comment);
assert(range.front.text == " some random comment ");

// "    <p>something here</p>\n" ~
range.popFront();
assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "p");

range.popFront();
assert(range.front.type == EntityType.text);
assert(range.front.text == "something here");

range.popFront();
assert(range.front.type == EntityType.elementEnd);
assert(range.front.name == "p");

// "    <p>\n" ~
// "       something else\n" ~
// "       here</p>\n" ~
range.popFront();
assert(range.front.type == EntityType.elementStart);

range.popFront();
assert(range.front.type == EntityType.text);
assert(range.front.text == "\n       something else\n       here");

range.popFront();
assert(range.front.type == EntityType.elementEnd);

// "</root>"
range.popFront();
assert(range.front.type == EntityType.elementEnd);

range.popFront();
assert(range.empty);

@property Entity front();

Returns the Entity representing the entity in the XML document which was most recently parsed.

void popFront();

Move to the next entity.

The next entity is the next one that is linearly in the XML document. So, if the current entity has child entities, the next entity will be the first child entity, whereas if it has no child entities, it will be the next entity at the same level.

Throws: XMLParsingException on invalid XML.

const pure nothrow @nogc @property @safe bool empty();

Whether the end of the XML document has been reached.

Note that because an XMLParsingException will be thrown an invalid XML, it's actually possible to call front and popFront without checking empty if the only way that empty would be true is if the XML were invalid (e.g. if at a start tag, it's a given that there's at least one end tag left in the document unless it's invalid XML).

However, of course, caution should be used to ensure that incorrect assumptions are not made that allow the document to reach its end earlier than predicted without throwing an XMLParsingException, since it's still an error to call front or popFront if empty would return false.

@property auto save();

Forward range function for obtaining a copy of the range which can then be iterated independently of the original.

EntityRange takeNone();

Returns an empty range. This corresponds to std.range.takeNone except that it doesn't create a wrapper type.

R skipContents(R)(R entityRange)
if(isInstanceOf!(EntityRange, R));

Takes an EntityRange which is at a start tag and iterates it until it is at its corresponding end tag. It is an error to call skipContents when the current entity is not EntityType.elementStart.

Supported EntityTypes:
elementStart

Returns: The range with its front now at the end tag corresponding to the start tag that was front when the function was called.

Throws: XMLParsingException on invalid XML.

Examples:

auto xml = "<root>\n" ~
           "    <foo>\n" ~
           "        <bar>\n" ~
           "        Some text\n" ~
           "        </bar>\n" ~
           "    </foo>\n" ~
           "    <!-- no comment -->\n" ~
           "</root>";

auto range = parseXML(xml);
assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "root");

range.popFront();
assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "foo");

range = range.skipContents();
assert(range.front.type == EntityType.elementEnd);
assert(range.front.name == "foo");

range.popFront();
assert(range.front.type == EntityType.comment);
assert(range.front.text == " no comment ");

range.popFront();
assert(range.front.type == EntityType.elementEnd);
assert(range.front.name == "root");

range.popFront();
assert(range.empty);

R skipToEntityType(R)(R entityRange, EntityType[] entityTypes...)
if(isInstanceOf!(EntityRange, R));

Skips entities until the given EntityType is reached.

If multiple EntityTypes are given, then any one of them counts as a match.

The current entity is skipped regardless of whether it is the given EntityType.

This is essentially a slightly optimized equivalent to

if(!range.empty())
{
    range.popFront();
    range = range.find!((a, b) => a.type == b.type)(entityTypes);
}

Returns: The given range with its front now at the first entity which matched one of the given EntityTypes or an empty range if none were found.

Throws: XMLParsingException on invalid XML.

Examples:

auto xml = "<root>\n" ~
           "    <!-- blah blah blah -->\n" ~
           "    <foo>nothing to say</foo>\n" ~
           "</root>";

auto range = parseXML(xml);
assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "root");

range = range.skipToEntityType(EntityType.elementStart,
                               EntityType.elementEmpty);
assert(range.front.type == EntityType.elementStart);
assert(range.front.name == "foo");

assert(range.skipToEntityType(EntityType.comment).empty);

// skipToEntityType will work on an empty range but will always
// return an empty range.
assert(range.takeNone().skipToEntityType(EntityType.comment).empty);

R skipToParentEndTag(R)(R entityRange)
if(isInstanceOf!(EntityRange, R));

Skips entities until the end tag is reached that corresponds to the start tag that is the parent of the current entity.

Returns: The given range with its front now at the end tag which corresponds to the parent start tag of the entity that was front when skipToParentEndTag was called. If the current entity does not have a parent start tag (which means that it's either the root element or a comment or PI outside of the root element), then an empty range is returned.

Throws: XMLParsingException on invalid XML.

Examples:

auto xml = "<root>\n" ~
           "    <foo>\n" ~
           "        <!-- comment -->\n" ~
           "        <bar>exam</bar>\n" ~
           "    </foo>\n" ~
           "    <!-- another comment -->\n" ~
           "</root>";
{
    auto range = parseXML(xml);
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "root");

    range.popFront();
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "foo");

    range.popFront();
    assert(range.front.type == EntityType.comment);
    assert(range.front.text == " comment ");

    range = range.skipToParentEndTag();
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "foo");

    range = range.skipToParentEndTag();
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "root");

    range = range.skipToParentEndTag();
    assert(range.empty);
}
{
    auto range = parseXML(xml);
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "root");

    range.popFront();
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "foo");

    range.popFront();
    assert(range.front.type == EntityType.comment);
    assert(range.front.text == " comment ");

    range.popFront();
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "bar");

    range.popFront();
    assert(range.front.type == EntityType.text);
    assert(range.front.text == "exam");

    range = range.skipToParentEndTag();
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "bar");

    range = range.skipToParentEndTag();
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "foo");

    range.popFront();
    assert(range.front.type == EntityType.comment);
    assert(range.front.text == " another comment ");

    range = range.skipToParentEndTag();
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "root");

    assert(range.skipToParentEndTag().empty);
}
{
    auto range = parseXML("<root><foo>bar</foo></root>");
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "root");
    assert(range.skipToParentEndTag().empty);
}

R skipToPath(R)(R entityRange, string path)
if(isInstanceOf!(EntityRange, R));

Treats the given string like a file path except that each directory corresponds to the name of a start tag. Note that this does not try to implement XPath as that would be quite complicated, and it really doesn't fit with a StAX parser.

A start tag should be thought of as a directory, with its child start tags as the directories it contains.

All paths should be relative. EntityRange can only move forward through the document, so using an absolute path would only make sense at the beginning of the document. As such, absolute paths are treated as invalid paths.

"./" and "../" are supported. Repeated slashes such as in "foo//bar" are not supported and are treated as an invalid path.

If range.front.type == EntityType.elementStart, then range.skiptoPath("foo") will search for the first child start tag (be it EntityType.elementStart or EntityType.elementEmpty) with the name "foo". That start tag must be a direct child of the current start tag.

If range.front.type is any other EntityType, then range.skipToPath("foo") will return an empty range, because no other EntityTypes have child start tags.

For any EntityType, range.skipToPath("../foo") will search for the first start tag with the name "foo" at the same level as the current entity. If the current entity is a start tag with the name "foo", it will not be considered a match.

range.skipToPath("./") is a no-op. However, range.skipToPath("../") will result in the empty range (since it doesn't target a specific start tag).

range.skipToPath("foo/bar") is equivalent to range.skipToPath("foo").skipToPath("bar"), and range.skipToPath("../foo/bar") is equivalent to range.skipToPath("../foo").skipToPath("bar").

Returns: The given range with its front now at the requested entity if the path is valid; otherwise, an empty range is returned.

Throws: XMLParsingException on invalid XML.

Examples:

{
    auto xml = "<carrot>\n" ~
               "    <foo>\n" ~
               "        <bar>\n" ~
               "            <baz/>\n" ~
               "            <other/>\n" ~
               "        </bar>\n" ~
               "    </foo>\n" ~
               "</carrot>";

    auto range = parseXML(xml);
    // "<carrot>"
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "carrot");

    range = range.skipToPath("foo/bar");
    // "        <bar>
    assert(!range.empty);
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "bar");

    range = range.skipToPath("baz");
    // "            <baz/>
    assert(!range.empty);
    assert(range.front.type == EntityType.elementEmpty);

    // other is not a child element of baz
    assert(range.skipToPath("other").empty);

    range = range.skipToPath("../other");
    // "            <other/>"
    assert(!range.empty);
    assert(range.front.type == EntityType.elementEmpty);
}
{
    auto xml = "<potato>\n" ~
               "    <foo>\n" ~
               "        <bar>\n "~
               "        </bar>\n" ~
               "        <crazy>\n" ~
               "        </crazy>\n" ~
               "        <fou/>\n" ~
               "    </foo>\n" ~
               "    <buzz/>\n" ~
               "</potato>";

    auto range = parseXML(xml);
    // "<potato>"
    assert(range.front.type == EntityType.elementStart);

    range = range.skipToPath("./");
    // "<potato>"
    assert(!range.empty);
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "potato");

    range = range.skipToPath("./foo/bar");
    // "        <bar>"
    assert(!range.empty);
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "bar");

    range = range.skipToPath("../crazy");
    // "        <crazy>"
    assert(!range.empty);
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "crazy");

    // Whether popFront is called here before the call to
    // range.skipToPath("../fou") below, the result is the same, because
    // both <crazy> and </crazy> are at the same level.
    range.popFront();
    // "        </crazy>"
    assert(!range.empty);
    assert(range.front.type == EntityType.elementEnd);
    assert(range.front.name == "crazy");

    range = range.skipToPath("../fou");
    // "        <fou/>"
    assert(!range.empty);
    assert(range.front.type == EntityType.elementEmpty);
}
// Searching stops at the first matching start tag.
{
    auto xml = "<beet>\n" ~
               "    <foo a='42'>\n" ~
               "    </foo>\n" ~
               "    <foo b='451'>\n" ~
               "    </foo>\n" ~
               "</beet>";

    auto range = parseXML(xml);
    range = range.skipToPath("foo");
    assert(!range.empty);
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "foo");

    {
        auto attrs = range.front.attributes;
        assert(attrs.front.name == "a");
        assert(attrs.front.value == "42");
    }

    range = range.skipToPath("../foo");
    assert(!range.empty);
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "foo");

    {
        auto attrs = range.front.attributes;
        assert(attrs.front.name == "b");
        assert(attrs.front.value == "451");
    }
}
// skipToPath will work on an empty range but will always return an
// empty range.
{
    auto range = parseXML("<root/>");
    assert(range.takeNone().skipToPath("nowhere").empty);
}
// Empty and absolute paths will also result in an empty range as will
// "../" without any actual tag name on the end.
{
    auto range = parseXML("<root/>");
    assert(range.skipToPath("").empty);
    assert(range.skipToPath("/").empty);
    assert(range.skipToPath("../").empty);
}
// Only non-empty start tags have children; all other EntityTypes result
// in an empty range unless "../" is used.
{
    auto xml = "<!-- comment -->\n" ~
               "<root>\n" ~
               "    <foo/>\n" ~
               "</root>";
    auto range = parseXML(xml);
    assert(range.skipToPath("root").empty);
    assert(range.skipToPath("foo").empty);

    range = range.skipToPath("../root");
    assert(!range.empty);
    assert(range.front.type == EntityType.elementStart);
    assert(range.front.name == "root");
}