[−][src]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:
- It maintains a reasonable separation between the node type traits and the tree implementation using opaque Node reference types.
- Where possible the names from IDL are used with minimal conversion, however some redundant
suffixes (
_data
,_node
) have been reduced for brevity/clarity. - 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 theNode
interface expose methods for dealing with children, not all objects implementing theNode
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
andattributes
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 specificnodeType
(e.g.,nodeValue
for anElement
orattributes
for aComment
), this returnsnull
. 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 enumerationError
. - 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.
- readonly attributes simply have an
- IDL function names are altered from
lowerCamelCase
tosnake_case
. - IDL functions that are marked
raises(DOMException)
returnResult
withError
as the error type. - IDL attributes of type
T
that are described as "may benull
", or IDL functions that "may returnT
ornull
" instead returnOption<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.
- The
get_implementation
function returns an instance ofDOMImplementation
to allow bootstrapping the creation of documents. - The
get_implementation_version
function returns a vendor-specific version identifier for theDOMImplementation
. - The trait
Namespaced
extendsElement
with the ability to look up namespace mappings (using the standardxmlns
attribute).
Modules
convert | Provides safe |
Structs
Name | Corresponds to attributes |
Enums
Error | Corresponds to the DOM |
NodeType | This corresponds to the DOM |
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 |
CDataSection | This corresponds to the DOM |
CharacterData | This corresponds to the DOM |
Comment | This corresponds to the DOM |
DOMImplementation | This corresponds to the DOM |
Document | This corresponds to the DOM |
DocumentFragment | This corresponds to the DOM |
DocumentType | This corresponds to the DOM |
Element | This corresponds to the DOM |
Entity | This corresponds to the DOM |
EntityReference | This corresponds to the DOM |
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 |
Notation | This corresponds to the DOM |
ProcessingInstruction | This corresponds to the DOM |
Text | This corresponds to the DOM |
Functions
get_implementation | Return a reference to an instance of this |
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 |
Result | This standard |