Crate xml_dom

A reasonably faithful implementation of the W3C Document Object Model Core, Level 2.

This crate provides a trait-based implementation of the DOM with minimal changes to the style and semantics defined in the Level 2 specification. The specific mapping from the IDL in the specification is described below, however from a purely style point of view the implementation has the following characteristics:

1. It maintains a reasonable separation between the node type traits and the tree implementation using opaque Node reference types.
2. Where possible the names from IDL are used with minimal conversion, however some redundant suffixes (_data, _node) have been reduced for brevity/clarity.
3. This leads to a replication of the typical programmer experience where casting between the node traits is required. This is supported by the xml_dom::convert module.

Example

use xml_dom::*;
use xml_dom::convert::*;

let implementation = get_implementation();
let mut document_node = implementation
    .create_document("http://www.w3.org/1999/xhtml", "html", None)
    .unwrap();
println!("document 1: {:#?}", document_node);

let document = as_document_mut(&mut document_node).unwrap();
let mut root_node = document.document_element().unwrap();

let root = as_element_mut(&mut root_node).unwrap();
root.set_attribute("lang", "en");
let _head = root.append_child(document.create_element("head").unwrap());
let _body = root.append_child(document.create_element("body").unwrap());

let xml = document_node.to_string();
println!("document 2: {}", xml);

Specification

• Document Object Model (DOM) Level 1 Specification, Version 1.0, W3C Recommendation 1 October, 1998. Specifically §1, Document Object Model (Core) Level 1.
• Document Object Model (DOM) Level 2 Core Specification, Version 1.0, W3C Recommendation 13 November, 2000. Specifically §1, Document Object Model Core.

Conformance

TBD

The has_feature method DOMImplementation and is_supported on Node will return true when the request is for support of the Core or XML feature and supports both version 1.0 and version 2.0 of Core and version 1.0 of XML. Currently some of the XML extended interfaces are unsupported.

use xml_dom::{DOMImplementation, get_implementation};

let implementation = get_implementation();
assert!(implementation.has_feature("Core", "1.0"));
assert!(implementation.has_feature("Core", "2.0"));
assert!(implementation.has_feature("XML", "1.0"));
assert!(!implementation.has_feature("XML", "2.0"));

IDL to Rust Mapping

From the core documentation:

The Node interface is the primary datatype for the entire Document Object Model. It represents a single node in the document tree. While all objects implementing the Node interface expose methods for dealing with children, not all objects implementing the Node interface may have children. For example, Text nodes may not have children, and adding children to such nodes results in a DOMException being raised.

The attributes nodeName, nodeValue and attributes are included as a mechanism to get at node information without casting down to the specific derived interface. In cases where there is no obvious mapping of these attributes for a specific nodeType (e.g., nodeValue for an Element or attributes for a Comment), this returns null. Note that the specialized interfaces may contain additional and more convenient mechanisms to get and set the relevant information.

Wherever possible the documentation included in sections headed Specification is taken from the specification documents listed above.

Interface Mapping

The actual concrete types used in the DOM tree are RefNode and WeakRefNode which in turn are references to the opaque NodeImpl struct. Only RefNode implements all of the DOM interfaces and in general the programmer should never need to interact with WeakRefNode.

IDL Interface	Rust Mapping
Attr	Attribute
CharacterData	CharacterData
CDATASection	CDataSection
Comment	Comment
Document	Document
DocumentFragment	DocumentFragment
DocumentType	DocumentType
DOMImplementation	DOMImplementation
Element	Element
Entity	Entity
EntityReference	EntityReference
NamedNodeMap	HashMap<Name, RefNode>
Node	Node
NodeList	Vec<Rc<RefNode>>
Notation	Notation
ProcessingInstruction	ProcessingInstruction
Text	Text

• The exception type DOMException and associated constants are represented by the enumeration Error.
• IDL Interface attributes are represented by functions;
  • readonly attributes simply have an attribute_name getter,
  • writeable attributes also have a set_attribute_name setter,
  • some attributes allow null in which case they have an unset_attribute_name setter.
• IDL function names are altered from lowerCamelCase to snake_case.
• IDL functions that are marked raises(DOMException) return Result with Error as the error type.
• IDL attributes of type T that are described as "may be null", or IDL functions that "may return T or null" instead return Option<T>.

Primitive Type Mapping

IDL Type	Rust Type	Usage
boolean	bool	all
DOMString	String	all
unsigned short	Error, u16	as representation of exception code
unsigned long	usize	list/string indexes and lengths

Extensions

The following extensions are provided beyond the DOM Level 2 specification.

1. The get_implementation function returns an instance of DOMImplementation to allow bootstrapping the creation of documents.
2. The get_implementation_version function returns a vendor-specific version identifier for the DOMImplementation.
3. The trait Namespaced extends Element with the ability to look up namespace mappings (using the standard xmlns attribute).

Modules

convert

Provides safe RefNode conversion functions.

Structs

Name	Corresponds to attributes localName, namespaceURI, and prefix on the DOM Node interface.

Enums

Error	Corresponds to the DOM DomException type.
NodeType	This corresponds to the DOM NodeType set of constants.

Constants

MSG_INDEX_ERROR	Error message, see value.
MSG_INVALID_EXTENSION	Error message, see value.
MSG_INVALID_NAME	Error message, see value.
MSG_INVALID_NODE_TYPE	Error message, see value.
MSG_NO_PARENT_NODE	Error message, see value.
MSG_WRONG_DOCUMENT	Error message, see value.

Traits

Attribute	This corresponds to the DOM Attr interface.
CDataSection	This corresponds to the DOM CDataSection interface.
CharacterData	This corresponds to the DOM CharacterData interface.
Comment	This corresponds to the DOM Comment interface.
DOMImplementation	This corresponds to the DOM DOMImplementation interface.
Document	This corresponds to the DOM Document interface.
DocumentFragment	This corresponds to the DOM DocumentFragment interface (current unsupported).
DocumentType	This corresponds to the DOM DocumentType interface.
Element	This corresponds to the DOM Element interface.
Entity	This corresponds to the DOM Entity interface (currently unsupported).
EntityReference	This corresponds to the DOM EntityReference interface (currently unsupported).
Namespaced	An extended interface that provides access to namespace information for elements, including the resolving of prefixes and namespaces in the hierarchy of the document.
Node	This corresponds to the DOM Node interface.
Notation	This corresponds to the DOM Notation interface (currently unsupported).
ProcessingInstruction	This corresponds to the DOM ProcessingInstruction interface.
Text	This corresponds to the DOM Text interface.

Functions

get_implementation	Return a reference to an instance of this DOMImplementation implementation.
get_implementation_version	Return a string with the vendor/version of the implementation.

Type Definitions

RefNode	Opaque DOM tree node reference. This is the type used by this implementation as the concrete type for the NodeRef associated type in the Node trait.
Result	This standard Result structure is used wherever an IDL function is marked as throwing exceptions.