Struct Document 

pub struct Document { /* private fields */ }

A parsed XML document, stored as an arena of nodes.

Construct one with Document::from_str, Document::from_bytes, or Document::from_path. Every accessor takes a NodeId obtained from this same document.

Examples

use schematron::xml::Document;

let doc = Document::from_str("<a x='1'>hello</a>").unwrap();
let a = doc.document_element().unwrap();
assert_eq!(doc.name(a).unwrap().local, "a");
assert_eq!(doc.string_value(a), "hello");

Implementations

impl Document

pub const fn root(&self) -> NodeId

The root node, which is the parent of the document element.

This is XPath’s /, and it is not the document element itself. When other documents have been merged in, this is the root of the primary one — use Document::root_of to get the root that a particular node belongs to.

pub fn root_of(&self, node: NodeId) -> NodeId

The root of the document that node belongs to.

Identical to Document::root unless other documents have been merged in by XPath document(). It is what an absolute path such as /invoice must start from: inside a merged document, / means that document’s root, not the primary one’s.

Examples

use schematron::xml::Document;

let doc = Document::from_str("<a><b/></a>").unwrap();
let b = doc.children(doc.document_element().unwrap())[0];
assert_eq!(doc.root_of(b), doc.root());

pub fn roots(&self) -> Vec<NodeId>

The roots of every document in this arena, primary first.

pub fn document_element(&self) -> Option<NodeId>

The document element: the single element child of the root.

Returns None only for a document with no element, which the parser rejects, so in practice this is always Some for a parsed document.

pub fn base_uri(&self) -> Option<&str>

The base URI used to resolve relative references from this document.

pub fn set_base_uri(&mut self, uri: impl Into<String>)

Sets the base URI.

pub fn len(&self) -> usize

The number of nodes in the document, all kinds included.

pub fn is_empty(&self) -> bool

Whether the document holds nothing but its root node.

pub fn kind(&self, id: NodeId) -> NodeKind

The kind of a node.

pub fn name(&self, id: NodeId) -> Option<&QName>

The expanded name of a node, for the kinds that have one.

Elements, attributes, and processing instructions have names; the other kinds return None. A namespace node’s “name” is its prefix, which is what XPath’s name() returns for it, so it is reported here as a local name.

pub fn parent(&self, id: NodeId) -> Option<NodeId>

The parent of a node, or None for the root.

Attribute and namespace nodes report their element as their parent, which is what the parent axis requires, even though they are not in that element’s child list.

pub fn children(&self, id: NodeId) -> &[NodeId]

The children of a node, excluding attribute and namespace nodes.

pub fn attributes(&self, id: NodeId) -> &[NodeId]

The attribute nodes of an element, excluding namespace declarations.

pub fn namespaces(&self, id: NodeId) -> &[NodeId]

The namespace nodes in scope on an element.

Per XPath, this includes bindings inherited from ancestors and the implicit binding of the xml prefix, and excludes any binding that a nearer ancestor has overridden or undeclared.

pub fn order(&self, id: NodeId) -> usize

The position of a node in document order.

Node-set ordering, position(), and the “first node in document order” rule all reduce to comparing this value.

pub fn value(&self, id: NodeId) -> &str

The raw stored value of a node.

For text, comments, and processing instructions this is the content; for attributes the normalised value; for namespace nodes the URI. For elements and the root it is empty — use Document::string_value, which computes the XPath string value.

pub fn string_value(&self, id: NodeId) -> String

The XPath 1.0 string value of a node.

For the root and for elements this is the concatenation of every descendant text node in document order; for every other kind it is the node’s own content.

Examples

use schematron::xml::Document;

let doc = Document::from_str("<a>one<b>two</b>three</a>").unwrap();
let a = doc.document_element().unwrap();
assert_eq!(doc.string_value(a), "onetwothree");

pub fn ancestors(&self, id: NodeId) -> Vec<NodeId>

The ancestors of a node, nearest first, ending at the root.

pub fn descendants_or_self(&self, id: NodeId) -> Vec<NodeId>

Every node in the subtree rooted at id, in document order.

Includes id itself. Excludes attribute and namespace nodes, matching the descendant-or-self axis.

pub fn descendants(&self, id: NodeId) -> Vec<NodeId>

Every node in the subtree rooted at id except id.

Separate from Document::descendants_or_self rather than that result with its first element removed: Vec::remove(0) shifts every remaining element, and this axis is evaluated against the whole document once per rule.

pub fn all_nodes_in_document_order(&self) -> Vec<NodeId>

Every node of the document in document order, attribute and namespace nodes included.

This is the visiting order Schematron rules are offered nodes in: an element, then its namespace nodes, then its attribute nodes, then its children. See spec/validation/.

pub fn subtree_end(&self, id: NodeId) -> usize

The highest document-order value in this node’s subtree.

With Document::order, this gives an O(1) descendant test: x is a descendant of y exactly when order(y) < order(x) <= subtree_end(y).

pub fn is_descendant_of(&self, descendant: NodeId, ancestor: NodeId) -> bool

Whether descendant lies inside the subtree rooted at ancestor.

Excludes the node itself.

pub fn location(&self, id: NodeId) -> String

An absolute XPath expression that unambiguously identifies id.

Names are written in the *:local wildcard form so that the result is usable without knowing the consumer’s prefix bindings, which is what SVRL @location requires. See spec/validation/.

Examples

use schematron::xml::Document;

let doc = Document::from_str("<a><b/><b id='x'/></a>").unwrap();
let second = doc.children(doc.document_element().unwrap())[1];
assert_eq!(doc.location(second), "/a[1]/b[2]");

impl Document

pub fn from_str(source: &str) -> Result<Document>

Parses a document from a string.

Named from_str rather than implementing std::str::FromStr deliberately, to match Document::from_bytes and Document::from_path, which the trait cannot express.

Errors

Returns Error::XmlParse if the input is not well-formed, if a namespace prefix is used without being declared, or if it references an entity that is not predefined.

Examples

use schematron::xml::Document;

let doc = Document::from_str("<a><b/></a>").unwrap();
assert!(doc.document_element().is_some());
assert!(Document::from_str("<a>").is_err());

pub fn from_bytes(bytes: &[u8]) -> Result<Document>

Parses a document from bytes, transcoding UTF-16 to UTF-8 if needed.

Errors

As Document::from_str, plus an error if the bytes are not valid in any encoding the crate understands.

pub fn from_path<P: AsRef<Path>>(path: P) -> Result<Document>

Reads and parses a document from a file, recording its path as the base URI for relative reference resolution.

Errors

Returns Error::Io if the file cannot be read, or a parse error as Document::from_str.

Trait Implementations

impl Clone for Document

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Document

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.