arsd.dom

This is an html DOM implementation, started with cloning what the browser offers in Javascript, but going well beyond it in convenience.

If you can do it in Javascript, you can probably do it with this module.

And much more.

⚓ Element[] findComments(Document document, string txt);
Element[] findComments(Element element, string txt);

finds comments that match the given txt. Case insensitive, strips whitespace.

⚓ struct DataSet;

A proxy object to do the Element class' dataset property. See Element.dataset for more info.

Do not create this object directly.

⚓ struct AttributeSet;

Proxy object for attributes which will replace the main opDispatch eventually

⚓ struct ElementStyle;

for style, i want to be able to set it with a string like a plain attribute,

but also be able to do properties Javascript style.

⚓ string unCamelCase(string a);

Converts a camel cased propertyName to a css style dashed property-name

⚓ string camelCase(string a);

Translates a css style property-name to a camel cased propertyName

⚓ interface FileResource;

This might belong in another module, but it represents a file with a mime type and some data.

Document implements this interface with type = text/html (see Document.contentType for more info)

and data = document.toString, so you can return Documents anywhere web.d expects FileResources.

⚓ abstract const @property string contentType();

the content-type of the file. e.g. "text/html; charset=utf-8" or "image/png"

⚓ abstract const immutable(ubyte)[] getData();

the data

⚓ enum NodeType: int;

.

⚓ T require(T = Element, string file = __FILE__, int line = __LINE__)(Element e) if (is(T : Element));

You can use this to do an easy null check or a dynamic cast+null check on any element.

⚓ class Element;

This represents almost everything in the DOM.

⚓ string tagName;

The name of the tag. Remember, changing this doesn't change the dynamic type of the object.

⚓ string[string] attributes;

This is where the attributes are actually stored. You should use getAttribute, setAttribute, and hasAttribute instead.

⚓ Document parentDocument;

Get the parent Document object that contains this element.

It may be null, so remember to check for that.

⚓ Element parentNode;

.

⚓ static Element make(string tagName, string childInfo = null, string childInfo2 = null);

Convenience function to try to do the right thing for HTML. This is the main

way I create elements.

⚓ this(Document _parentDocument, string _tagName, string[string] _attributes = null, bool _selfClosed = false);

Generally, you don't want to call this yourself - use Element.make or document.createElement instead.

⚓ this(string _tagName, string[string] _attributes = null);

Convenience constructor when you don't care about the parentDocument. Note this might break things on the document.

Note also that without a parent document, elements are always in strict, case-sensitive mode.

⚓ @property Element firstChild();

Returns the first child of this element. If it has no children, returns null.

Remember, text nodes are children too.

⚓ @property Element lastChild();

⚓ @property Element previousSibling(string tagName = null);

.

⚓ @property Element nextSibling(string tagName = null);

.

⚓ T getParent(T = Element)(string tagName = null) if (is(T : Element));

Gets the nearest node, going up the chain, with the given tagName

May return null or throw.

⚓ Element getElementById(string id);

.

⚓ Element querySelector(string selector);

Note: you can give multiple selectors, separated by commas.

It will return the first match it finds.

⚓ Element[] querySelectorAll(string selector);

a more standards-compliant alias for getElementsBySelector

⚓ Element[] getElementsBySelector(string selector);

Does a CSS selector

-- all, default if nothing else is there

tag#id.class.class.class:pseudo[attrib=what][attrib=what] OP selector

It is all additive

OP

space = descendant > = direct descendant + = sibling (E+F Matches any F element immediately preceded by a sibling element E)

[foo] Foo is present as an attribute [foo="warning"] Matches any E element whose "foo" attribute value is exactly equal to "warning". E[foo~="warning"] Matches any E element whose "foo" attribute value is a list of space-separated values, one of which is exactly equal to "warning" E[lang|="en"] Matches any E element whose "lang" attribute has a hyphen-separated list of values beginning (from the left) with "en".

[item$=sdas] ends with [item^-sdsad] begins with

Quotes are optional here.

Pseudos: :first-child :last-child :link (same as a[href] for our purposes here)

There can be commas separating the selector. A comma separated list result is OR'd onto the main.

This ONLY cares about elements. text, etc, are ignored

There should be two functions: given element, does it match the selector? and given a selector, give me all the elements

⚓ Element[] getElementsByClassName(string cn);

.

⚓ Element[] getElementsByTagName(string tag);

.

⚓ const string getAttribute(string name);

Gets the given attribute value, or null if the attribute is not set.

Note that the returned string is decoded, so it no longer contains any xml entities.

⚓ Element setAttribute(string name, string value);

Sets an attribute. Returns this for easy chaining

⚓ bool hasAttribute(string name);

Returns if the attribute exists.

⚓ Element removeAttribute(string name);

Removes the given attribute from the element.

⚓ const @property string className();

Gets the class attribute's contents. Returns an empty string if it has no class.

⚓ @property Element className(string c);

.

⚓ @property string opDispatch(string name)(string v = null) if (isConvenientAttribute(name));

Provides easy access to attributes, object style.

auto element = Element.make("a"); a.href = "cool.html"; // this is the same as a.setAttribute("href", "cool.html"); string where = a.href; // same as a.getAttribute("href");

⚓ @property string opDispatch(string name)(string v = null) if (!isConvenientAttribute(name));

Deprecated:
generally open opDispatch caused a lot of unforeseen trouble with compile time duck typing and UFCS extensions. so I want to remove it. A small whitelist of attributes is still allowed, but others are not.

Instead, use element.attrs.attribute, element.attrs["attribute"], or element.getAttribute("attribute")/element.setAttribute("attribute").

⚓ const @property const(Element[]) childNodes();

Returns the element's children.

⚓ @property Element[] childNodes();

Mutable version of the same

⚓ @property DataSet dataset();

HTML5's dataset property. It is an alternate view into attributes with the data- prefix.

Given:

We get: assert(a.dataset.myProperty == "cool");

⚓ @property AttributeSet attrs();

Gives dot/opIndex access to attributes

ele.attrs.largeSrc = "foo"; // same as ele.setAttribute("largeSrc", "foo")

⚓ @property ElementStyle style();

Provides both string and object style (like in Javascript) access to the style attribute.

⚓ @property ElementStyle style(string s);

This sets the style attribute with a string.

⚓ @property CssStyle computedStyle();

.

⚓ void removeAllChildren();

Removes all inner content from the tag; all child text and elements are gone.

⚓ Element appendChild(Element e);

Appends the given element to this one. The given element must not have a parent already.

⚓ Element insertBefore(in Element where, Element what);

Inserts the second element to this node, right before the first param

⚓ Element insertAfter(in Element where, Element what);

.

⚓ Element swapNode(Element child, Element replacement);

swaps one child for a new thing. Returns the old child which is now parentless.

⚓ Element appendText(string text);

.

⚓ @property Element[] childElements();

.

⚓ Element[] appendHtml(string html);

Appends the given html to the element, returning the elements appended

⚓ void insertChildAfter(Element child, Element where);

.

⚓ Element[] stealChildren(Element e, Element position = null);

.

⚓ Element prependChild(Element e);

Puts the current element first in our children list. The given element must not have a parent already.

⚓ const @property string innerHTML(Appender!string where = appender!string());

Returns a string containing all child elements, formatted such that it could be pasted into an XML file.

⚓ @property Element innerHTML(string html, bool strict = false);
@property Element innerHTML(Html html);

Takes some html and replaces the element's children with the tree made from the string.

⚓ @property Element[] outerHTML(string html);

Replaces this node with the given html string, which is parsed

Note: this invalidates the this reference, since it is removed from the tree.

Returns the new children that replace this.

⚓ @property string outerHTML();

Returns all the html for this element, including the tag itself.

This is equivalent to calling toString().

⚓ @property void innerRawSource(string rawSource);

This sets the inner content of the element *without* trying to parse it.

You can inject any code in there; this serves as an escape hatch from the dom.

The only times you might actually need it are for < style > and < script > tags in html.

Other than that, innerHTML and/or innerText should do the job.

⚓ Element replaceChild(Element find, Element replace);

.

⚓ void replaceChild(Element find, Element[] replace);

Replaces the given element with a whole group.

⚓ Element removeChild(Element c);

Removes the given child from this list.

Returns the removed element.

⚓ Element[] removeChildren();

This removes all the children from this element, returning the old list.

⚓ const @property string innerText();

Fetch the inside text, with all tags stripped out.

cool api & code dude

innerText of that is "cool api & code dude".

This does not match what real innerText does!

http: //perfectionkills.com/the-poor-misunderstood-innerText/

It is more like textContent.

⚓ @property void innerText(string text);

Sets the inside text, replacing all children. You don't have to worry about entity encoding.

⚓ @property void outerText(string text);

Strips this node out of the document, replacing it with the given text

⚓ const string outerText();

Same result as innerText; the tag with all inner tags stripped out

⚓ @property Element cloned();

This is a full clone of the element

⚓ Element cloneNode(bool deepClone);

Clones the node. If deepClone is true, clone all inner tags too. If false, only do this tag (and its attributes), but it will have no contents.

⚓ const string nodeValue();

.

⚓ const @property int nodeType();

.

⚓ const string toString();

Turns the whole element, including tag, attributes, and children, into a string which could be pasted into an XML file.

⚓ const string writeToAppender(Appender!string where = appender!string());

This is the actual implementation used by toString. You can pass it a preallocated buffer to save some time.

Returns the string it creates.

⚓ @property ElementStream tree();

Returns a lazy range of all its children, recursively.

⚓ Element addField(string label, string name, string type = "text", FormFieldOptions fieldOptions = FormFieldOptions.none);

Tags: HTML, HTML5

⚓ class DocumentFragment: arsd.dom.Element;

.

⚓ this(Document _parentDocument);

.

⚓ const string writeToAppender(Appender!string where = appender!string());

.

⚓ string htmlEntitiesEncode(string data, Appender!string output = appender!string());

Given text, encode all html entities on it - &, <, >, and ". This function also

encodes all 8 bit characters as entities, thus ensuring the resultant text will work

even if your charset isn't set right.

The output parameter can be given to append to an existing buffer. You don't have to

pass one; regardless, the return value will be usable for you, with just the data encoded.

⚓ string xmlEntitiesEncode(string data);

An alias for htmlEntitiesEncode; it works for xml too

⚓ dchar parseEntity(in dchar[] entity);

This helper function is used for decoding html entities. It has a hard-coded list of entities and characters.

⚓ string htmlEntitiesDecode(string data, bool strict = false);

This takes a string of raw HTML and decodes the entities into a nice D utf-8 string.

By default, it uses loose mode - it will try to return a useful string from garbage input too.

Set the second parameter to true if you'd prefer it to strictly throw exceptions on garbage input.

⚓ class RawSource: arsd.dom.SpecialElement;

.

⚓ this(Document _parentDocument, string s);

.

⚓ const string nodeValue();

.

⚓ const string writeToAppender(Appender!string where = appender!string());

.

⚓ string source;

.

⚓ class PhpCode: arsd.dom.ServerSideCode;

.

⚓ this(Document _parentDocument, string s);

.

⚓ class AspCode: arsd.dom.ServerSideCode;

.

⚓ this(Document _parentDocument, string s);

.

⚓ class BangInstruction: arsd.dom.SpecialElement;

.

⚓ this(Document _parentDocument, string s);

.

⚓ const string nodeValue();

.

⚓ const string writeToAppender(Appender!string where = appender!string());

.

⚓ string source;

.

⚓ class QuestionInstruction: arsd.dom.SpecialElement;

.

⚓ this(Document _parentDocument, string s);

.

⚓ const string nodeValue();

.

⚓ const string writeToAppender(Appender!string where = appender!string());

.

⚓ string source;

.

⚓ class HtmlComment: arsd.dom.SpecialElement;

.

⚓ this(Document _parentDocument, string s);

.

⚓ const string nodeValue();

.

⚓ const string writeToAppender(Appender!string where = appender!string());

.

⚓ string source;

.

⚓ class TextNode: arsd.dom.Element;

.

⚓ this(Document _parentDocument, string e);

.

⚓ static TextNode fromUndecodedString(Document _parentDocument, string html);

.

⚓ @property Element cloned();

.

⚓ const string nodeValue();

.

⚓ const @property int nodeType();

.

⚓ const string writeToAppender(Appender!string where = appender!string());

.

⚓ Element appendChild(Element e);

.

⚓ string contents;

.

⚓ class Link: arsd.dom.Element;

There are subclasses of Element offering improved helper functions for the element in HTML.

.

⚓ this(Document _parentDocument);

.

⚓ this(string href, string text);

.

⚓ string getValue(string name);

This gets a variable from the URL's query string.

⚓ void updateQueryString(string[string] vars);

.

⚓ void setValue(string name, string variable);

Sets or adds the variable with the given name to the given value

It automatically URI encodes the values and takes care of the ? and &.

⚓ void removeValue(string name);

Removes the given variable from the query string

⚓ class Form: arsd.dom.Element;

.

⚓ this(Document _parentDocument);

.

⚓ void setValue(string field, string value, bool makeNew);

Set's the form field's value. For input boxes, this sets the value attribute. For

textareas, it sets the innerText. For radio boxes and select boxes, it removes

the checked/selected attribute from all, and adds it to the one matching the value.

For checkboxes, if the value is non-null and not empty, it checks the box.

If you set a value that doesn't exist, it throws an exception if makeNew is false.

Otherwise, it makes a new input with type=hidden to keep the value.

⚓ void addValueArray(string key, string[] arrayOfValues);

This takes an array of strings and adds hidden elements for each one of them. Unlike setValue,

it makes no attempt to find and modify existing elements in the form to the new values.

⚓ string getValue(string field);

Gets the value of the field; what would be given if it submitted right now. (so

it handles select boxes and radio buttons too). For checkboxes, if a value isn't

given, but it is checked, it returns "checked", since null and "" are indistinguishable

⚓ string getPostableData();

.

⚓ Element[] getField(string name);

Gets the actual elements with the given name

⚓ Element getLabel(string forId);

Grabs the with the given for tag, if there is one.

⚓ Element addInput(string name, string value, string type = "hidden");

Adds a new INPUT field to the end of the form with the given attributes.

⚓ void removeField(string name);

Removes the given field from the form. It finds the element and knocks it right out.

⚓ class Table: arsd.dom.Element;

.

⚓ this(Document _parentDocument);

.

⚓ Element th(T)(T t);

.

⚓ Element td(T)(T t);

.

⚓ Element appendHeaderRow(T...)(T t);

.

⚓ Element appendFooterRow(T...)(T t);

.

⚓ Element appendRow(T...)(T t);

.

⚓ Element captionElement();

.

⚓ @property string caption();

.

⚓ @property void caption(string text);

.

⚓ TableCell[][] getGrid(Element tablePortition = null);

Gets the logical layout of the table as a rectangular grid of

cells. It considers rowspan and colspan. A cell with a large

span is represented in the grid by being referenced several times.

The tablePortition parameter can get just a , , or

portion if you pass one.

Note: the rectangular grid might include null cells.

This is kinda expensive so you should call once when you want the grid,

then do lookups on the returned array.

⚓ class TableRow: arsd.dom.Element;

Represents a table row element - a

⚓ this(Document _parentDocument);

.

⚓ class TableCell: arsd.dom.Element;

Represents anything that can be a table cell - or html.

⚓ this(Document _parentDocument, string _tagName);

.

⚓ class MarkupException: object.Exception;

.

⚓ this(string message, string file = __FILE__, size_t line = __LINE__);

.

⚓ class ElementNotFoundException: object.Exception;

This is used when you are using one of the require variants of navigation, and no matching element can be found in the tree.

⚓ this(string type, string search, string file = __FILE__, size_t line = __LINE__);

type == kind of element you were looking for and search == a selector describing the search.

⚓ struct Html;

The html struct is used to differentiate between regular text nodes and html in certain functions

Easiest way to construct it is like this: auto html = Html("

hello

");

⚓ string source;

This string holds the actual html. Use it to retrieve the contents.

⚓ class Document: arsd.dom.FileResource;

The main document interface, including a html parser.

⚓ this(string data, bool caseSensitive = false, bool strict = false);

.

⚓ this();

Creates an empty document. It has *nothing* in it at all.

⚓ ElementCollection opIndex(string selector);

This is just something I'm toying with. Right now, you use opIndex to put in css selectors.

It returns a struct that forwards calls to all elements it holds, and returns itself so you

can chain it.

Example: document["p"].innerText("hello").addClass("modified");

Equivalent to: foreach(e; document.getElementsBySelector("p")) { e.innerText("hello"); e.addClas("modified"); }

Note: always use function calls (not property syntax) and don't use toString in there for best results.

You can also do things like: document["p"]["b"] though tbh I'm not sure why since the selector string can do all that anyway. Maybe

you could put in some kind of custom filter function tho.

⚓ @property string contentType(string mimeType);

If you're using this for some other kind of XML, you can

set the content type here.

Note: this has no impact on the function of this class.

It is only used if the document is sent via a protocol like HTTP.

This may be called by parse() if it recognizes the data. Otherwise,

if you don't set it, it assumes text/html; charset=utf-8.

⚓ const @property string contentType();

implementing the FileResource interface, useful for sending via

http automatically.

⚓ const immutable(ubyte)[] getData();

implementing the FileResource interface; it calls toString.

⚓ void enableAddingSpecialTagsToDom();

Concatenates any consecutive text nodes

This will set delegates for parseSaw* (note: this overwrites anything else you set, and you setting subsequently will overwrite this) that add those things to the dom tree when it sees them.

Call this before calling parse().

Note this will also preserve the prolog and doctype from the original file, if there was one.

⚓ bool delegate(string) parseSawComment;

If the parser sees a html comment, it will call this callback

will call parseSawComment(" comment ")

Return true if you want the node appended to the document.

⚓ bool delegate(string) parseSawAspCode;

If the parser sees <% asp code... %>, it will call this callback.

It will be passed "% asp code... %" or "%= asp code .. %"

Return true if you want the node appended to the document.

⚓ bool delegate(string) parseSawPhpCode;

If the parser sees <?php php code... ?>, it will call this callback.

It will be passed "?php php code... ?" or "?= asp code .. ?"

Note: dom.d cannot identify the other php <? code ?> short format.

Return true if you want the node appended to the document.

⚓ bool delegate(string) parseSawQuestionInstruction;

if it sees a <?xxx> that is not php or asp

it calls this function with the contents.

<?SOMETHING foo> calls parseSawQuestionInstruction("?SOMETHING foo")

Unlike the php/asp ones, this ends on the first > it sees, without requiring ?>.

Return true if you want the node appended to the document.

⚓ bool delegate(string) parseSawBangInstruction;

if it sees a <! that is not CDATA or comment (CDATA is handled automatically and comments call parseSawComment),

it calls this function with the contents.

<!SOMETHING foo> calls parseSawBangInstruction("SOMETHING foo")

Return true if you want the node appended to the document.

⚓ void parseGarbage()(string data);

Given the kind of garbage you find on the Internet, try to make sense of it.

Equivalent to document.parse(data, false, false, null);

(Case-insensitive, non-strict, determine character encoding from the data.)

NOTE: this makes no attempt at added security.

It is a template so it lazily imports characterencodings.

⚓ void parseStrict(string data);

Parses well-formed UTF-8, case-sensitive, XML or XHTML

Will throw exceptions on things like unclosed tags.

⚓ void parseUtf8(string data, bool caseSensitive = false, bool strict = false);

Parses well-formed UTF-8 in loose mode (by default). Tries to correct

tag soup, but does NOT try to correct bad character encodings.

They will still throw an exception.

⚓ void parse()(in string rawdata, bool caseSensitive = false, bool strict = false, string dataEncoding = "UTF-8");

Take XMLish data and try to make the DOM tree out of it.

The goal isn't to be perfect, but to just be good enough to approximate Javascript's behavior.

If strict, it throws on something that doesn't make sense. (Examples: mismatched tags. It doesn't validate!) If not strict, it tries to recover anyway, and only throws when something is REALLY unworkable.

If strict is false, it uses a magic list of tags that needn't be closed. If you are writing a document specifically for this, try to avoid such - use self closed tags at least. Easier to parse.

The dataEncoding argument can be used to pass a specific charset encoding for automatic conversion. If null (which is NOT the default!), it tries to determine from the data itself, using the xml prolog or meta tags, and assumes UTF-8 if unsure.

If this assumption is wrong, it can throw on non-ascii characters!

Note that it previously assumed the data was encoded as UTF-8, which is why the dataEncoding argument defaults to that.

So it shouldn't break backward compatibility.

But, if you want the best behavior on wild data - figuring it out from the document instead of assuming - you'll probably want to change that argument to null.

This is a template so it lazily imports arsd.characterencodings, which is required to fix up data encodings.

If you are sure the encoding is good, try parseUtf8 or parseStrict to avoid the dependency. If it is data from the Internet though, a random website, the encoding is often a lie. This function, if dataEncoding == null, can correct for that, or you can try parseGarbage. In those cases, arsd.characterencodings is required to compile.

⚓ @property string title();

Gets the