DOMEntity

Represents an entity in an XML document as a DOM tree.

parseDOM either takes a range of characters or an dxml.parser.EntityRange and generates a DOMEntity from that XML.

When parseDOM processes the XML, it returns a DOMEntity representing the entire document. Even though the XML document itself isn't technically an entity in the XML document, it's simplest to treat it as if it were an EntityType.elementStart with an empty name. That DOMEntity then contains child entities that recursively define the DOM tree through their children.

For DOMEntities of type EntityType.elementStart, _DOMEntity.children gives access to all of the child entities of that start tag. Other DOMEntities have no children.

Note that the type determines which properties of the DOMEntity can be used, and it can determine whether functions which a DOMEntity 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.

If parseDOM is given a range of characters, it in turn passes that to dxml.parser.parseXML to do the actual XML parsing. As such, that overload accepts an optional dxml.parser.Config as a template argument to configure the parser.

If parseDOM is given an EntityRange, the range does not have to be at the start of the document. It can be used to create a DOM for a portion of the document. When a character range is passed to it, it will return a DOMEntity with the type EntityType.elementStart and an empty name. It will iterate the range until it either reaches the end of the range, or it reaches the end tag which matches the start tag which is the parent of the entity that was the front of the range when it was passed to parseDOM. The EntityType.elementStart is passed by $(K_REF), so if it was not at the top level when it was passed to parseDOM (and thus still has elements in it when parseDOM returns), the range will then be at the entity after that matching end tag, and the application can continue to process the range after that if it so chooses.

Postblit

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

Public Imports

std.algorithm.searching
public import std.algorithm.searching : canFind;
std.range
public import std.range : only, takeExactly;
std.typecons
public import std.typecons : Tuple;
dxml.parser
public import dxml.parser : TextPos;

Members

Aliases

Attribute
alias Attribute = Tuple!(SliceOfR, "name", SliceOfR, "value", TextPos, "pos")

The exact instantiation of $(PHOBOS_REF Tuple, std, typecons) that attributes returns a range of.

SliceOfR
alias SliceOfR = R

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

Properties

attributes
auto attributes [@property getter]

Returns a dynamic array of attributes for a start tag where each attribute is represented as a
$(PHOBOS_REF_ALTTEXT Tuple, Tuple, std, typecons)!( $(LREF2 SliceOfR, EntityRange), $(D_STRING "name"), $(LREF2 SliceOfR, EntityRange), $(D_STRING "value"), $(REF_ALTTEXT TextPos, TextPos, dxml, parser), $(D_STRING "pos")).

children
DOMEntity[] children [@property getter]

Returns the child entities of the current entity.

name
SliceOfR name [@property getter]

Gives the name of this DOMEntity.

path
SliceOfR[] path [@property getter]

Gives the list of the names of the parent start tags of this DOMEntity.

pos
TextPos pos [@property getter]

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

text
SliceOfR text [@property getter]

Returns the textual value of this DOMEntity.

type
EntityType type [@property getter]

The EntityType for this DOMEntity.

Return Value

A DOMEntity representing the DOM tree from the point in the document that was passed to parseDOM (the start of the document if a range of characters was passed, and wherever in the document the range was if an EntityRange was passed).

Throws

XMLParsingException if the parser encounters invalid XML.

Examples

parseDOM with the default Config and a range of characters.

1 import std.range.primitives;
2 
3 auto xml = "<root>\n" ~
4            "    <!-- no comment -->\n" ~
5            "    <foo></foo>\n" ~
6            "    <baz>\n" ~
7            "        <xyzzy>It's an adventure!</xyzzy>\n" ~
8            "    </baz>\n" ~
9            "    <tag/>\n" ~
10            "</root>";
11 
12 auto dom = parseDOM(xml);
13 assert(dom.type == EntityType.elementStart);
14 assert(dom.name.empty);
15 assert(dom.children.length == 1);
16 
17 auto root = dom.children[0];
18 assert(root.type == EntityType.elementStart);
19 assert(root.name == "root");
20 assert(root.children.length == 4);
21 
22 assert(root.children[0].type == EntityType.comment);
23 assert(root.children[0].text == " no comment ");
24 
25 assert(root.children[1].type == EntityType.elementStart);
26 assert(root.children[1].name == "foo");
27 assert(root.children[1].children.length == 0);
28 
29 auto baz = root.children[2];
30 assert(baz.type == EntityType.elementStart);
31 assert(baz.name == "baz");
32 assert(baz.children.length == 1);
33 
34 auto xyzzy = baz.children[0];
35 assert(xyzzy.type == EntityType.elementStart);
36 assert(xyzzy.name == "xyzzy");
37 assert(xyzzy.children.length == 1);
38 
39 assert(xyzzy.children[0].type == EntityType.text);
40 assert(xyzzy.children[0].text == "It's an adventure!");
41 
42 assert(root.children[3].type == EntityType.elementEmpty);
43 assert(root.children[3].name == "tag");

parseDOM with simpleXML and a range of characters.

1 import std.range.primitives : empty;
2 
3 auto xml = "<root>\n" ~
4            "    <!-- no comment -->\n" ~
5            "    <foo></foo>\n" ~
6            "    <baz>\n" ~
7            "        <xyzzy>It's an adventure!</xyzzy>\n" ~
8            "    </baz>\n" ~
9            "    <tag/>\n" ~
10            "</root>";
11 
12 auto dom = parseDOM!simpleXML(xml);
13 assert(dom.type == EntityType.elementStart);
14 assert(dom.name.empty);
15 assert(dom.children.length == 1);
16 
17 auto root = dom.children[0];
18 assert(root.type == EntityType.elementStart);
19 assert(root.name == "root");
20 assert(root.children.length == 3);
21 
22 assert(root.children[0].type == EntityType.elementStart);
23 assert(root.children[0].name == "foo");
24 assert(root.children[0].children.length == 0);
25 
26 auto baz = root.children[1];
27 assert(baz.type == EntityType.elementStart);
28 assert(baz.name == "baz");
29 assert(baz.children.length == 1);
30 
31 auto xyzzy = baz.children[0];
32 assert(xyzzy.type == EntityType.elementStart);
33 assert(xyzzy.name == "xyzzy");
34 assert(xyzzy.children.length == 1);
35 
36 assert(xyzzy.children[0].type == EntityType.text);
37 assert(xyzzy.children[0].text == "It's an adventure!");
38 
39 assert(root.children[2].type == EntityType.elementStart);
40 assert(root.children[2].name == "tag");
41 assert(root.children[2].children.length == 0);

parseDOM with simpleXML and an EntityRange.

1 import std.range.primitives : empty;
2 import dxml.parser : parseXML;
3 
4 auto xml = "<root>\n" ~
5            "    <!-- no comment -->\n" ~
6            "    <foo></foo>\n" ~
7            "    <baz>\n" ~
8            "        <xyzzy>It's an adventure!</xyzzy>\n" ~
9            "    </baz>\n" ~
10            "    <tag/>\n" ~
11            "</root>";
12 
13 auto range = parseXML!simpleXML(xml);
14 auto dom = parseDOM(range);
15 assert(range.empty);
16 
17 assert(dom.type == EntityType.elementStart);
18 assert(dom.name.empty);
19 assert(dom.children.length == 1);
20 
21 auto root = dom.children[0];
22 assert(root.type == EntityType.elementStart);
23 assert(root.name == "root");
24 assert(root.children.length == 3);
25 
26 assert(root.children[0].type == EntityType.elementStart);
27 assert(root.children[0].name == "foo");
28 assert(root.children[0].children.length == 0);
29 
30 auto baz = root.children[1];
31 assert(baz.type == EntityType.elementStart);
32 assert(baz.name == "baz");
33 assert(baz.children.length == 1);
34 
35 auto xyzzy = baz.children[0];
36 assert(xyzzy.type == EntityType.elementStart);
37 assert(xyzzy.name == "xyzzy");
38 assert(xyzzy.children.length == 1);
39 
40 assert(xyzzy.children[0].type == EntityType.text);
41 assert(xyzzy.children[0].text == "It's an adventure!");
42 
43 assert(root.children[2].type == EntityType.elementStart);
44 assert(root.children[2].name == "tag");
45 assert(root.children[2].children.length == 0);

parseDOM with an EntityRange which is not at the start of the document.

1 import std.range.primitives : empty;
2 import dxml.parser : parseXML, skipToPath;
3 
4 auto xml = "<root>\n" ~
5            "    <!-- no comment -->\n" ~
6            "    <foo></foo>\n" ~
7            "    <baz>\n" ~
8            "        <xyzzy>It's an adventure!</xyzzy>\n" ~
9            "    </baz>\n" ~
10            "    <tag/>\n" ~
11            "</root>";
12 
13 auto range = parseXML!simpleXML(xml).skipToPath("baz/xyzzy");
14 assert(range.front.type == EntityType.elementStart);
15 assert(range.front.name == "xyzzy");
16 
17 auto dom = parseDOM(range);
18 assert(range.front.type == EntityType.elementStart);
19 assert(range.front.name == "tag");
20 
21 assert(dom.type == EntityType.elementStart);
22 assert(dom.name.empty);
23 assert(dom.children.length == 1);
24 
25 auto xyzzy = dom.children[0];
26 assert(xyzzy.type == EntityType.elementStart);
27 assert(xyzzy.name == "xyzzy");
28 assert(xyzzy.children.length == 1);
29 
30 assert(xyzzy.children[0].type == EntityType.text);
31 assert(xyzzy.children[0].text == "It's an adventure!");

parseDOM at compile-time

1 enum xml = "<!-- comment -->\n" ~
2            "<root>\n" ~
3            "    <foo>some text<whatever/></foo>\n" ~
4            "    <bar/>\n" ~
5            "    <baz></baz>\n" ~
6            "</root>";
7 
8 enum dom = parseDOM(xml);
9 static assert(dom.type == EntityType.elementStart);
10 static assert(dom.name.empty);
11 static assert(dom.children.length == 2);
12 
13 static assert(dom.children[0].type == EntityType.comment);
14 static assert(dom.children[0].text == " comment ");

Meta