Skip to main content

Document

Struct Document 

Source
pub struct Document { /* private fields */ }
Expand description

A parsed HTML document, or a fragment.

Implementations§

Source§

impl Document

Source

pub fn empty() -> Document

An empty document to build into, as XML is: no source, no nodes but the document itself.

Source

pub fn root(&self) -> u32

Source

pub fn quirks(&self) -> Quirks

Source

pub fn len(&self) -> usize

Source

pub fn is_empty(&self) -> bool

Source

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.

Source

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>.

Source

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.

Source

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.

Source

pub fn errors(&self) -> &[SyntaxError]

The parse errors in the input, in source order: empty unless the document was parsed with Options::errors on.

Source

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.

Source

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.

Source

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

Source

pub fn first_child(&self, id: u32) -> Option<u32>

Source

pub fn prev_sibling(&self, id: u32) -> Option<u32>

Source

pub fn last_child(&self, id: u32) -> Option<u32>

Source

pub fn next_sibling(&self, id: u32) -> Option<u32>

Source

pub fn children(&self, id: u32) -> impl Iterator<Item = u32>

Source

pub fn template_contents(&self, id: u32) -> Option<u32>

A template element’s contents.

Source

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.

Source

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.

Source

pub fn attrs(&self, id: u32) -> impl Iterator<Item = (AttrNs, &str, &str)>

An element’s attributes, in source order, as (namespace, local name, value).

Source

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.

Source

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

pub fn known_tag(&self, id: u32) -> Option<u8>

The parser’s number for an element’s tag, from its lowercase name: what crate::tag_number gives for that name. HTML, SVG and MathML elements alike get one, so an SVG <title> shares HTML title’s; an XML element never does.

Source§

impl Document

Source

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.

Source

pub fn create_text(&mut self, text: &str) -> u32

Source

pub fn create_cdata(&mut self, text: &str) -> u32

Source

pub fn create_comment(&mut self, text: &str) -> u32

Source

pub fn create_processing_instruction(&mut self, target: &str, data: &str) -> u32

Source

pub fn create_doctype( &mut self, name: &str, public_id: &str, system_id: &str, ) -> u32

Source

pub fn append(&mut self, parent: u32, child: u32) -> Result<(), EditError>

Moves child to be the last child of parent.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Source

pub fn inner_html(&self, id: u32) -> String

The markup for id’s children, as innerHTML returns it.

Source

pub fn outer_html(&self, id: u32) -> String

The markup for id and its children, as outerHTML returns it.

Source

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.

Source

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.

Source

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

pub fn text(&self, id: u32) -> String

The text of id and everything under it, in tree order, as textContent gives it.

Source§

impl Document

Source

pub fn shadow_root(&self, host: u32) -> Option<u32>

The element’s shadow root, open or closed.

Source

pub fn shadow_host(&self, root: u32) -> Option<u32>

A shadow root’s host.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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).

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn flat_tree(&self, id: u32) -> impl Iterator<Item = u32>

The flat tree under id, in tree order, id first: what a renderer walks.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.