Document

The main document interface, including a html or xml parser.

There's three main ways to create a Document:

If you want to parse something and inspect the tags, you can use the constructor:

// create and parse some HTML in one call
auto document = new Document("<html></html>");

// or some XML
auto document = new Document("<xml></xml>", true, true); // strict mode enabled

// or better yet:
auto document = new XmlDocument("<xml></xml>"); // specialized subclass

If you want to download something and parse it in one call, the fromUrl static function can help:

auto document = Document.fromUrl("http://dlang.org/");

(note that this requires my arsd.characterencodings and arsd.http2 libraries)

And, if you need to inspect things like <%= foo %> tags and comments, you can add them to the dom like this, with the enableAddingSpecialTagsToDom and parseUtf8 or parseGarbage functions:

auto document = new Document();
document.enableAddingSpecialTagsToDom();
document.parseUtf8("<example></example>", true, true); // changes the trues to false to switch from xml to html mode

However you parse it, it will put a few things into special variables.

root contains the root document. prolog contains the instructions before the root (like <!DOCTYPE html>). To keep the original things, you will need to enableAddingSpecialTagsToDom first, otherwise the library will return generic strings in there. piecesBeforeRoot will have other parsed instructions, if enableAddingSpecialTagsToDom is called. piecesAfterRoot will contain any xml-looking data after the root tag is closed.

Most often though, you will not need to look at any of that data, since Document itself has methods like querySelector, appendChild, and more which will forward to the root Element for you.

class Document : FileResource , DomParent {

static Document fromUrl(string url, bool strictMode);

this(string data, bool caseSensitive, bool strict);

ElementCollection opIndex(string selector);

string _contentType;

string contentType [@property setter];

string filename [@property getter];

string contentType [@property getter];

immutable(ubyte)[] getData();

void enableAddingSpecialTagsToDom();

bool delegate(string) parseSawComment;

bool delegate(string) parseSawAspCode;

bool delegate(string) parseSawPhpCode;

bool delegate(string) parseSawQuestionInstruction;

bool delegate(string) parseSawBangInstruction;

void parseGarbage(string data);

void parseStrict(string data, bool pureXmlMode);

void parseUtf8(string data, bool caseSensitive, bool strict);

string[] selfClosedElements;

string[] inlineElements;

void parse(string rawdata, bool caseSensitive, bool strict, string dataEncoding);

string title [@property getter];

string title [@property setter];

Element getElementById(string id);

SomeElementType requireElementById(string id, string file, size_t line);

SomeElementType requireSelector(string selector, string file, size_t line);

MaybeNullElement!SomeElementType optionSelector(string selector, string file, size_t line);

Element querySelector(string selector);

Element[] querySelectorAll(string selector);

Element[] getElementsBySelector(string selector);

Element[] getElementsByTagName(string tag);

Element[] getElementsByClassName(string tag);

Element getFirstElementByTagName(string tag);

Element mainBody();

string getMeta(string name);

void setMeta(string name, string value);

Form[] forms();

Form createForm();

Element createElement(string name);

Element createFragment();

Element createTextNode(string content);

Element findFirst(bool delegate(Element) doesItMatch);

void clear();

string prolog [@property getter];

void setProlog(string d);

string toString();

string toPrettyString(bool insertComments, int indentationLevel, string indentWith);

Element root;

Element[] piecesBeforeRoot;

Element[] piecesAfterRoot;

void delegate(DomMutationEvent)[] eventObservers;

}

Constructors

this this(string data, bool caseSensitive, bool strict): Creates a document with the given source data. If you want HTML behavior, use caseSensitive and struct set to false. For XML mode, set them to true.
this this(): Creates an empty document. It has *nothing* in it at all, ready.

Members

Functions

clear void clear(): .
createElement Element createElement(string name): .
createForm Form createForm(): .
createFragment Element createFragment(): .
createTextNode Element createTextNode(string content): .
enableAddingSpecialTagsToDom void enableAddingSpecialTagsToDom(): Adds objects to the dom representing things normally stripped out during the default parse, like comments, <!instructions>, <% code%>, and <? code?> all at once.
findFirst Element findFirst(bool delegate(Element) doesItMatch): .
forms Form[] forms(): .
getData immutable(ubyte)[] getData(): implementing the FileResource interface; it calls toString.
getElementById Element getElementById(string id)
getElementsByClassName Element[] getElementsByClassName(string tag)
getElementsBySelector deprecated Element[] getElementsBySelector(string selector)
getElementsByTagName Element[] getElementsByTagName(string tag): These functions all forward to the root element. See the documentation in the Element class.
getFirstElementByTagName Element getFirstElementByTagName(string tag): FIXME: btw, this could just be a lazy range......
getMeta string getMeta(string name): this uses a weird thing... it's [name=] if no colon and [property=] if colon
mainBody Element mainBody(): This returns the <body> element, if there is one. (It different than Javascript, where it is called 'body', because body is a keyword in D.)
opIndex 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.
optionSelector MaybeNullElement!SomeElementType optionSelector(string selector, string file, size_t line): These functions all forward to the root element. See the documentation in the Element class.
parse void parse(string rawdata, bool caseSensitive, bool strict, string dataEncoding): Take XMLish data and try to make the DOM tree out of it.
parseGarbage 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, but it will try to recover from anything instead of throwing.
parseStrict void parseStrict(string data, bool pureXmlMode): Parses well-formed UTF-8, case-sensitive, XML or XHTML Will throw exceptions on things like unclosed tags.
parseUtf8 void parseUtf8(string data, bool caseSensitive, bool strict): Parses well-formed UTF-8 in loose mode (by default). Tries to correct tag soup, but does NOT try to correct bad character encodings.
querySelector Element querySelector(string selector)
querySelectorAll Element[] querySelectorAll(string selector)
requireElementById SomeElementType requireElementById(string id, string file, size_t line)
requireSelector SomeElementType requireSelector(string selector, string file, size_t line): These functions all forward to the root element. See the documentation in the Element class.
setMeta void setMeta(string name, string value): Sets a meta tag in the document header. It is kinda hacky to work easily for both Facebook open graph and traditional html meta tags/
setProlog void setProlog(string d): Returns or sets the string before the root element. This is, for example, <!DOCTYPE html>\n or similar.
toPrettyString string toPrettyString(bool insertComments, int indentationLevel, string indentWith): Writes it out with whitespace for easier eyeball debugging
toString string toString(): Returns the document as string form. Please note that if there is anything in piecesAfterRoot, they are discarded. If you want to add them to the file, loop over that and append it yourself (but remember xml isn't supposed to have anything after the root element).

Properties

contentType string contentType [@property setter]: If you're using this for some other kind of XML, you can set the content type here.
contentType string contentType [@property getter]: implementing the FileResource interface, useful for sending via http automatically.
filename string filename [@property getter]: implementing the FileResource interface, useful for sending via http automatically.
prolog string prolog [@property getter]: Returns or sets the string before the root element. This is, for example, <!DOCTYPE html>\n or similar.
title string title [@property getter]: Gets the <title> element's innerText, if one exists
title string title [@property setter]: Sets the title of the page, creating a <title> element if needed.

Static functions

fromUrl Document fromUrl(string url, bool strictMode): Convenience method for web scraping. Requires arsd.http2 to be included in the build as well as arsd.characterencodings.

Variables

inlineElements string[] inlineElements;: List of elements that are considered inline for pretty printing. The default for a Document are hard-coded to something appropriate for HTML. For XmlDocument, it defaults to empty. You can modify this after construction but before parsing.
loose bool loose;: .
parseSawAspCode 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. It will be in an AspCode object.
parseSawBangInstruction 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. It will be in a BangInstruction object.
parseSawComment 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. It will be in a HtmlComment object.
parseSawPhpCode 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. It will be in a PhpCode object.
parseSawQuestionInstruction 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. It will be in a QuestionInstruction object.
piecesAfterRoot Element[] piecesAfterRoot;: stuff after the root, only stored in non-strict mode and not used in toString, but available in case you want it
piecesBeforeRoot Element[] piecesBeforeRoot;: if these were kept, this is stuff that appeared before the root element, such as <?xml version ?> decls and <!DOCTYPE>s
root Element root;: The root element, like <html>. Most the methods on Document forward to this object.
selfClosedElements string[] selfClosedElements;: List of elements that can be assumed to be self-closed in this document. The default for a Document are a hard-coded list of ones appropriate for HTML. For XmlDocument, it defaults to empty. You can modify this after construction but before parsing.

Inherited Members

From FileResource

contentType string contentType [@property getter]: the content-type of the file. e.g. "text/html; charset=utf-8" or "image/png"
getData immutable(ubyte)[] getData(): the data
filename string filename [@property getter]: filename, return null if none

See Also

core_functionality

Meta

Source

See Implementation