pub struct Document { /* private fields */ }Expand description
A parsed HTML document, or a fragment.
Implementations§
Source§impl Document
impl Document
Sourcepub fn empty() -> Document
pub fn empty() -> Document
An empty document to build into, as XML is: no source, no nodes but the document itself.
pub fn root(&self) -> u32
pub fn quirks(&self) -> Quirks
pub fn len(&self) -> usize
pub fn is_empty(&self) -> bool
Sourcepub fn span(&self, id: u32) -> Option<Range<usize>>
pub fn span(&self, id: u32) -> Option<Range<usize>>
Where a node was written, as a byte range of the input the parse
was given: an element’s start tag from < to >, or the whole of
a text node, comment, doctype or processing instruction. A text
node made of several runs (text, then a character reference, then
text again, or text foster-parented out of a table) spans the first
run’s start to the last one’s end.
None for a node the parser made up rather than read (an implied
<html>, <head>, <body> or <tbody>, a formatting element it
reopened, a copy the adoption agency made), for one an edit made,
and for every node unless the document was parsed with
Options::spans on.
Sourcepub fn end_span(&self, id: u32) -> Option<Range<usize>>
pub fn end_span(&self, id: u32) -> Option<Range<usize>>
Where an element’s end tag was written, when it had one: the end
tag whose handling closed it, </p> for a <p>, or a </body>.
Sourcepub fn attr_span(&self, id: u32, i: usize) -> Option<Range<usize>>
pub fn attr_span(&self, id: u32, i: usize) -> Option<Range<usize>>
Where an element’s ith attribute, as Document::attrs lists
them, was written: from its name’s first byte to the end of its
value, past a closing quote, or to the end of its name when it has
no value. An attribute an edit set has none; a reopened formatting
element’s are where the original’s were written.
Sourcepub fn line_col(&self, offset: usize) -> (usize, usize)
pub fn line_col(&self, offset: usize) -> (usize, usize)
The line and column of a byte offset into the input the parse was
given, as an editor shows them: both start at 1, a line ends at an
LF, a CRLF or a lone CR, and the column counts characters (Unicode
scalar values), not bytes. Worked out from the source each time,
so it costs a pass over the text before offset.
Sourcepub fn errors(&self) -> &[SyntaxError]
pub fn errors(&self) -> &[SyntaxError]
The parse errors in the input, in source order: empty unless the
document was parsed with Options::errors
on.
Sourcepub fn detach(&mut self, child: u32)
pub fn detach(&mut self, child: u32)
Takes child out of the tree, still usable: insert it again to move
it, subtree and all. To be done with a node for good, use
Document::remove, after which its id reads as nothing.
Sourcepub fn check_tree(&self)
pub fn check_tree(&self)
Checks every invariant of the tree, panicking at the first that doesn’t hold: every node’s links agree with its parent’s and its siblings’, only elements, documents and fragments have children, each node is reached from the root at most once (template contents included), each template’s contents are a fragment of its own that’s nobody’s child, the map of hosts agrees with the templates, and every string and recorded position is inside its buffer.
Linear in the document’s size, so it’s for tests and fuzzing, not for every edit; the parser and the edits assert the parts of this they touch as they go. Only in builds with debug assertions.
pub fn parent(&self, id: u32) -> Option<u32>
pub fn first_child(&self, id: u32) -> Option<u32>
pub fn prev_sibling(&self, id: u32) -> Option<u32>
pub fn last_child(&self, id: u32) -> Option<u32>
pub fn next_sibling(&self, id: u32) -> Option<u32>
pub fn children(&self, id: u32) -> impl Iterator<Item = u32>
Sourcepub fn template_contents(&self, id: u32) -> Option<u32>
pub fn template_contents(&self, id: u32) -> Option<u32>
A template element’s contents.
Sourcepub fn is_removed(&self, id: u32) -> bool
pub fn is_removed(&self, id: u32) -> bool
Whether id was taken out with Document::remove, or was inside
a node that was. A removed node reads as nothing: the readers that
return an Option give None, it has no children, attributes or
text, it serializes to "", it matches no selector, and inserting
it, or anything into it, is an error.
Sourcepub fn kind(&self, id: u32) -> Kind<'_>
pub fn kind(&self, id: u32) -> Kind<'_>
What id is. A removed node keeps its kind and an element its
name, but its text, a comment’s, and a processing instruction’s
data read as empty, as it has no children or attributes.
Sourcepub fn attrs(&self, id: u32) -> impl Iterator<Item = (AttrNs, &str, &str)>
pub fn attrs(&self, id: u32) -> impl Iterator<Item = (AttrNs, &str, &str)>
An element’s attributes, in source order, as (namespace, local name, value).
Sourcepub fn attrs_written(
&self,
id: u32,
) -> impl Iterator<Item = (AttrNs, &str, &str)>
pub fn attrs_written( &self, id: u32, ) -> impl Iterator<Item = (AttrNs, &str, &str)>
An element’s attributes with their names as written: xlink:href
rather than href, and an XML attribute’s prefix kept.
Sourcepub fn lower_name(&self, id: u32) -> Option<&str>
pub fn lower_name(&self, id: u32) -> Option<&str>
An element’s name lowercased, without allocating: SVG’s
foreignObject gives foreignobject, whether it was parsed or made
with Document::create_element. An XML element’s name as written,
and so is a foreign element made under a name in another case
(LINEARGRADIENT), which the DOM treats as a different element.
Source§impl Document
impl Document
Sourcepub fn create_element(&mut self, ns: Ns, name: &str) -> u32
pub fn create_element(&mut self, ns: Ns, name: &str) -> u32
A new element, not yet in the tree. HTML names are lowercased, as
createElement does.
pub fn create_text(&mut self, text: &str) -> u32
pub fn create_cdata(&mut self, text: &str) -> u32
pub fn create_comment(&mut self, text: &str) -> u32
pub fn create_processing_instruction(&mut self, target: &str, data: &str) -> u32
pub fn create_doctype( &mut self, name: &str, public_id: &str, system_id: &str, ) -> u32
Sourcepub fn append(&mut self, parent: u32, child: u32) -> Result<(), EditError>
pub fn append(&mut self, parent: u32, child: u32) -> Result<(), EditError>
Moves child to be the last child of parent.
Sourcepub fn insert_before(
&mut self,
parent: u32,
child: u32,
before: Option<u32>,
) -> Result<(), EditError>
pub fn insert_before( &mut self, parent: u32, child: u32, before: Option<u32>, ) -> Result<(), EditError>
Moves child into parent, before before, or last for None.
Sourcepub fn adopt_template_contents(&mut self)
pub fn adopt_template_contents(&mut self)
Moves every template’s contents in under the template element itself, as lxml and Beautiful Soup show them and scrapers expect: selectors and walks then see them. The contents are left empty.
Sourcepub fn remove(&mut self, id: u32)
pub fn remove(&mut self, id: u32)
Takes id, and everything in it, out of the document for good. From
then on each of their ids reads as nothing (see
Document::is_removed), editing one does nothing, and inserting
one, or anything into one, is EditError::Removed. A template’s
contents go with it, and so does a shadow host’s shadow tree. To move
a node, take it out with Document::detach and insert it again.
The root, a template’s contents or a shadow root on its own can’t be
removed: they’re never anyone’s child.
Sourcepub fn set_attr(&mut self, id: u32, name: &str, value: &str)
pub fn set_attr(&mut self, id: u32, name: &str, value: &str)
Sets an attribute, replacing the first one of the same qualified name
in any namespace (xlink:href), as setAttribute does. HTML
elements’ attribute names are lowercased; SVG’s and MathML’s keep the
case they’re given.
A node taken out with Document::remove is left alone.
Sourcepub fn add_attr(&mut self, id: u32, ns: AttrNs, name: &str, value: &str)
pub fn add_attr(&mut self, id: u32, ns: AttrNs, name: &str, value: &str)
Adds an attribute as given, after the others, without replacing one
of the same name: for building XML, where the caller has already
checked names.
A node taken out with Document::remove is left alone.
Sourcepub fn set_attrs(&mut self, id: u32, attrs: &[(AttrNs, &str, &str)])
pub fn set_attrs(&mut self, id: u32, attrs: &[(AttrNs, &str, &str)])
Replaces all of the element’s attributes at once.
A node taken out with Document::remove is left alone.
Sourcepub fn rename(&mut self, id: u32, name: &str)
pub fn rename(&mut self, id: u32, name: &str)
Renames the element: lowercased for HTML, as given for the rest.
An element renamed to template gets empty contents, as a new one
does. A template renamed to anything else gives its contents up as
ordinary children, ahead of any it has, so its markup stays the same
and nothing in them is lost.
A node taken out with Document::remove is left alone.
Sourcepub fn rename_attr(&mut self, id: u32, index: usize, ns: AttrNs, name: &str)
pub fn rename_attr(&mut self, id: u32, index: usize, ns: AttrNs, name: &str)
Renames the element’s indexth attribute, and sets its namespace.
A node taken out with Document::remove is left alone.
Sourcepub fn remove_attr_at(&mut self, id: u32, index: usize) -> bool
pub fn remove_attr_at(&mut self, id: u32, index: usize) -> bool
Removes the element’s indexth attribute; false if there’s none.
A node taken out with Document::remove is left alone, and gives
false.
Sourcepub fn remove_attr(&mut self, id: u32, name: &str) -> bool
pub fn remove_attr(&mut self, id: u32, name: &str) -> bool
Removes an attribute by name; false if there wasn’t one.
A node taken out with Document::remove is left alone, and gives
false.
Source§impl Document
impl Document
Sourcepub fn inner_html(&self, id: u32) -> String
pub fn inner_html(&self, id: u32) -> String
The markup for id’s children, as innerHTML returns it.
Sourcepub fn outer_html(&self, id: u32) -> String
pub fn outer_html(&self, id: u32) -> String
The markup for id and its children, as outerHTML returns it.
Sourcepub fn serialize_with(&self, id: u32, options: &SerializeOptions) -> String
pub fn serialize_with(&self, id: u32, options: &SerializeOptions) -> String
The markup for id and its children, written as options say;
with the defaults, what Document::outer_html gives.
Sourcepub fn inner_html_with(&self, id: u32, options: &SerializeOptions) -> String
pub fn inner_html_with(&self, id: u32, options: &SerializeOptions) -> String
The markup for id’s children, written as options say; with the
defaults, what Document::inner_html gives.
Sourcepub fn html_alone(&self, id: u32) -> String
pub fn html_alone(&self, id: u32) -> String
The node alone: an element’s start tag, escaped text, a comment
or a doctype; as outer_html writes it, without the children. A
document or a template’s contents is nothing but its children, so
it gives an empty string.
Source§impl Document
impl Document
Sourcepub fn shadow_root(&self, host: u32) -> Option<u32>
pub fn shadow_root(&self, host: u32) -> Option<u32>
The element’s shadow root, open or closed.
Sourcepub fn shadow_host(&self, root: u32) -> Option<u32>
pub fn shadow_host(&self, root: u32) -> Option<u32>
A shadow root’s host.
Sourcepub fn tree_root(&self, id: u32) -> u32
pub fn tree_root(&self, id: u32) -> u32
The node at the top of id’s tree: the document, a template’s
contents, a shadow root, or a detached node.
Sourcepub fn attach_shadow(
&mut self,
host: u32,
init: ShadowRoot,
) -> Result<u32, EditError>
pub fn attach_shadow( &mut self, host: u32, init: ShadowRoot, ) -> Result<u32, EditError>
Attaches a shadow root to host, as attachShadow does: only an
HTML element of a name the standard lists (div, span,
section…) or a custom element may have one, and only one.
EditError::NotAShadowHost otherwise. The root starts empty. As
in the DOM, a root the parser made from a <template shadowrootmode> is handed back once to a call with its mode,
emptied, keeping the settings it was declared with.
Sourcepub fn is_slot(&self, id: u32) -> bool
pub fn is_slot(&self, id: u32) -> bool
Whether id is a slot element in a shadow tree, the only kind
that’s assigned nodes.
Sourcepub fn assign(&mut self, slot: u32, nodes: &[u32])
pub fn assign(&mut self, slot: u32, nodes: &[u32])
Sets the nodes a slot in a shadow root with
SlotAssignment::Manual is assigned, as slot.assign() does:
in that order, each taken from any slot it was assigned before.
Only those that are children of the host are assigned, when asked;
in a root with named assignment the list is kept and unused.
Sourcepub fn assigned_slot(&self, node: u32) -> Option<u32>
pub fn assigned_slot(&self, node: u32) -> Option<u32>
The slot that node is assigned to, as the DOM’s “find a slot”:
None unless it’s an element or text whose parent hosts a shadow
root (open or closed).
Sourcepub fn assigned_nodes(&self, slot: u32) -> Vec<u32>
pub fn assigned_nodes(&self, slot: u32) -> Vec<u32>
The nodes assigned to a slot, as slot.assignedNodes(): the
host’s children that Document::assigned_slot puts there, in
tree order (or the order Document::assign gave, for manual
assignment). Empty for an element that isn’t a slot in a shadow
tree.
Sourcepub fn flattened_assigned_nodes(&self, slot: u32) -> Vec<u32>
pub fn flattened_assigned_nodes(&self, slot: u32) -> Vec<u32>
slot.assignedNodes({flatten: true}): a slot assigned another
slot shows what that one shows, and a slot assigned nothing shows
its own children, its fallback content.
Sourcepub fn flat_children(&self, id: u32) -> Vec<u32>
pub fn flat_children(&self, id: u32) -> Vec<u32>
A node’s children in the flat tree, as rendering sees them: a shadow host’s are its shadow root’s children, a slot’s are its assigned nodes (or its own children when it has none), and every other node’s are its children.
Sourcepub fn flat_parent(&self, id: u32) -> Option<u32>
pub fn flat_parent(&self, id: u32) -> Option<u32>
A node’s parent in the flat tree: its slot when it’s assigned one,
the host for a shadow root’s child, else its parent. None for a
node the flat tree leaves out: a host’s child no slot takes, or a
slot’s fallback content when the slot was assigned nodes.