DOM4

Abstract

DOM4 defines the event and document model the Web platform uses. The DOM is a language- and platform neutral interface that allows programs and scripts to dynamically access and update the content and structure of documents.

Status of this Document

Table of Contents

1. Goals
2. Issues
3. 1 Conformance
   1. 1.1 Dependencies
   2. 1.2 Extensibility
4. 2 Terminology
   1. 2.1 Trees
   2. 2.2 Strings
   3. 2.3 Common microsyntaxes
      1. 2.3.1 Common parser idioms
      2. 2.3.2 Space-separated tokens
   4. 2.4 Namespaces
5. 3 Exceptions
   1. 3.1 Exception DOMException
6. 4 Events
   1. 4.1 Interface Event
   2. 4.2 Interface CustomEvent
   3. 4.3 Constructing events
   4. 4.4 Interface EventTarget
   5. 4.5 Dispatching events
   6. 4.6 Firing events
   7. 4.7 Mutation events
7. 5 Nodes
   1. 5.1 Nodes model
   2. 5.2 Interface Node
   3. 5.3 Interface Document
      1. 5.3.1 Interface DOMImplementation
   4. 5.4 Interface DocumentFragment
   5. 5.5 Interface DocumentType
   6. 5.6 Interface Element
      1. 5.6.1 Interface Attr
   7. 5.7 Interface CharacterData
   8. 5.8 Interface Text
   9. 5.9 Interface ProcessingInstruction
   10. 5.10 Interface Comment
8. 6 Ranges
   1. 6.1 Interface Range
9. 7 Traversal
   1. 7.1 Interface NodeIterator
   2. 7.2 Interface TreeWalker
   3. 7.3 Interface NodeFilter
10. 8 Collections
    1. 8.1 Interface NodeList
    2. 8.2 Interface HTMLCollection
11. 9 Lists
    1. 9.1 Interface DOMStringList
    2. 9.2 Interface DOMTokenList
    3. 9.3 Interface DOMSettableTokenList
12. 10 DOM features
13. 11 Historical
    1. 11.1 DOM Events
    2. 11.2 DOM Core
    3. 11.3 DOM Range
    4. 11.4 DOM Traversal
14. References
    1. Normative references
    2. Informative references
15. Acknowledgments

Goals

This specification will standardize the DOM platform. It does so as follows:

1. By consolidating DOM Level 3 Core [DOM3CORE], Element Traversal [ELEMENTTRAVERSAL], the "DOM Event Architecture" and "Basic Event Interfaces" chapters of DOM Level 3 Events [DOM3EVENTS] (specific type of events do not belong in the base specification), and DOM Level 2 Traversal and Range [DOM2TR], and do the following:

   • Align them with the needs of ECMAScript where possible.
   • Align them with existing implementations.
   • Simplify them as much as possible.

2. By moving features from HTML5 that ought to be part of the DOM platform here, while preventing a dependency on HTML5. [HTML]

3. By defining a replacement for "Mutation Events" as modification listeners are fundamental to the DOM.

   "Mutation Events" are expected to be removed from implementations in due course.

4. By defining new features that simplify common DOM operations.

Issues

• Mutation listeners (and updating the methods that mutate)
• Define event handlers. Define list of event handler IDL attributes? Define a concept for event handler content attributes?
• Move DOMStringMap here?
• replaceWholeText()

1 Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.

Unless otherwise stated, string comparisons are done in a case-sensitive manner.

1.1 Dependencies

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

Some of the terms used in this specification are defined in Web IDL, XML and Namespaces in XML. [WEBIDL] [XML] [XMLNS]

1.2 Extensibility

Vendor-specific proprietary extensions to this specification are strongly discouraged. Authors must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.

If vendor-specific extensions are needed, the members should be prefixed by vendor-specific strings to prevent clashes with future versions of this specification. Extensions must be defined so that the use of extensions neither contradicts nor causes the non-conformance of functionality defined in the specification.

When vendor-neutral extensions to this specification are needed, either this specification can be updated accordingly, or an extension specification can be written that overrides the requirements in this specification. When someone applying this specification to their activities decides that they will recognize the requirements of such an extension specification, it becomes an applicable specification for the purposes of conformance requirements in this specification.

2 Terminology

The term context object means the object on which the method or attribute being discussed was called. When the context object is unambiguous, the term can be omitted.

The preferred MIME name of a character encoding is the name or alias labeled as "preferred MIME name" in the IANA Character Sets registry, if there is one, or the encoding's name, if none of the aliases are so labeled. [IANACHARSET]

2.1 Trees

Just like most programming paradigms the Web platform has finite hierarchical tree structures, simply named trees. The tree order is preorder, depth-first traversal.

An object that participates in a tree has a parent, which is either another object or null, and an ordered list of zero or more child objects.

The root of an object is itself, if it has no parent, or else it is the root of its parent.

An object A is called a descendant of an object B, if either A is a child of B or A is a child of an object C that is a descendant of B.

An inclusive descendant is an object or one of its descendants.

An object A is called an ancestor of an object B if and only if B is a descendant of A.

An inclusive ancestor is an object or one of its ancestors.

An object A is called a sibling of an object B, if and only if B and A share the same non-null parent.

An object A is preceding an object B if A and B are in the same tree and A comes before B in tree order.

An object A is following an object B if A and B are in the same tree and A comes after B in tree order.

The first child of an object is its first child or null if it has no child.

The last child of an object is its last child or null if it has no child.

The previous sibling of an object is its first preceding sibling or null if it has no preceding sibling.

The next sibling of an object is its first following sibling or null if it has no following sibling.

The index of an object is its number of preceding siblings.

2.2 Strings

Comparing two strings in a case-sensitive manner means comparing them exactly, code point for code point.

Comparing two strings in a ASCII case-insensitive manner means comparing them exactly, code point for code point, except that the characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and the corresponding characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) are considered to also match.

Converting a string to ASCII uppercase means replacing all characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) with the corresponding characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z).

Converting a string to ASCII lowercase means replacing all characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) with the corresponding characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z).

A string pattern is a prefix match for a string s when pattern is not longer than s and truncating s to pattern's length leaves the two strings as matches of each other.

The space characters, for the purposes of this specification, are U+0020 SPACE, U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), U+000C FORM FEED (FF), and U+000D CARRIAGE RETURN (CR).

2.3 Common microsyntaxes

2.3.1 Common parser idioms

Some of the micro-parsers described below follow the pattern of having an input variable that holds the string being parsed, and having a position variable pointing at the next character to parse in input.

For parsers based on this pattern, a step that requires the user agent to collect a sequence of characters means that the following algorithm must be run, with characters being the set of characters that can be collected:

1. Let input and position be the same variables as those of the same name in the algorithm that invoked these steps.

2. Let result be the empty string.

3. While position does not point past the end of input and the character at position is one of the characters, append that character to the end of result and advance position to the next character in input.

4. Return result.

The step skip whitespace means that the user agent must collect a sequence of characters that are space characters. The collected characters are not used.

2.3.2 Space-separated tokens

A set of space-separated tokens is a string containing zero or more words (known as tokens) separated by one or more space characters, where words consist of any string of one or more characters, none of which are space characters.

A string containing a set of space-separated tokens may have leading or trailing space characters.

An unordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated.

An ordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated but where the order of the tokens is meaningful.

Sets of space-separated tokens sometimes have a defined set of allowed values. When a set of allowed values is defined, the tokens must all be from that list of allowed values; other values are non-conforming. If no such set of allowed values is provided, then all values are conforming.

How tokens in a set of space-separated tokens are to be compared (e.g. case-sensitively or not) is defined on a per-set basis.

2.4 Namespaces

The HTML namespace is http://www.w3.org/1999/xhtml.

The XML namespace is http://www.w3.org/XML/1998/namespace.

The XMLNS namespace is http://www.w3.org/2000/xmlns/.

3 Exceptions

3.1 Exception DOMException

exception DOMException {
  const unsigned short INDEX_SIZE_ERR = 1;
  const unsigned short DOMSTRING_SIZE_ERR = 2; // historical
  const unsigned short HIERARCHY_REQUEST_ERR = 3;
  const unsigned short WRONG_DOCUMENT_ERR = 4;
  const unsigned short INVALID_CHARACTER_ERR = 5;
  const unsigned short NO_DATA_ALLOWED_ERR = 6; // historical
  const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7;
  const unsigned short NOT_FOUND_ERR = 8;
  const unsigned short NOT_SUPPORTED_ERR = 9;
  const unsigned short INUSE_ATTRIBUTE_ERR = 10; // historical
  const unsigned short INVALID_STATE_ERR = 11;
  const unsigned short SYNTAX_ERR = 12;
  const unsigned short INVALID_MODIFICATION_ERR = 13;
  const unsigned short NAMESPACE_ERR = 14;
  const unsigned short INVALID_ACCESS_ERR = 15;
  const unsigned short VALIDATION_ERR = 16; // historical
  const unsigned short TYPE_MISMATCH_ERR = 17;
  const unsigned short SECURITY_ERR = 18;
  const unsigned short NETWORK_ERR = 19;
  const unsigned short ABORT_ERR = 20;
  const unsigned short URL_MISMATCH_ERR = 21;
  const unsigned short QUOTA_EXCEEDED_ERR = 22;
  const unsigned short TIMEOUT_ERR = 23;
  const unsigned short INVALID_NODE_TYPE_ERR = 24;
  const unsigned short DATA_CLONE_ERR = 25;
  unsigned short code;
  DOMString name;
};

The code exception field must return the code for the exception, which must be one of the following:

• INDEX_SIZE_ERR (1): the index is not in the allowed range;
• DOMSTRING_SIZE_ERR (2): the text does not fit in a DOMString (historical);
• HIERARCHY_REQUEST_ERR (3): the operation would yield an incorrect nodes model;
• WRONG_DOCUMENT_ERR (4): the object is in the wrong document;
• INVALID_CHARACTER_ERR (5): the string contains invalid characters;
• NO_DATA_ALLOWED_ERR (6): data is specified for an object that does not support it (historical);
• NO_MODIFICATION_ALLOWED_ERR (7): the object can not be modified;
• NOT_FOUND_ERR (8): the object can not be found here;
• NOT_SUPPORTED_ERR (9): this operation is not supported;
• INUSE_ATTRIBUTE_ERR (10): the attribute is in use (historical);
• INVALID_STATE_ERR (11): the object is in an invalid state;
• SYNTAX_ERR (12): the string did not match the expected pattern;
• INVALID_MODIFICATION_ERR (13): the object can not be modified in this way;
• NAMESPACE_ERR (14): the operation is not allowed by Namespaces in XML; [XMLNS]
• INVALID_ACCESS_ERR (15): the object does not support the operation or argument;
• VALIDATION_ERR (16): the operation is invalid (historical);
• TYPE_MISMATCH_ERR (17): the type of the object does not match the expected type;
• SECURITY_ERR (18): the operation is insecure;
• NETWORK_ERR (19): a network error occurred;
• ABORT_ERR (20): the user aborted an operation;
• URL_MISMATCH_ERR (21): the given URL does not match another URL;
• QUOTA_EXCEEDED_ERR (22): the quota has been exceeded;
• TIMEOUT_ERR (23): a timeout occurred;
• INVALID_NODE_TYPE_ERR (24): the supplied node is invalid or has an invalid ancestor for this operation;
• DATA_CLONE_ERR (25): the object can not be cloned.

The name exception field must return the name of the exception constant as a string.

When this specification requires that a user agent throw an exception named using a code listed above, it means that the user agent is required to create a DOMException exception object, with its code set to the given code, and then throw that object as defined in WebIDL. [WEBIDL]

This term is not hyperlinked because of its widespread use.

For example, to throw a TIMEOUT_ERR exception, a user agent would construct a DOMException object whose code was set to 23 and actually throw that object as an exception.

4 Events

4.1 Interface Event

[Constructor(DOMString type, optional EventInit eventInitDict)]
interface Event {
  readonly attribute DOMString type;
  readonly attribute EventTarget? target;
  readonly attribute EventTarget? currentTarget;

  const unsigned short CAPTURING_PHASE = 1;
  const unsigned short AT_TARGET = 2;
  const unsigned short BUBBLING_PHASE = 3;
  readonly attribute unsigned short eventPhase;

  void stopPropagation();
  void stopImmediatePropagation();

  readonly attribute boolean bubbles;
  readonly attribute boolean cancelable;
  void preventDefault();
  readonly attribute boolean defaultPrevented;

  readonly attribute boolean isTrusted;
  readonly attribute DOMTimeStamp timeStamp;

  void initEvent(DOMString type, boolean bubbles, boolean cancelable);
};

dictionary EventInit {
  boolean bubbles;
  boolean cancelable;
};

An event allows for signaling that something has occurred. E.g. that an image has completed downloading.

The type attribute must return the value it was initialized to. When an event is created the attribute must be initialized to the empty string.

The target and currentTarget attributes must return the values they were initialized to. When an event is created the attributes must be initialized to null.

The target and currentTarget attributes are initialized to different values while dispatching the event.

The eventPhase attribute must return the value it was initialized to, which must be one of the following:

CAPTURING_PHASE (numeric value 1)

When an event is dispatched on an object that participates in a tree it will be in this phase before it reaches its target attribute value.

AT_TARGET (numeric value 2)

When an event is dispatched it will be in this phase on its target attribute value.

BUBBLING_PHASE (numeric value 3)

When an event is dispatched on an object that participates in a tree it will be in this phase after it reaches its target attribute value.

Initially the attribute must be initialized to AT_TARGET.

Each event has the following associated flags that are all initially unset:

• stop propagation flag
• stop immediate propagation flag
• canceled flag
• initialized flag
• dispatch flag

When the stopPropagation() method is invoked the stop propagation flag must be set.

When the stopImmediatePropagation() method is invoked both the stop propagation flag and stop immediate propagation flag must be set.

The bubbles and cancelable attributes must return the values they were initialized to. When an event is created the attributes must be initialized to false.

When the preventDefault() method is invoked and the cancelable attribute is true, the canceled flag must be set.

The defaultPrevented attribute must return true if the canceled flag is set and false otherwise.

The isTrusted attribute must return the value it was initialized to. When an event is created the attribute must be initialized to false.

The timeStamp attribute must return the value it was initialized to. When an event is created the attribute must be initialized to the number of milliseconds that has passed since 00:00:00 UTC on 1 January 1970.

When the initEvent(type, bubbles, cancelable) method is invoked these steps must be run:

1. Set the initialized flag.

2. If the dispatch flag is set, terminate these steps.

3. Unset the stop propagation flag, stop immediate propagation flag, and canceled flag.

4. Set the isTrusted attribute to false.

5. Set the target attribute to null.

6. Set the type attribute to the type argument.

7. Set the bubbles attribute to the bubbles argument.

8. Set the cancelable attribute to the cancelable argument.

As events have constructors initEvent() is superfluous. However, it has to be supported for legacy content.

4.2 Interface CustomEvent

[Constructor(DOMString type, optional CustomEventInit eventInitDict)]
interface CustomEvent : Event {
  readonly attribute any detail;
};

dictionary CustomEventInit : EventInit {
  any detail;
}

Events using the CustomEvent interface can be used for synthetic events that need to carry data.

The detail attribute must return the value it was initialized to. When an event is created the attribute must be initialized to null.

4.3 Constructing events

When a constructor of the Event interface, or of an interface that inherits from the Event interface, is invoked, these steps must be run:

1. Create an event that uses the interface the constructor was invoked upon.

2. Set its initialized flag.

3. Initialize the type attribute to the type argument.

4. If there is an eventInitDict argument then for each dictionary member defined therein find the attribute on event whose identifier matches the key of the dictionary member and then set the attribute to the value of that dictionary member.

5. Return the event.

4.4 Interface EventTarget

interface EventTarget {
  void addEventListener(DOMString type, EventListener? listener, optional boolean capture);
  void removeEventListener(DOMString type, EventListener? listener, optional boolean capture);
  boolean dispatchEvent(Event event);
};

[Callback, NoInterfaceObject]
interface EventListener {
  void handleEvent(Event event);
};

EventTarget is an object upon which an event is dispatched when something has occurred. Each EventTarget has an associated list of event listeners.

An event listener is a handler for a specific event. Each event listener consists of a type (of the event), listener, and capture variable.

When the addEventListener(type, listener, capture) method is invoked these steps must be run:

1. If listener is null terminate these steps.

2. If capture is omitted let capture be false.

3. Append an event listener to the associated list of event listeners with type set to type, listener set to listener, and capture set to capture, unless there already is an event listener in that list with the same type, listener, and capture.

When the removeEventListener(type, listener, capture) method is invoked these steps must be run:

1. If capture is omitted let capture be false.

2. Remove an event listener from the associated list of event listeners, whose type is name, listener is listener, and capture is capture.

When the dispatchEvent(event) method is invoked these steps must be run:

1. If event's dispatch flag is set, or if its initialized flag is not set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Initialize event's isTrusted attribute to false.

3. Dispatch the event and return the value that returns.

4.5 Dispatching events

To dispatch an event on a given object run these steps:

1. Let event be the event that is dispatched.

2. Set event's dispatch flag.

3. Initialize event's target attribute to the object on which event is dispatched.

4. If event's target attribute value is participating in a tree

   1. Let event path be a static ordered list of all ancestors of event's target attribute value in tree order.

   2. Initialize event's eventPhase attribute to CAPTURING_PHASE.

   3. For each object in the event path invoke its event listeners, as long as event's stop propagation flag is unset.

   4. Initialize event's eventPhase attribute to AT_TARGET.

   5. Invoke the event listeners of event's target attribute value, if event's stop propagation flag is unset.

   6. If event's bubbles attribute is true run these substeps:

      1. Reverse the order of event path.

      2. Initialize event's eventPhase attribute to BUBBLING_PHASE.

      3. For each object in the event path invoke its event listeners, as long as event's stop propagation flag is unset.

   Otherwise

   Invoke the event listeners of event's target attribute value.

5. Unset event's dispatch flag.

6. Initialize event's eventPhase attribute to AT_TARGET.

7. Initialize event's currentTarget to null.

8. Return false if event's canceled flag is set and true otherwise.

To invoke the event listeners for an object run these steps:

1. Let event be the event for which the event listeners are invoked.

2. Let listeners be a static list of the event listeners associated with the object for which these steps are run.

3. Initialize event's currentTarget to the object for which these steps are run.

4. Then run these substeps for each event listener in listeners:

   1. If event's stop immediate propagation flag is set, terminate the invoke algorithm.

   2. Let listener be the event listener.

   3. If event's type attribute value is not listener's type, terminate these substeps (and run them for the next event listener).

   4. If event's eventPhase attribute value is CAPTURING_PHASE and listener's capture is false, terminate these substeps (and run them for the next event listener).

   5. If event's eventPhase attribute value is BUBBLING_PHASE and listener's capture is true, terminate these substeps (and run them for the next event listener).

   6. If listener's listener is a Function object, its callback this value is the event's target attribute value.

   7. Run listener's listener.

4.6 Firing events

To fire an event named e means that an event using the Event interface, with its type attribute initialized to e, and its isTrusted attribute initialized to true, is to be dispatched at the given object.

Fire is short for initializing and dispatching an event.

Fire an event is a concept to make initializing and dispatching an event easier to write down. If the event needs its bubbles or cancelable attribute initialized, one could write "fire an event named submit with its cancelable attribute initialized to true".

4.7 Mutation events

The status of mutation events is currently unclear. The editors hope they can eventually be removed from the platform. There is a proposal for a replacement. We encourage experimentation with that proposal, as well as alternative proposals.

5 Nodes

5.1 Nodes model

Objects implementing the Document, DocumentFragment, DocumentType, Element, Text, ProcessingInstruction, or Comment interface (simply called nodes) participate in a tree.

A tree of nodes is constrained as follows, expressed as a relationship between the type of node and its allowed children:

Document

In tree order:

1. Zero or more nodes each of which is either ProcessingInstruction or Comment.

2. Optionally one DocumentType node.

3. Zero or more nodes each of which is either ProcessingInstruction or Comment.

4. Optionally one Element node.

5. Zero or more nodes each of which is either ProcessingInstruction or Comment.

DocumentFragment

Element

Zero or more nodes each of which is one of Element, ProcessingInstruction, Comment, or Text.

DocumentType

Text

ProcessingInstruction

Comment

None.

The pre-insert and replace algorithms throw a HIERARCHY_REQUEST_ERR if the constraints listed above are violated. These algorithms are used by methods that manipulate the tree of nodes.

5.2 Interface Node

interface Node : EventTarget {
  const unsigned short ELEMENT_NODE = 1;
  const unsigned short ATTRIBUTE_NODE = 2; // historical
  const unsigned short TEXT_NODE = 3;
  const unsigned short CDATA_SECTION_NODE = 4; // historical
  const unsigned short ENTITY_REFERENCE_NODE = 5; // historical
  const unsigned short ENTITY_NODE = 6; // historical
  const unsigned short PROCESSING_INSTRUCTION_NODE = 7;
  const unsigned short COMMENT_NODE = 8;
  const unsigned short DOCUMENT_NODE = 9;
  const unsigned short DOCUMENT_TYPE_NODE = 10;
  const unsigned short DOCUMENT_FRAGMENT_NODE = 11;
  const unsigned short NOTATION_NODE = 12; // historical
  readonly attribute unsigned short nodeType;
  readonly attribute DOMString nodeName;

  readonly attribute DOMString? baseURI;

  readonly attribute Document? ownerDocument;
  readonly attribute Node? parentNode;
  readonly attribute Element? parentElement;
  boolean hasChildNodes();
  readonly attribute NodeList childNodes;
  readonly attribute Node? firstChild;
  readonly attribute Node? lastChild;
  readonly attribute Node? previousSibling;
  readonly attribute Node? nextSibling;

  const unsigned short DOCUMENT_POSITION_DISCONNECTED = 0x01;
  const unsigned short DOCUMENT_POSITION_PRECEDING = 0x02;
  const unsigned short DOCUMENT_POSITION_FOLLOWING = 0x04;
  const unsigned short DOCUMENT_POSITION_CONTAINS = 0x08;
  const unsigned short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
  const unsigned short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20; // historical
  unsigned short compareDocumentPosition(Node other);
  boolean contains(Node? other);

           attribute DOMString? nodeValue;
           attribute DOMString? textContent;
  Node insertBefore(Node node, Node? child);
  Node appendChild(Node node);
  Node replaceChild(Node node, Node child);
  Node removeChild(Node child);

  Node cloneNode(optional boolean deep);
  boolean isSameNode(Node? node);
  boolean isEqualNode(Node? node);

  DOMString lookupPrefix(DOMString? namespace);
  DOMString lookupNamespaceURI(DOMString? prefix);
  boolean isDefaultNamespace(DOMString? namespace);
};

Node is an abstract interface and does not exist as node. It is used by all nodes (Document, DocumentFragment, DocumentType, Element, Text, ProcessingInstruction, and Comment).

Each node has an associated node document, set upon creation, that is a document.

A node's node document can be changed by the "adopt" algorithm.

Each node also has an associated base URL.

Other specifications define the value of the base URL and its observable behavior. This specification solely defines the concept and the baseURI attribute.

node . nodeType

Returns the type of node, represented by a number from the following list:

Node . ELEMENT_NODE (1)

node is an element.

Node . TEXT_NODE (3)

node is a Text node.

Node . PROCESSING_INSTRUCTION_NODE (7)

node is a ProcessingInstruction node.

Node . COMMENT_NODE (8)

node is a Comment node.

Node . DOCUMENT_NODE (9)

node is a document.

Node . DOCUMENT_TYPE_NODE (10)

node is a doctype.

Node . DOCUMENT_FRAGMENT_NODE (11)

node is a DocumentFragment node.

node . nodeName

Returns a string appropriate for the type of node, as follows:

Element

Its tagName attribute value.

Text

"#text".

ProcessingInstruction

Its target.

Comment

"#comment".

Document

"#document".

DocumentType

Its name.

DocumentFragment

"#document-fragment".

The nodeType attribute must return the type of the node, which must be one of the following:

• ELEMENT_NODE (1);
• TEXT_NODE (3);
• PROCESSING_INSTRUCTION_NODE (7);
• COMMENT_NODE (8);
• DOCUMENT_NODE (9);
• DOCUMENT_TYPE_NODE (10);
• DOCUMENT_FRAGMENT_NODE (11).

The nodeName attribute must return the following, depending on the context object:

Element

Its tagName attribute value.

Text

"#text".

ProcessingInstruction

Its target.

Comment

"#comment".

Document

"#document".

DocumentType

Its name.

DocumentFragment

"#document-fragment".

node . baseURI

Returns the base URL.

The baseURI attribute must return the associated base URL.

doc = node . ownerDocument

Returns the node document.

parent = node . parentNode

Returns the parent.

parent = node . parentElement

Returns the parent element.

haschildren = node . hasChildNodes

Returns whether node has children.

children = node . childNodes

Returns the children.

child = node . firstChild

Returns the first child.

child = node . lastChild

Returns the last child.

child = node . previousSibling

Returns the previous sibling.

child = node . nextSibling

Returns the next sibling.

node . compareDocumentPosition(other)

Returns a bitmask indicating the position of other relative to node. These are the bits that can be set:

Node . DOCUMENT_POSITION_DISCONNECTED (1)

Set when node and other are not in the same document.

DOCUMENT_POSITION_PRECEDING (2)

Set when other is preceding node.

DOCUMENT_POSITION_FOLLOWING (4)

Set when other is following node.

DOCUMENT_POSITION_CONTAINS (8)

Set when other is an ancestor of node.

DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal)

Set when other is a descendant of node.

contains = node . contains(other)

Returns true if other is an inclusive descendant of node, or false otherwise.

These are the constants compareDocumentPosition() returns as mask:

• DOCUMENT_POSITION_DISCONNECTED (1);
• DOCUMENT_POSITION_PRECEDING (2);
• DOCUMENT_POSITION_FOLLOWING (4);
• DOCUMENT_POSITION_CONTAINS (8);
• DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal).

The compareDocumentPosition(other) method must run these steps:

1. Let reference be the context object.

2. If other and reference are the same object, return zero and terminate these steps.

3. If other and reference are not in the same tree, return DOCUMENT_POSITION_DISCONNECTED and terminate these steps.

4. If other is an ancestor of reference, return the result of adding DOCUMENT_POSITION_CONTAINS to DOCUMENT_POSITION_PRECEDING and terminate these steps.

5. If other is a descendant of reference, return the result of adding DOCUMENT_POSITION_CONTAINED_BY to DOCUMENT_POSITION_FOLLOWING and terminate these steps.

6. If other is preceding reference return DOCUMENT_POSITION_PRECEDING and terminate these steps.

7. Return DOCUMENT_POSITION_FOLLOWING.

The contains(other) method must return true if other is an inclusive descendant of the context object, or false otherwise.

The nodeValue attribute must return the following, depending on the context object:

Text

Comment

ProcessingInstruction

The context object's data.

Any other node

Null.

Setting the nodeValue attribute must do as described below, depending on the context object:

Text

Comment

ProcessingInstruction

Replace data with node context object, offset 0, count length attribute value, and data new value.

Any other node

Do nothing.

The textContent attribute must return the following, depending on the context object:

DocumentFragment

Element

The concatenation of data of all the Text node descendants of the context object, in tree order.

Text

ProcessingInstruction

Comment

The context object's data.

Any other node

Null.

The textContent attribute must, on setting, if the new value is null, act as if it was the empty string instead, and then do as described below, depending on the context object:

DocumentFragment

Element

1. Remove all the descendants of the context object.

2. Let data be the new value.

3. If data is not the empty string, append a new Text node to the context object whose data is set to data.

Text

ProcessingInstruction

Comment

Replace data with node context object, offset 0, count length attribute value, and data new value.

Any other node

Do nothing.

To pre-insert a node into a parent before a child, run these steps:

1. If child is not null and its parent is not parent, throw a NOT_FOUND_ERR exception and terminate these steps.

2. If node is parent or an ancestor of parent, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

3. If parent is not a Document, DocumentFragment, or Element node, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

4. If parent is a document, run these substeps:

   1. If node is not a DocumentFragment, DocumentType, Element, ProcessingInstruction, or Comment node, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

   2. If node is a DocumentFragment node, run these inner substeps:

      1. If node has more than one element child or has a Text node child, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

      2. If node has one element child and either parent has an element child or child is not null and a doctype is following child, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

   3. If node is an element and either parent has an element child or child is not null and a doctype is following child, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

   4. If node is a doctype and either parent has a doctype child, an element is preceding child, or child is null and parent has an element child.

5. Otherwise if parent is a DocumentFragment or Element node and node is not a DocumentFragment, Element, Text, ProcessingInstruction, or Comment node, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

6. Adopt node with parent's node document.

7. Insert node into parent before child.

8. Return child.

To insert a node into a parent before a child, run these steps:

1. Let count be the number of children of node if it is a DocumentFragment node, or one otherwise.

2. For each range whose start node is parent and start offset is greater than child's index, increase its start offset by count.

3. For each range whose end node is parent and end offset is greater than child's index, increase its end offset by count.

4. If node is a DocumentFragment node, insert its children (preserving tree order), before child or at the end of parent if child is null.

5. Otherwise insert node before child or at the end of parent if child is null.

The insertBefore(node, child) method must pre-insert node into the context object before child.

To append a node to a parent, pre-insert node into parent before null.

The appendChild(node) method must append node to the context object.

To replace a child with node within a parent, run these steps:

1. If child's parent is not parent, throw a NOT_FOUND_ERR exception and terminate these steps.

2. If node is parent or an ancestor of parent, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

3. If parent is not a Document, DocumentFragment, or Element node, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

4. If parent is a document, run these substeps:

   1. If node is not a DocumentFragment, DocumentType, Element, ProcessingInstruction, or Comment node, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

   2. If node is a DocumentFragment node, run these inner substeps:

      1. If node has more than one element child or has a Text node child, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

      2. If node has one element child and either parent has an element child that is not child or a doctype is following child, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

   3. If node is an element and either parent has an element child that is not child or a doctype is following child, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

   4. If node is a doctype and either parent has a doctype child that is not child, or an element is preceding child, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

5. Otherwise if parent is a DocumentFragment or Element node and node is not a DocumentFragment, Element, Text, ProcessingInstruction, or Comment node, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

6. Adopt node with parent's node document.

7. Let reference child be child's next sibling.

8. Remove child from its parent.

9. Insert node into parent before reference child.

10. Return child.

The replaceChild(node, child) method must replace child with node within the context object.

To pre-remove a node from a parent, run these steps:

1. If child's parent is not parent, throw a NOT_FOUND_ERR exception and terminate these steps.

2. Remove child from parent.

3. Return child.

To remove a node from a parent, run these steps:

1. Let index be node's index.

2. For each range whose start node is a descendant of parent, set its start to (parent, index).

3. For each range whose end node is a descendant of parent, set its end to (parent, index).

4. For each range whose start node is parent and start offset is greater than index, decrease its start offset by one.

5. For each range whose end node is parent and end offset is greater than index, decrease its end offset by one.

6. Remove node from its parent.

The removeChild(child) method must pre-remove child from the context object.

clone = node . cloneNode([deep])

Returns a copy of node. If deep is true or omitted, the copy also includes the node children.

same = node . isSameNode(other)

Returns whether node and other are the exact same node.

similar = node . isEqualNode(other)

Returns whether node and other have the same properties.

To locate a namespace prefix for an element using namespace run these steps:

1. If element's namespace is namespace and its namespace prefix is not null return its namespace prefix and terminate these steps.

2. If, in element's attributes, there is an attribute whose namespace prefix is "xmlns" and value is namespace then return that attribute's local name and terminate these steps.

3. If element's parent element is not null, return the result of running locate a namespace prefix on that element using namespace. Otherwise, return null.

To locate a namespace for a node using prefix depends on the node:

Element

1. If its namespace is not null and its namespace prefix is prefix return namespace and terminate these steps.

2. If, in its attributes, there is an attribute whose namespace prefix is "xmlns" and local name is prefix or whose namespace prefix is null and local name is "xmlns":

   1. Let value be its value if it is not the empty string, or null otherwise.

   2. Return value and terminate these steps.

3. Return the result of running locate a namespace on its parent element using prefix, if that is not null, or null otherwise.

Document

Return the result of running locate a namespace on its document element using prefix, if document element is not null, or null otherwise.

DocumentType

DocumentFragment

Return null.

Any other node

Return the result of running locate a namespace on its parent element using prefix, if that is not null, or null otherwise.

The lookupPrefix(namespace) method must run these steps:

1. If namespace is null or the empty string, return null.

2. Otherwise it depends on the context object:

   Element

   Return the result of locating a namespace prefix for the node using namespace.

   Document

   Return the result of locating a namespace prefix for its document element, if that is not null, or null otherwise.

   DocumentType

   DocumentFragment

   Return null.

   Any other node

   Return the result of locating a namespace prefix for its parent element, or if that is null, null.

The lookupNamespaceURI(prefix) method must return the result of running locate a namespace for the context object using prefix.

The isDefaultNamespace(namespace) method must run these steps:

1. If namespace is the empty string, set it to null.

2. Let defaultNamespace be the result of running locate a namespace for the context object using null.

3. Return true if defaultNamespace is the same as namespace, or false otherwise.

5.3 Interface Document

interface Document : Node {
  readonly attribute DOMImplementation implementation;
  readonly attribute DOMString URL;
  readonly attribute DOMString documentURI;
  readonly attribute DOMString compatMode;

           attribute DOMString charset;
  readonly attribute DOMString characterSet;
  readonly attribute DOMString defaultCharset;
  readonly attribute DOMString contentType;

  readonly attribute DocumentType? doctype;
  readonly attribute Element? documentElement;
  NodeList getElementsByTagName(DOMString qualifiedName);
  NodeList getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  NodeList getElementsByClassName(DOMString classNames);
  Element? getElementById(DOMString elementId);

  Element createElement([TreatNullAs=EmptyString] DOMString localName);
  Element createElementNS(DOMString? namespace, DOMString qualifiedName);
  DocumentFragment createDocumentFragment();
  Text createTextNode(DOMString data);
  Comment createComment(DOMString data);
  ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);

  Node importNode(Node node, optional boolean deep);
  Node adoptNode(Node node);

  Event createEvent(DOMString eventInterfaceName);

  Range createRange();

  NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow, optional NodeFilter? filter);
  TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow, optional NodeFilter? filter);
};

Document nodes are simply known as documents.

Each document has an associated character encoding, media type, and URL.

Unless explicitly given when a document is created its character encoding is "UTF-8", its media type is "application/xml", and its URL is "about:blank".

A document is assumed to be an XML document unless it is flagged as being an HTML document. Whether a document is an HTML document or an XML document affects the behavior of certain APIs.

A document is always set to one of three modes: no-quirks mode, the default; quirks mode, used typically for legacy documents; and limited-quirks mode, also known as "almost standards" mode. Unless other applicable specifications define otherwise, a document must be in no-quirks mode.

The mode is only ever changed from the default if the document is created by the HTML parser, based on the presence, absence, or value of the DOCTYPE string. [HTML]

document . implementation

Returns the associated DOMImplementation object.

document . URL

document . documentURI

Returns the URL.

document . compatMode

Returns the string "CSS1Compat" if document is in no-quirks mode or limited-quirks mode, and "BackCompat", if document is in quirks mode.

The implementation attribute must return the DOMImplementation object that is associated with the document.

The URL and documentURI attributes must return the URL.

The compatMode IDL attribute must return the literal string "CSS1Compat" unless the context object is in quirks mode, in which case it must instead return the literal string "BackCompat".

document . charset [ = value ]

Returns the character encoding.

Can be set, to change character encoding.

New values that are not IANA-registered aliases supported by the user agent are ignored.

document . characterSet

Returns the character encoding.

document . defaultCharset

Returns what might be the user agent's default character encoding. (The user agent might return another character encoding altogether, e.g. to protect the user's privacy, or if the user agent doesn't use a single default encoding.)

document . contentType

Returns the media type.

The charset attribute must return the preferred MIME name of the character encoding.

Setting the charset attribute must set character encoding to the new value if it is an IANA-registered alias for a character encoding supported by the user agent. (Otherwise, nothing happens.)

The characterSet attribute must return the preferred MIME name of the character encoding.

The defaultCharset attribute must return the preferred MIME name of a character encoding, possibly the user's default character encoding, or a character encoding associated with the user's current geographical location, or any arbitrary character encoding name.

The contentType attribute must return the media type.

document . doctype

Returns the doctype or null if there is none.

document . documentElement

Returns the document element.

collection = document . getElementsByTagName(localName)

If localName is "*" returns a NodeList of all descendant elements.

Otherwise, returns a NodeList of all descendant elements whose local name is localName. (Matches case-insensitively against elements in the HTML namespace within an HTML document.)

collection = document . getElementsByTagNameNS(namespace, localName)

If namespace and localName are "*" returns a NodeList of all descendant elements.

If only namespace is "*" returns a NodeList of all descendant elements whose local name is localName.

If only localName is "*" returns a NodeList of all descendant elements whose namespace is namespace.

Otherwise, returns a NodeList of all descendant elements whose namespace is namespace and local name is localName.

collection = document . getElementsByClassName(classes)

collection = element . getElementsByClassName(classes)

Returns a NodeList of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classes.

The classes argument is interpreted as a space-separated list of classes.

element = document . getElementById(elementId)

Returns the first element in document with the given ID.

The doctype attribute must return the child of the document that is a doctype, or null otherwise.

The documentElement attribute must return the document element.

The getElementsByTagName(localName) method must run these steps:

1. If localName is "*" (U+002A), return a NodeList rooted at the context object, whose filter matches only Element nodes.

2. Otherwise, if the context object is an HTML document, return a NodeList rooted at the context object, whose filter matches only the following nodes:

   • Element nodes in the HTML namespace whose local name is localName converted to ASCII lowercase.
   • Element nodes, not in the HTML namespace, whose local name is localName.

3. Otherwise, return a NodeList rooted at the context object, whose filter matches only elements whose local name is localName.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

Thus, in an HTML document, document.getElementsByTagName("FOO") will match FOO elements that are not in the HTML namespace, and foo elements that are in the HTML namespace, but not FOO elements that are in the HTML namespace.

The getElementsByTagNameNS(namespace, localName) method must run these steps:

1. If namespace is the empty string, set it to null.

2. If both namespace and localName are "*" (U+002A) return a NodeList rooted at the context object, whose filter matches only elements.

3. Otherwise, if just namespace is "*" (U+002A), return a NodeList rooted at the context object, whose filter matches only elements whose local name is localName.

4. Otherwise, if just localName is "*" (U+002A), return a NodeList rooted at the context object, whose filter matches only elements whose namespace is namespace.

5. Otherwise, return a NodeList rooted at the context object, whose filter matches only elements whose namespace is namespace and local name is localName.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

The getElementsByClassName(classNames) method must run these steps:

1. Let classes be the set of tokens found by splitting classNames on spaces. (Duplicates are ignored.)

2. If classes is the empty set, return an empty NodeList and terminate these steps.

3. Return a NodeList rooted at the context object, whose filter matches only elements that have all the classes in classes.

   If the context object is in quirks mode, then the comparisons for the classes must be done in an ASCII case-insensitive manner, otherwise, the comparisons must be done in a case-sensitive manner.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

<div id="example">
  <p id="p1" class="aaa bbb"/>
  <p id="p2" class="aaa ccc"/>
  <p id="p3" class="bbb ccc"/>
</div>

The getElementById(elementId) method must return the first element, in tree order, within the context object's tree, whose ID is elementId, or null if there is none.

element = document . createElement(localName)

Returns an element in the HTML namespace with localName as local name. (In an HTML document localName is lowercased.)

If localName does not match the Name production an INVALID_CHARACTER_ERR exception will be thrown.

element = document . createElementNS(namespace, qualifiedName)

Returns an element with namespace namespace. Its namespace prefix will be everything before ":" (U+003E) in qualifiedName or null. Its local name will be everything after ":" (U+003E) in qualifiedName or qualifiedName.

If localName does not match the Name production an INVALID_CHARACTER_ERR exception will be thrown.

If one of the following conditions is true a NAMESPACE_ERR exception will be thrown:

• localName does not match the QName production.
• Namespace prefix is not null and namespace is the empty string.
• Namespace prefix is "xml" and namespace is not the XML namespace.
• qualifiedName or namespace prefix is "xmlns" and namespace is not the XMLNS namespace.
• namespace is the XMLNS namespace and neither qualifiedName nor namespace prefix is "xmlns".

documentFragment = document . createDocumentFragment()

Returns a DocumentFragment node.

text = document . createTextNode(data)

Returns a Text node whose data is data.

comment = document . createComment(data)

Returns a Comment node whose data is data.

processingInstruction = document . createProcessingInstruction(target, data)

Returns a ProcessingInstruction node whose target is target and data is data.

If document is an HTML document a NOT_SUPPORTED_ERR exception will be thrown.

If target does not match the Name production an INVALID_CHARACTER_ERR exception will be thrown.

If data contains "?>" an INVALID_CHARACTER_ERR exception will be thrown.

The createElement(localName) method must run the these steps:

1. If localName does not match the Name production, throw an INVALID_CHARACTER_ERR exception and terminate these steps.

2. If the context object is an HTML document, let localName be converted to ASCII lowercase.

3. Return a new element with no attributes, namespace set to the HTML namespace, local name set to localName, and node document set to the context object.

The createElementNS(namespace, qualifiedName) method must run these steps:

1. If namespace is the empty string, set it to null.

2. If qualifiedName does not match the Name production, throw an INVALID_CHARACTER_ERR exception and terminate these steps.

3. If qualifiedName does not match the QName production, throw a NAMESPACE_ERR exception and terminate these steps.

4. If qualifiedName contains a ":" (U+003E), then split the string on it and let prefix be the part before and localName the part after. Otherwise, let prefix be null and localName be qualifiedName.

5. If prefix is not null and namespace is null, throw a NAMESPACE_ERR exception and terminate these steps.

6. If prefix is "xml" and namespace is not the XML namespace, throw a NAMESPACE_ERR exception and terminate these steps.

7. If qualifiedName or prefix is "xmlns" and namespace is not the XMLNS namespace, throw a NAMESPACE_ERR exception and terminate these steps.

8. If namespace is the XMLNS namespace and neither qualifiedName nor prefix is "xmlns", throw a NAMESPACE_ERR exception and terminate these steps.

9. Return a new element with no attributes, namespace set to namespace, namespace prefix set to prefix, local name set to localName, and node document set to the context object.

The createDocumentFragment() method must return a new DocumentFragment node with its node document set to the context object.

The createTextNode(data) method must return a new Text node with its data set to data and node document set to the context object.

No check is performed that data consists of characters that match the Char production.

The createComment(data) method must return a new Comment node with its data set to data and node document set to the context object.

No check is performed that data consists of characters that match the Char production or that it contains two adjacent hyphens or ends with a hyphen.

The createProcessingInstruction(target, data) method must run these steps:

1. If the context object is an HTML document, throw a NOT_SUPPORTED_ERR exception and terminate these steps.

2. If target does not match the Name production, throw an INVALID_CHARACTER_ERR exception and terminate these steps.

3. If data contains the string "?>", throw an INVALID_CHARACTER_ERR exception and terminate these steps.

4. Return a new ProcessingInstruction node, with target set to target, data set to data, and node document set to the context object.

No check is performed that target contains "xml" or ":", or that data contains characters that match the Char production.

clone = document . importNode(node [, deep])

Returns a copy of node. If deep is true or omitted, the copy also includes the node children.

If node is a document throws a NOT_SUPPORTED_ERR exception.

node = document . adoptNode(node)

Moves node from another document and returns it.

If node is a document throws a NOT_SUPPORTED_ERR exception.

The importNode(node, deep) method must run these steps:

1. If node is a document throw a NOT_SUPPORTED_ERR exception and terminate these steps.

2. Return a clone of node, with document context object and the clone children flag set if deep is true or omitted.

To adopt a node, with an ownerDocument, run these steps:

1. If node is an element, it is affected by a base URL change.

2. If node's parent is not null, remove node from its parent.

3. Set node document for node and all its descendants to ownerDocument.

The adoptNode(node) method must run these steps:

1. If node is a document throw a NOT_SUPPORTED_ERR exception and terminate these steps.

2. Adopt node with the context object and return it.

event = document . createEvent(eventInterfaceName)

Returns an event using an interface for which the interface name is a case-insensitive match for eventInterfaceName.

When the createEvent(eventInterfaceName) methed is invoked these steps must be run:

1. If eventInterfaceName is an ASCII case-insensitive match for any of the strings in the first column in the following table, let eventInterfaceName be the string in the second column on the same row as the matching string:

   Input interface	Replacement interface
   "htmlevents"	"event"
   "mouseevents"	"mouseevent"
   "mutationevents"	"mutationevent"
   "uievents"	"uievent"

2. If eventInterfaceName is not an ASCII case-insensitive match for "event" or for the name of an interface that inherits from the Event interface and is supported by the user agent, throw a NOT_SUPPORTED_ERR and terminate these steps.

3. Create an event implementing the interface whose name eventInterfaceName is an ASCII case-insensitive match for and return it.

This method is pretty much obsolete as events have constructors these days, but needs to be supported for legacy content. Tough.

event = document . createRange()

Returns a new range.

The createRange() method must return a new range with (context object, 0) as its start and end.

When the createNodeIterator(root, whatToShow, filter) method is invoked these steps must be run:

1. Create a NodeIterator object.

2. Set root and initialize the referenceNode attribute to the root argument.

3. Set whatToShow to the whatToShow argument, or to SHOW_ALL if omitted.

4. Set filter to filter, or to null if omitted.

5. Return the newly created NodeIterator object.

When the createTreeWalker(root, whatToShow, filter) method is invoked these steps must be run:

1. Create a TreeWalker object.

2. Set root and initialize the currentNode attribute to the root argument.

3. Set whatToShow to the whatToShow argument, or to SHOW_ALL if omitted.

4. Set filter to filter, or to null if omitted.

5. Return the newly created TreeWalker object.

5.3.1 Interface DOMImplementation

User agents must create a DOMImplementation object whenever a document is created and associate it with that document.

interface DOMImplementation {
  boolean hasFeature(DOMString feature, [TreatNullAs=EmptyString] DOMString version);

  DocumentType createDocumentType(DOMString qualifiedName, DOMString publicId, DOMString systemId);
  Document createDocument(DOMString? namespace, DOMString qualifiedName, DocumentType? doctype);
  Document createHTMLDocument(DOMString title);
};

hasSupport = document . implementation . hasFeature( feature, version )

Returns whether the user agent supports the version version of feature. The empty string means any version.

doctype = document . implementation . createDocumentType( qualifiedName, publicId, systemId )

Returns a doctype, with the given qualifiedName, publicId, and systemId. If qualifiedName does not match the Name production, an INVALID_CHARACTER_ERR exception is thrown, and if it does not match the QName production, a NAMESPACE_ERR exception is thrown.

doc = document . implementation . createDocument( namespace, qualifiedName, doctype )

Returns a document, with a document element whose local name is qualifiedName and whose namespace is namespace (unless qualifiedName is the empty string), and with doctype, if it is given, as its doctype.

This method throws the same exceptions as the createElementNS method, when invoked with the same arguments.

doc = document . implementation . createHTMLDocument( title )

Returns a document, with a basic tree already constructed including a title element.

5.4 Interface DocumentFragment

interface DocumentFragment : Node {
};

5.5 Interface DocumentType

interface DocumentType : Node {
  readonly attribute DOMString name;
  readonly attribute DOMString publicId;
  readonly attribute DOMString systemId;
};

DocumentType nodes are simply known as doctypes.

Doctypes have an associated name, public ID, and system ID.

When a doctype is created, its name is always given. Unless explicitly given when a doctype is created, its public ID and system ID are the empty string.

The name attribute must return the name.

The publicId attribute must return the public ID.

The systemId attribute must return the system ID.

5.6 Interface Element

interface Element : Node {
  readonly attribute DOMString? namespaceURI;
  readonly attribute DOMString? prefix;
  readonly attribute DOMString localName;
  readonly attribute DOMString tagName;

           attribute DOMString id;
           attribute DOMString className;
  readonly attribute DOMTokenList classList;

  readonly attribute Attr[] attributes;
  DOMString? getAttribute(DOMString qualifiedName);
  DOMString? getAttributeNS(DOMString? namespace, DOMString localName);
  void setAttribute(DOMString qualifiedName, DOMString value);
  void setAttributeNS(DOMString? namespace, DOMString qualifiedName, DOMString value);
  void removeAttribute(DOMString qualifiedName);
  void removeAttributeNS(DOMString? namespace, DOMString localName);
  boolean hasAttribute(DOMString qualifiedName);
  boolean hasAttributeNS(DOMString? namespace, DOMString localName);

  NodeList getElementsByTagName(DOMString qualifiedName);
  NodeList getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  NodeList getElementsByClassName(DOMString classNames);

  readonly attribute HTMLCollection children;
  readonly attribute Element? firstElementChild;
  readonly attribute Element? lastElementChild;
  readonly attribute Element? previousElementSibling;
  readonly attribute Element? nextElementSibling;
  readonly attribute unsigned long childElementCount;
};

Element nodes are simply known as elements.

Elements have an associated namespace, namespace prefix, local name.

When an element is created, its local name is always given. Unless explicitly given when an element is created, its namespace and namespace prefix are null.

Elements also have an associated list of attributes.

Elements can have a unique identifier (ID) and classes associated with them.

Whenever an attribute whose local name is id and namespace is null is set or modified on an element, the element's ID must be set to the attribute's value.

Whenever an attribute whose local name is class and namespace is null is set or modified on an element, the element's classes must be set to the attribute's value, split on spaces.

While this specification defines user agent processing requirements for id and class attributes on any element, it makes no claims as to whether using them is conforming or not.

A node's parent of type Element is known as a parent element. If the node has a parent of a different type, its parent element is null.

The document element of a document is the element whose parent is that document, if it exists, and null otherwise.

As explained in the Nodes model section, there can only be one such element.

When an element or one of its ancestors is the document element, it is in a document.

Specifications may define base URL change steps.

When an element is affected by a base URL change, the user agent must run the base URL change steps, as defined in other applicable specifications.

namespace = element . namespaceURI

Returns the namespace.

prefix = element . prefix

Returns the namespace prefix.

localName = element . localName

Returns the local name.

qualifiedName = element . tagName

If namespace prefix is not null returns the concatenation of namespace prefix, ":", and local name. Otherwise it returns the local name. (The return value is uppercased in an HTML document.)

The namespaceURI attribute must return the context object's namespace.

The prefix attribute must return the context object's namespace prefix.

The localName attribute must return the context object's local name.

The tagName attribute must run these steps:

1. If context object's namespace prefix is not null, let qualified name be its namespace prefix, followed by a ":" (U+003A), followed by its local name. Otherwise, let qualified name be its local name.

2. If the context object is in the HTML namespace and its node document is an HTML document, let qualified name be converted to ASCII uppercase.

3. Return qualified name.

Some IDL attributes are defined to reflect a particular content attribute. This means that on getting, the following steps must be run:

1. Let value be the result of invoking getAttribute() with the name of the content attribute as its argument.
2. If value is null, return the empty string and terminate these steps.
3. Return value.

On setting, the user agent must invoke setAttribute() with the name of the content attribute and the new value as its arguments.

The id attribute must reflect the "id" content attribute.

The className attribute must reflect the "class" content attribute.

The classList attribute must return a DOMTokenList whose underlying string is the className attribute value.

The attributes attribute must return a read only array of the context object's associated attributes. The returned read only array must be live. I.e. changes to the associated attributes are reflected.

The getAttribute(name) method must run these steps:

1. If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.

2. Return the value of the first attribute in the context object's attributes whose qualified name is name, or null otherwise.

The getAttributeNS(namespace, localName) method must return the following steps:

1. If namespace is the empty string, set it to null.

2. Return the value of the attribute in the context object's attributes whose namespace is namespace and local name is localName, if it has one, or null otherwise.

The setAttribute(qualifiedName, value) method must run these steps:

1. If qualifiedName does not match the Name production in XML, throw an INVALID_CHARACTER_ERR exception and terminate these steps.

2. If the context object is in the HTML namespace and its node document is an HTML document, let qualifiedName be converted to ASCII lowercase.

3. If "xmlns" is a prefix match for qualifiedName, throw a NAMESPACE_ERR and terminate these steps.

4. If the context object does not have an attribute whose qualified name is qualifiedName, create an attribute, whose local name is qualifiedName and value is value. Append this attribute to the context object's attributes.

5. Otherwise, set the value of the first attribute in the context object's attributes whose qualified name is qualifiedName, to value.

The setAttributeNS(namespace, qualifiedName, value) method must run these steps:

1. If namespace is the empty string, set it to null.

2. If qualifiedName does not match the Name production in XML, throw an INVALID_CHARACTER_ERR exception and terminate these steps.

3. If qualifiedName does not match the QName production in Namespaces in XML, throw a NAMESPACE_ERR exception and terminate these steps.

4. If qualifiedName contains a ":" (U+003E), then split the string on it and let prefix be the part before and localName the part after. Otherwise, let prefix be null and localName be qualifiedName.

5. If prefix is not null and namespace is null, throw a NAMESPACE_ERR exception and terminate these steps.

6. If prefix is "xml" and namespace is not the XML namespace, throw a NAMESPACE_ERR exception and terminate these steps.

7. If qualifiedName or prefix is "xmlns" and namespace is not the XMLNS namespace, throw a NAMESPACE_ERR exception and terminate these steps.

8. If namespace is the XMLNS namespace and neither qualifiedName nor prefix is "xmlns", throw a NAMESPACE_ERR exception and terminate these steps.

9. If the context object's attributes does not contain an attribute whose namespace is namespace and local name is localName, create an attribute, whose namespace is namespace, namespace prefix is prefix, local name is localName, and value is value. Append this attribute to the context object's attributes.

10. Otherwise, set the value of the attribute in the context object's attributes whose namespace is namespace, and local name is localName, to value, and set its namespace prefix to prefix.

The removeAttribute(qualifiedName) method must run these steps:

1. If the context object is in the HTML namespace and its node document is an HTML document, let qualifiedName be converted to ASCII lowercase.

2. Remove the first attribute in the context object's attributes whose qualified name is qualifiedName.

The removeAttributeNS(namespace, localName) method must return the following steps:

1. If namespace is the empty string, set it to null.

2. Remove the attribute in the context object's attributes whose namespace is namespace and local name is localName, if any.

The hasAttribute(qualifiedName) method must run these steps:

1. If the context object is in the HTML namespace and its node document is an HTML document, let qualifiedName be converted to ASCII lowercase.

2. Return true if context object's attributes contains an attribute whose qualified name is qualifiedName, or false otherwise.

The hasAttributeNS(namespace, localName) method must return the following steps:

1. If namespace is the empty string, set it to null.

2. Return true if context object's attributes contains an attribute whose namespace is namespace and local name is localName, or false otherwise.

When the getElementsByTagName(qualifiedName) method is invoked it must return a NodeList with the elements that the getElementsByTagName() method would return when called on the context object's node document and passed the same argument, excluding any elements that are not descendants of the context object on which the method was invoked.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

When the getElementsByTagNameNS(namespace, localName) method is invoked it must return a NodeList with the elements that the getElementsByTagNameNS() method would return when called on the context object's node document and passed the same arguments, excluding any elements that are not descendants of the context object on which the method was invoked.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

When the getElementsByClassName(classNames) method is invoked it must return a NodeList with the elements that the getElementsByClassName() method would return when called on the context object's node document and passed the same argument, excluding any elements that are not descendants of the context object on which the method was invoked.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

collection = element . children

Returns the child elements.

element = element . firstElementChild

Returns the first child that is an element, or null otherwise.

element = element . lastElementChild

Returns the last child that is an element, or null otherwise.

element = element . previousElementSibling

Returns the first preceding sibling that is an element, or null otherwise.

element = element . nextElementSibling

Returns the first following sibling that is an element, or null otherwise.

The children attribute must return an HTMLCollection collection rooted at the context object matching only element children.

The firstElementChild attribute must return the first child that is an element, or null otherwise.

The lastElementChild attribute must return the last child that is an element, or null otherwise.

The previousElementSibling attribute must return the first preceding sibling that is an element, or null otherwise.

The nextElementSibling attribute must return the first following sibling that is an element, or null otherwise.

The childElementCount attribute must return the number of children of the context object that are elements.

5.6.1 Interface Attr

interface Attr {
  readonly attribute DOMString? namespaceURI;
  readonly attribute DOMString? prefix;
  readonly attribute DOMString localName;
  readonly attribute DOMString name;
           attribute DOMString value;
};

Attr objects are simply known as attributes.

Just like elements, attributes have an associated namespace, namespace prefix, local name, and qualified name.

When an attribute is created, its local name is always given. Unless explicitly given when an attribute is created, its namespace and namespace prefix are null.

If an attribute's namespace prefix is not null, its qualified name is defined as its namespace prefix, followed by a ":" (U+003A), followed by its local name. Otherwise, its qualified name is defined as its local name.

Attributes also have an associated value, which is always given when an attribute is created.

The namespaceURI attribute must return the namespace.

The prefix attribute must return the namespace prefix.

The localName attribute must return the local name.

The name attribute must return the qualified name.

The value attribute must return the value.

Setting the value attribute must set value to the new value.

5.7 Interface CharacterData

interface CharacterData : Node {
  [TreatNullAs=EmptyString] attribute DOMString data;
  readonly attribute unsigned long length;
  DOMString substringData(unsigned long offset, unsigned long count);
  void appendData(DOMString data);
  void insertData(unsigned long offset, DOMString data);
  void deleteData(unsigned long offset, unsigned long count);
  void replaceData(unsigned long offset, unsigned long count, DOMString data);
};

CharacterData is an abstract interface and does not exist as node. It is used by Text, Comment, and ProcessingInstruction nodes.

Each node inheriting from the CharacterData interface has an associated mutable string called data.

To replace data of node node with offset offset, count count, and data data, run these steps:

1. Let length be the node's length attribute value.

2. If offset is greater than length, throw an INDEX_SIZE_ERR exception and terminate these steps.

3. If offset plus count is greater than length let count be length minus offset.

4. Insert data into node's data after offset code units.

5. Let delete offset be offset plus the number of code units in data.

6. Starting from delete offset code units, remove count code units from node's data.

7. For each range whose start node is node and start offset is greater than offset but less than or equal to offset plus count, set its start offset to offset.

8. For each range whose end node is node and end offset is greater than offset but less than or equal to offset plus count, set its end offset to offset.

9. For each range whose start node is node and start offset is greater than offset plus count, increase its start offset by the number of code units in data, then decrease it by count.

10. For each range whose start node is node and start offset is greater than offset plus count, increase its start offset by the number of code units in data, then decrease it by count.

To substring data with node node, offset offset, and count count, run these steps:

1. Let length be node's length attribute value.

2. If offset is greater than length, throw an INDEX_SIZE_ERR exception and terminate these steps.

3. If offset plus count is greater than length, return a string whose value is the code units from the offset^th code unit to the end of node's data, and then terminate these steps.

4. Return a string whose value is the code units from the offset^th code unit to the offset+count^th code unit in node's data.

The data attribute must return data, and on setting, must replace data with node context object offset 0, count length attribute value, and data new value.

The length attribute must return the number of code units in data.

The substringData(offset, count) method must substring data with node context object, offset offset, and count count.

The appendData(data) method must replace data with node context object, offset length attribute value, count 0, and data data.

The insertData(offset, data) method must replace data with node context object, offset offset, count 0, and data data.

The deleteData(offset, count) method must replace data with node context object, offset offset, count count, and data the empty string.

The replaceData(offset, count, data) method must replace data with node context object, offset offset, count count, and data data.

5.8 Interface Text

interface Text : CharacterData {
  Text splitText(unsigned long offset);
  readonly attribute DOMString wholeText;
  Text? replaceWholeText(DOMString data);
};

To split a Text node node with offset offset, run these steps:

1. Let length be the length attribute value.

2. If offset is greater than length, throw an INDEX_SIZE_ERR exception and terminate these steps.

3. Let count be length minus offset.

4. Let new data be the result of substringing data with node node, offset offset, and count count.

5. Replace data with node node, offset offset, count count, and data the empty string.

6. Let new node be a new Text node, with the same node document as node. Set new node's data to new data.

7. Let parent be the node's parent.

8. If parent is null, run these substeps:

   1. For each range whose start node is node, start offset is greater than or equal to offset, and end offset is greater than offset, set both its start node and end node to new node and decrease its start offset and end offset by offset.

   2. For each range whose end node is node and end offset is greater than offset, set its end offset is offset.

   3. Return new node and terminate these steps.

9. For each range whose start node is node and start offset is greater than offset, set its start node to new node and decrease its start offset by offset.

10. For each range whose end node is node and end offset is greater than offset, set its end node to new node and decrease its end offset by offset.

11. Insert new node into parent before node's next sibling.

12. Return new node.

The splitText(offset) method must split the context object with offset offset.

The contiguous Text nodes of a node are the node itself, the previous sibling Text node (if any) and its contiguous Text nodes, and the next sibling Text node (if any) and its contiguous Text nodes, avoiding any duplicates.

The wholeText attribute must return a concatenation of the data of the contiguous Text nodes of the context object, in tree order.

The replaceWholeText(data) method must run these steps:

1. Remove the contiguous Text nodes of the context object, in tree order, except for the context object itself if data is not the empty string.

2. If data is not the empty string, replace data with node context object, offset 0, count length attribute value, and data data, return the context object, and then terminate these steps.

3. Return null.

Can we remove replaceWholeText() in favor of making wholeText no longer readonly? Do we even need this wholeText business?

5.9 Interface ProcessingInstruction

interface ProcessingInstruction : CharacterData {
  readonly attribute DOMString target;
};

ProcessingInstruction nodes have an associated target.

The target attribute must return the target.

5.10 Interface Comment

interface Comment : CharacterData {
};

6 Ranges

The length of a node node depends on node:

DocumentType

0.

Text

ProcessingInstruction

Comment

Its length attribute value.

Any other node

Its number of children.

6.1 Interface Range

interface Range {
  readonly attribute Node startContainer;
  readonly attribute unsigned long startOffset;
  readonly attribute Node endContainer;
  readonly attribute unsigned long endOffset;
  readonly attribute boolean collapsed;
  readonly attribute Node commonAncestorContainer;

  void setStart(Node refNode, unsigned long offset);
  void setEnd(Node refNode, unsigned long offset);
  void setStartBefore(Node refNode);
  void setStartAfter(Node refNode);
  void setEndBefore(Node refNode);
  void setEndAfter(Node refNode);
  void collapse(boolean toStart);
  void selectNode(Node refNode);
  void selectNodeContents(Node refNode);

  enum CompareHow : unsigned short {
    START_TO_START = 0,
    START_TO_END   = 1,
    END_TO_END     = 2,
    END_TO_START   = 3
  };

  short compareBoundaryPoints(CompareHow how, Range sourceRange);
  void deleteContents()
  DocumentFragment extractContents();
  DocumentFragment cloneContents();
  void insertNode(Node newNode);
  void surroundContents(Node newParent);
  Range cloneRange();
  void detach();

  boolean isPointInRange(Node parent, unsigned long offset);
  short comparePoint(Node parent, unsigned long offset);

  boolean intersectsNode(Node node);

  stringifier;
};

Range objects are simply known as ranges.

Ranges can be created using the createRange() method.

A boundary point is a (node, offset) tuple, where offset is a non-negative integer.

Generally speaking, a boundary point's offset will be between zero and the boundary point's node length, inclusive. Algorithms that modify a tree (in particular the insert, remove, replace data, and split algorithms) also modify ranges associated with that tree.

If the two nodes of boundary points (node A, offset A) and (node B, offset B) have the same root, the position of the first relative to the second is either before, equal, or after, as returned by the following algorithm:

1. If node A is the same as node B, return equal if offset A is the same as offset B, before if offset A is less than offset B, and after if offset A is greater than offset B.

2. If node A is following node B, compute the position of (node B, offset B) relative to (node A, offset A). If it is before, return after. If it is after, return before. In either case terminate these steps.

3. If node A is an ancestor of node B:

   1. Let child equal node B.

   2. While child is not a child of node A, set child to its parent.

   3. If the index of child is less than offset A, return after.

4. Return before.

Each range has two associated boundary points — a start and end — an associated detached flag, which is initially unset.

For convenience, start node is start's node, start offset is start's offset, end node is end's node, and end offset is end's offset.

The root of a range is the root of its start node, or null if its detached flag is set.

A node node is contained in a range range if node's root is the same as range's root, and (node, 0) is after range's start, and (node, length of node) is before range's end.

A node is partially contained in a range if it is an inclusive ancestor of the range's start node but not its end node, or vice versa.

node = range . startContainer

Returns range's start node.

offset = range . startOffset

Returns range's start offset.

node = range . endContainer

Returns range's end node.

offset = range . endOffset

Returns range's end offset.

collapsed = range . collapsed

Returns true if range's start and end are the same, or false otherwise.

container = range . commonAncestorContainer

Returns the node, furthest away from the document, that is an ancestor of both range's start node and end node.

The startContainer attribute must return the start node, unless the detached flag is set, in which case an INVALID_STATE_ERR exception must be thrown.

The startOffset attribute must return the start offset, unless the detached flag is set, in which case an INVALID_STATE_ERR exception must be thrown.

The endContainer attribute must return the end node, unless the detached flag is set, in which case an INVALID_STATE_ERR exception must be thrown.

The endOffset attribute must return the end offset, unless the detached flag is set, in which case an INVALID_STATE_ERR exception must be thrown.

The collapsed attribute must return true if start equals end, or false otherwise, unless the detached flag is set, in which case an INVALID_STATE_ERR exception must be thrown.

The commonAncestorContainer attribute must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let container be start node.

3. While container is not an inclusive ancestor of end node, let container be container's parent.

4. Return container.

To set the start or end of a range to a boundary point (node, offset), run these steps:

1. If range's detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. If node is a doctype, throw an INVALID_NODE_TYPE_ERR exception and terminate these steps.

3. If offset is greater than node's length, throw an INDEX_SIZE_ERR exception and terminate these steps.

4. Let bp be the boundary point (node, offset).

5. If these steps were invoked as "set the start"

   1. If bp is after the range's end, or if the range's root is not equal to node's root, set range's end to bp.

   2. Set range's start to bp.

   If these steps were invoked as "set the end"

   1. If bp is before the range's start, or if the range's root is not equal to node's root, set range's start to bp.

   2. Set range's end to bp.

The setStart(node, offset) method must set the start of the context object to boundary point (node, offset).

The setEnd(refNode, offset) method must set the end of the context object to boundary point (node, offset).

The setStartBefore(node) method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let parent be node's parent.

3. If parent is null, throw an INVALID_NODE_TYPE_ERR exception and terminate these steps.

4. Set the start of the context object to boundary point (parent, node's index).

The setStartAfter(node) method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let parent be node's parent.

3. If parent is null, throw an INVALID_NODE_TYPE_ERR exception and terminate these steps.

4. Set the start of the context object to boundary point (parent, node's index plus one).

The setEndBefore(node) method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let parent be node's parent.

3. If parent is null, throw an INVALID_NODE_TYPE_ERR exception and terminate these steps.

4. Set the end of the context object to boundary point (parent, node's index).

The setEndAfter(node) method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let parent be node's parent.

3. If parent is null, throw an INVALID_NODE_TYPE_ERR exception and terminate these steps.

4. Set the end of the context object to boundary point (parent, node's index plus one).

The collapse(toStart) method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. If toStart is true, set end to start. Otherwise, set start to end.

The selectNode(refNode) method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let parent be refNode's parent.

3. If parent is null, throw an INVALID_NODE_TYPE_ERR and terminate these steps.

4. Let index be the index of refNode.

5. Set start to the boundary point (parent, index).

6. Set end to the boundary point (parent, index plus one).

The selectNodeContents(refNode) method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. If refNode is a doctype, throw an INVALID_NODE_TYPE_ERR and terminate these steps.

3. Let length be the length of refNode.

4. Set start to the boundary point (refNode, 0).

5. Set end to the boundary point (refNode, length).

The compareBoundaryPoints(how, sourceRange) method must run these steps:

1. If context object's or sourceRange's detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. If context object's root is not the same as sourceRange's root, throw a WRONG_DOCUMENT_ERR exception and terminate these steps.

3. If how is:

   START_TO_START:

   Let this point be the context object's start.

   Let other point be sourceRange's start.

   START_TO_END:

   Let this point be the context object's start.

   Let other point be sourceRange's end.

   END_TO_END:

   Let this point be the context object's end.

   Let other point be sourceRange's end.

   END_TO_END:

   Let this point be the context object's end.

   Let other point be sourceRange's start.

4. If the position of this point relative to other point is

   "before"

   Return −1 and terminate these steps.

   "equal"

   Return 0 and terminate these steps.

   "after"

   Return 1 and terminate these steps.

The deleteContents() method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. If start equals end, terminate these steps.

3. Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.

4. If original start node and original end node are the same, and they are a Text or Comment node, replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string, and then terminate these steps.

5. Let nodes to remove be a list of all the nodes that are contained in the context object, in tree order, omitting any node whose parent is also contained in the context object.

6. If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.

7. Otherwise:

   1. Let reference node equal original start node.

   2. While reference node's parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent.

   3. Set new node to the parent of reference node, and new offset to one plus the index of reference node.

      If reference node's parent were null, it would be the root of the context object, so would be an inclusive ancestor of original end node, and we could not reach this point.

8. If original start node is a Text or Comment node, replace data with node original start node, offset original start offset, count original start node's length minus original start offset, data the empty string.

9. For each node in nodes to remove, in order, remove node from its parent.

10. If original end node is a Text or Comment node, replace data with node original end node, offset 0, count original end offset), and data the empty string.

11. Set start and end to (new node, new offset).

The extractContents() method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let frag be a new DocumentFragment whose node document is the same as the node document of the context object's start node.

3. If start equals end, return frag, and terminate these steps.

4. Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.

5. If original start node equals original end node, and they are a Text or Comment node:

   1. Let clone be a clone of original start node.

   2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.

   3. Append clone to frag.

   4. Replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string.

   5. Return frag and terminate these steps.

6. Let common ancestor be original start node.

7. While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.

8. If original start node is an inclusive ancestor of original end node, let first partially contained child be null.

9. Otherwise, let first partially contained child be the first child of common ancestor that is partially contained in the context object.

10. If original end node is an inclusive ancestor of original start node, let last partially contained child be null.

11. Otherwise, let last partially contained child be the last child of common ancestor that is partially contained in the context object.

    These variable assignments do actually always make sense. For instance, if the original start node is not an inclusive ancestor of the original end node, the original start node is itself partially contained in the range, and so are all its ancestors up until a child of the common ancestor. The common ancestor can't be original start node, because it must be an inclusive ancestor of the original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.

12. Let contained children be a list of all children of common ancestor that are contained in the context object, in tree order.

13. If any member of contained children is a DocumentType, throw a HIERARCHY_REQUEST_ERR exception and terminate these steps.

    We do not have to worry about the first or last partially contained node, because a DocumentType can never be partially contained. It cannot be a boundary point of a range, and it cannot be the ancestor of anything.

14. If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.

15. Otherwise:

    1. Let reference node equal original start node.
    2. While reference node's parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent.
    3. Set new node to the parent of reference node, and new offset to one plus the index of reference node.

       If reference node's parent were null, it would be the root of the context object, so would be an inclusive ancestor of original end node, and we couldn't reach this point.

16. If first partially contained child is a Text or Comment node:

    In this case, the first partially contained child is the original start node.

    1. Let clone be a clone of original start node.

    2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node's length minus original start offset.

    3. Append clone to frag.

    4. Replace data with node original start node, offset original start offset, count original start node's length minus original start offset, and data the empty string.

17. Otherwise, if first partially contained child is not null:

    1. Let clone be a clone of first partially contained child.

    2. Append clone to frag.

    3. Let subrange be a new Range whose start is (original start node, original start offset) and whose end is (first partially contained child, length of first partially contained child).
    4. Let subfrag be the result of calling extractContents() on subrange.

       Is this method of recursing black-box detectable? E.g., would it fire extra DOM mutation events or something? What we really mean is to get a list of nodes to insert, then insert them directly into frag, without an intermediate document fragment.

    5. For each child of subfrag, in order, append that child to clone.

18. For each contained child in contained children, append contained child to frag.

19. If last partially contained child is a Text or Comment node:

    In this case, the last partially contained child is the original end node.

    1. Let clone be a clone of original end node.

    2. Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.

    3. Append clone to frag.

    4. Replace data with node original end node, offset 0, count original end offset, and data the empty string.

20. Otherwise, if last partially contained child is not null:

    1. Let clone be a clone of last partially contained child.

    2. Append clone to frag.

    3. Let subrange be a new Range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
    4. Let subfrag be the result of calling extractContents() on subrange.

    5. For each child of subfrag, in order, append that child to clone.

21. Set start and end to (new node, new offset).

22. Return frag.

The cloneContents() method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let frag be a new DocumentFragment whose node document is the same as the node document of the context object's start node.

3. If start equals end, return frag, and terminate these steps.

4. Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.

5. If original start node equals original end node, and they are a Text or Comment node:

   1. Let clone be a clone of original start node.

   2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.

   3. Append clone to frag.

   4. Return frag and terminate these steps.

6. Let common ancestor be original start node.

7. While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.

8. If original start node is an inclusive ancestor of original end node, let first partially contained child be null.

9. Otherwise, let first partially contained child be the first child of common ancestor that is partially contained in the context object.

10. If original end node is an inclusive ancestor of original start node, let last partially contained child be null.

11. Otherwise, let last partially contained child be the last child of common ancestor that is partially contained in the context object.

    These variable assignments do actually always make sense. For instance, if the original start node is not an inclusive ancestor of the original end node, the original start node is itself partially contained in the range, and so are all its ancestors up until a child of the common ancestor. The common ancestor can't be original start node, because it must be an inclusive ancestor of the original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.

12. Let contained children be a list of all children of common ancestor that are contained in the context object, in tree order.

13. If any member of contained children is a DocumentType, throw a HIERARCHY_REQUEST_ERR exception and terminate these steps.

    We don't have to worry about the first or last partially contained node, because a DocumentType can never be partially contained. It can't be a boundary point of a range, and it can't be the ancestor of anything.

14. If first partially contained child is a Text or Comment node:

    In this case, the first partially contained child is the original start node.

    1. Let clone be a clone of original start node.

    2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node's length minus original start offset.

    3. Append clone to frag.

15. Otherwise, if first partially contained child is not null:

    1. Let clone be a clone of first partially contained child.

    2. Append clone to frag.

    3. Let subrange be a new Range whose start is (original start node, original start offset) and whose end is (first partially contained child, length of first partially contained child).
    4. Let subfrag be the result of calling cloneContents() on subrange.

       Is this method of recursing black-box detectable? E.g., would it fire extra DOM mutation events or something? What we really mean is to get a list of nodes to insert, then insert them directly into frag, without an intermediate document fragment.

    5. For each child of subfrag, in order, append that child to clone.

16. For each contained child in contained children:

    1. Let clone be a clone of contained child.

    2. Append clone to frag.

17. If last partially contained child is a Text or Comment node:

    In this case, the last partially contained child is the original end node.

    1. Let clone be a clone of original end node.

    2. Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.

    3. Append clone to frag.

18. Otherwise, if last partially contained child is not null:

    1. Let clone be a clone of last partially contained child.

    2. Append clone to frag.

    3. Let subrange be a new Range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
    4. Let subfrag be the result of calling cloneContents() on subrange.

    5. For each child of subfrag, in order, append that child to clone.

19. Return frag.

The insertNode(newNode) method must run these steps:

Browsers disagree on how to handle the case where the range is collapsed: do you increment the end offset so the node is now included, or not? DOM 2 Range says no, and Gecko follows that, but all other browsers disagree. Apparently this traces back to Acid3 at one point requiring the non-standard behavior. As of June 2011, smaug is checking with other browsers' implementers to see if they're willing to change to match the spec; otherwise the spec needs to be changed to match them.

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. If start node is a Text or Comment node and its parent is null, throw an HIERARCHY_REQUEST_ERR exception and terminate these steps.

3. If start node is a Text node, split it with offset context object's start offset, and let reference node be the result.

4. Otherwise, if start node is a Comment node, let reference node be the start node.

5. Otherwise, let reference node be the child of start node whose index is start offset, or null if there is no such child.

6. If reference node is null, let parent node be start node.

7. Otherwise, let parent node be the parent of reference node.

8. Pre-insert newNode into parent node before reference node.

The surroundContents(newParent) method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. If a non-Text node is partially contained in the context object, throw a INVALID_STATE_ERR exception and terminate these steps.

3. If newParent is a Document, DocumentType, or DocumentFragment node, throw an INVALID_NODE_TYPE_ERR exception and terminate these steps.

4. Call extractContents() on the context object, and let fragment be the result.

5. While newParent has children, remove its first child.

6. Call insertNode(newParent) on the context object.
7. Call appendChild(fragment) on newParent.
8. Call selectNode(newParent) on the context object.

The cloneRange() method must throw an INVALID_STATE_ERR exception if the detached flag is set. Otherwise, it must return a new range with the same start and end as the context object.

The detach() method must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Set the detached flag.

position = range . comparePoint( parent, offset )

Returns −1 if the point is before the range, 0 if the point is in the range, and 1 if the point is after the range.

intersects = range . intersectsNode( node )

Returns whether range intersects node.

The stringifier must run these steps:

1. If the detached flag is set, throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let s be the empty string.

3. If start node equals end node, and it is a Text node, return the substring of that Text node's data beginning at start offset and ending at end offset, and terminate these steps.

4. If start node is a Text node, append to s the substring of that node's data from the start offset until the end.

5. Append to s the concatenation, in tree order, of the data of all Text nodes that are contained in the context object.

6. If end node is a Text node, append to s the substring of that node's data from its start until the end offset.

7. Return s.

7 Traversal

NodeIterator and TreeWalker objects can be used to filter and traverse node trees.

Each NodeIterator and TreeWalker object has an associated active flag to avoid recursive invocations. It is initially unset.

Each NodeIterator and TreeWalker object also has an associated root node, whatToShow bitmask, and filter callback.

To filter node run these steps:

1. If active flag is set throw an INVALID_STATE_ERR, terminate these steps, and terminate the steps of the algorithm that invoked this algorithm.

2. Let n be node's nodeType attribute value minus 1.

3. If the n^th bit (where 0 is the least significant bit) of whatToShow is not set, return FILTER_SKIP and terminate these steps.

4. If filter is null return FILTER_ACCEPT and terminate these steps.

5. Set the active flag.

6. Let result be the return value of invoking filter.

7. Unset the active flag.

8. If an exception was thrown, re-throw the exception, terminate these steps, and terminate the steps of the algorithm that invoked this algorithm.

9. Return result.

7.1 Interface NodeIterator

interface NodeIterator {
  readonly attribute Node root;
  readonly attribute Node? referenceNode;
  readonly attribute boolean pointerBeforeReferenceNode;
  readonly attribute unsigned long whatToShow;
  readonly attribute NodeFilter? filter;

  Node? nextNode();
  Node? previousNode();

  void detach();
};

NodeIterator objects can be created using the createNodeIterator() method.

Each NodeIterator object has an associated iterator collection, which is a collection rooted at root, whose filter matches any node.

Before a node is removed from the iterator collection, these steps must be run:

1. If the node is not a descendant of root and is not an ancestor of the referenceNode attribute value or the referenceNode attribute value itself, terminate these steps.

2. If the pointerBeforeReferenceNode attribute value is false, set the referenceNode attribute to the first node preceding the node that is being removed, and terminate these steps.

3. If the pointerBeforeReferenceNode attribute value is true and there is a node following the node that is being removed, set the referenceNode attribute to the first such node, and terminate these steps.

4. Set the referenceNode attribute to the first node preceding the node that is being removed and set the pointerBeforeReferenceNode attribute to false.

Each NodeIterator object also has an associated detached flag which is initially unset.

As mentioned earlier NodeIterator objects have an associated active flag, root node, whatToShow bitmask, and filter callback as well.

The root attribute must return root.

The referenceNode attribute must return what it was initialized to.

The pointerBeforeReferenceNode attribute must return what it was initialized to. When a NodeIterator is created it must be initialized to true.

The whatToShow attribute must return whatToShow.

The filter attribute must return filter.

To traverse in direction direction run these steps:

1. If the detached flag is set throw an INVALID_STATE_ERR exception and terminate these steps.

2. Let node be the value of the referenceNode attribute.

3. Let before node be the value of the pointerBeforeReferenceNode attribute.

4. Run these substeps:

   1. If direction is next

      If before node is false, let node be the first node following node in the iterator collection. If there is no such node return null and terminate these steps.

      If before node is true, set it to false.

      If direction is previous

      If before node is true, let node be the first node preceding node in the iterator collection. If there is no such node return null and terminate these steps.

      If before node is false, set it to true.

   2. Filter node and let result be the return value.

   3. If the detached flag is set throw an INVALID_STATE_ERR exception and terminate these steps.

   4. If result is FILTER_ACCEPT, go to the next step in the overall set of steps.

      Otherwise, run these substeps again.

5. Set the referenceNode attribute to node, set the pointerBeforeReferenceNode attribute to before node, and return node.

The nextNode() method must traverse in direction next.

The previousNode() method must traverse in direction previous.

When the detach() method is invoked set the detached flag and set the referenceNode attribute to null.

7.2 Interface TreeWalker

interface TreeWalker {
  readonly attribute Node root;
  readonly attribute unsigned long whatToShow;
  readonly attribute NodeFilter? filter;
           attribute Node currentNode;

  Node? parentNode();
  Node? firstChild();
  Node? lastChild();
  Node? previousSibling();
  Node? nextSibling();
  Node? previousNode();
  Node? nextNode();
};

TreeWalker objects can be created using the createTreeWalker() method.

As mentioned earlier TreeWalker objects have an associated active flag, root node, whatToShow bitmask, and filter callback.

The root attribute must return root.

The whatToShow attribute must return whatToShow.

The filter attribute must return filter.

The currentNode attribute must return what it was initialized to.

Setting the currentNode attribute must set it to the new value.

The parentNode() method must run these steps:

1. Let node be the value of the currentNode attribute.

2. While node is not null and is not root, run these substeps:

   1. Let node be node's parent.

   2. If node is not null and filtering node returns FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

3. Return null.

To traverse children of type type run these steps:

1. Let node and current be the value of the currentNode attribute.

2. While node is not null, run these substeps:

   1. Filter node and let result be the return value.

   2. If result is FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

   3. If result is FILTER_SKIP and node has a child, then set node as follows and run these substeps again:

      If type is first

      Set it to the first child

      If type is last

      Set it to the last child

   4. While node is not null, run these inner substeps:

      1. If type is first

         Let sibling be the next sibling of node.

         If type is last

         Let sibling be the previous sibling of node.

      2. If sibling is not null, set node to it and terminate these inner substeps.

      3. If node has a parent that is not root or current then set node to it.

         Otherwise, return null and terminate these steps.

The firstChild() method must traverse children of type first.

The lastChild() method must traverse children of type last.

To traverse siblings of type type run these steps:

1. Let node be the value of the currentNode attribute.

2. If node is root return null and terminate these steps.

3. Run these substeps:

   1. If type is next

      Let sibling be the next sibling of node.

      If type is previous

      Let sibling be the previous sibling of node.

   2. While sibling is not null run these inner substeps:

      1. Set node to sibling.

      2. Filter node and let result be the return value.

      3. If result is FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

      4. If type is next

         Let sibling be the first child of node.

         If type is previous

         Let sibling be the last child of node.

      5. If result is FILTER_REJECT or sibling is null, then set sibling as follows:

         If type is next

         Let sibling be the next sibling of node.

         If type is previous

         Let sibling be the previous sibling of node.

   3. Set node to its parent.

   4. If node is null or is root return null and terminate these steps.

   5. Filter node and if the return value is FILTER_ACCEPT, then return null and terminate these steps.

   6. Run these substeps again.