From 9461dcef331a832e3385361ffd217897093a8979 Mon Sep 17 00:00:00 2001 From: xusd320 Date: Fri, 19 Jul 2024 22:26:43 +0800 Subject: [PATCH] docs: add docs --- crates/niddle_napi/src/lib.rs | 5 +- crates/niddle_napi/src/node_repr/mod.rs | 17 +++---- crates/niddle_napi/src/node_repr/modify.rs | 51 ++++++++++++++----- crates/niddle_napi/src/node_repr/query.rs | 20 +++++--- crates/niddle_napi/src/serializer.rs | 6 +-- index.d.ts | 57 ++++++++++++++++++++++ 6 files changed, 124 insertions(+), 32 deletions(-) diff --git a/crates/niddle_napi/src/lib.rs b/crates/niddle_napi/src/lib.rs index bca0e1a..63d8923 100644 --- a/crates/niddle_napi/src/lib.rs +++ b/crates/niddle_napi/src/lib.rs @@ -12,13 +12,12 @@ mod serializer; mod node_repr; +/// Parse string input to a html tree, return the root node. #[napi] pub fn parse(html: String) -> NodeRepr { let parser = parse_html(); let document_node = parser.one(html); - NodeRepr { - node_ref: document_node, - } + NodeRepr(document_node) } #[cfg(test)] diff --git a/crates/niddle_napi/src/node_repr/mod.rs b/crates/niddle_napi/src/node_repr/mod.rs index 88bb686..ad7c0c3 100644 --- a/crates/niddle_napi/src/node_repr/mod.rs +++ b/crates/niddle_napi/src/node_repr/mod.rs @@ -3,36 +3,35 @@ use kuchikiki::{ElementData, NodeDataRef, NodeRef}; mod modify; mod query; +/// The node object, cann't be instantiated in javascript. #[napi] -pub struct NodeRepr { - pub(crate) node_ref: NodeRef, -} +pub struct NodeRepr(pub(crate) NodeRef); impl From> for NodeRepr { fn from(element: NodeDataRef) -> Self { - Self { - node_ref: element.as_node().clone(), - } + Self(element.as_node().clone()) } } impl From for NodeRepr { fn from(node_ref: NodeRef) -> Self { - Self { node_ref } + Self(node_ref) } } #[napi] impl NodeRepr { + /// Clone this node to a new instance, not clone its descendants. #[napi(js_name = "clone")] pub fn clone_self_only(&self) -> NodeRepr { - let new_node_ref = NodeRef::new(self.node_ref.data().clone()); + let new_node_ref = NodeRef::new(self.0.data().clone()); NodeRepr::from(new_node_ref) } + /// Clone this node to a new instance, including its all descendants. #[napi] pub fn clone_recursive(&self) -> NodeRepr { - NodeRepr::from(clone_node_ref_recursive(&self.node_ref)) + NodeRepr::from(clone_node_ref_recursive(&self.0)) } } diff --git a/crates/niddle_napi/src/node_repr/modify.rs b/crates/niddle_napi/src/node_repr/modify.rs index ab5aabf..ee7f79c 100644 --- a/crates/niddle_napi/src/node_repr/modify.rs +++ b/crates/niddle_napi/src/node_repr/modify.rs @@ -5,11 +5,17 @@ use super::NodeRepr; #[napi] impl NodeRepr { + /// Append a child node to this node, after existing children. + /// + /// The child node will be remove from its previous position. #[napi] pub fn append(&self, new_child: &NodeRepr) { - self.node_ref.append(new_child.node_ref.clone()) + self.0.append(new_child.0.clone()) } + /// Append some children nodes to this node by order, after existing children. + /// + /// These children nodes will be remove from their previous position. #[napi] pub fn append_sequence(&self, new_children: Vec<&NodeRepr>) { new_children @@ -17,11 +23,17 @@ impl NodeRepr { .for_each(|new_child| self.append(new_child)) } + /// Prepend a child node to this node, before existing children. + /// + /// The child node will be remove from its previous position. #[napi] pub fn prepend(&self, new_child: &NodeRepr) { - self.node_ref.prepend(new_child.node_ref.clone()) + self.0.prepend(new_child.0.clone()) } + /// Prepend some children nodes to this node by order, before existing children. + /// + /// These children nodes will be remove from their previous position. #[napi] pub fn prepend_sequence(&self, new_children: Vec<&NodeRepr>) { if !new_children.is_empty() { @@ -34,11 +46,17 @@ impl NodeRepr { } } + /// Insert a new sibling after this node. + /// + /// The sibling node will be remove from its previous position. #[napi] pub fn insert_after(&self, new_sibling: &NodeRepr) { - self.node_ref.insert_after(new_sibling.node_ref.clone()) + self.0.insert_after(new_sibling.0.clone()) } + /// Insert some siblings after this node. + /// + /// These sibling nodes will be remove from their previous position. #[napi] pub fn insert_sequence_after(&self, new_siblings: Vec<&NodeRepr>) { if !new_siblings.is_empty() { @@ -48,38 +66,46 @@ impl NodeRepr { .skip(1) .enumerate() .for_each(|(index, new_sibling)| { - if let Some(sibling) = self.node_ref.following_siblings().nth(index) { + if let Some(sibling) = self.0.following_siblings().nth(index) { NodeRepr::from(sibling).insert_after(new_sibling) } }); } } + /// Insert a new sibling before this node. + /// + /// The sibling node will be remove from its previous position. #[napi] pub fn insert_before(&self, new_sibling: &NodeRepr) { - self.node_ref.insert_before(new_sibling.node_ref.clone()) + self.0.insert_before(new_sibling.0.clone()) } + /// Insert some siblings before this node. + /// + /// These sibling nodes will be remove from their previous position. #[napi] pub fn insert_sequence_before(&self, new_siblings: Vec<&NodeRepr>) { if !new_siblings.is_empty() { self.insert_before(new_siblings[0]); new_siblings.iter().skip(1).for_each(|new_sibling| { - if let Some(sibling) = self.node_ref.preceding_siblings().last() { + if let Some(sibling) = self.0.preceding_siblings().last() { NodeRepr::from(sibling).insert_after(new_sibling) } }); } } + /// Remove a node from its parent and siblings. Children are not affected. #[napi] pub fn remove(&self) { - self.node_ref.detach() + self.0.detach() } + /// Assign an attribute K-V to this node #[napi] pub fn set_attribute(&self, name: String, value: String) { - if let Some(ele) = self.node_ref.as_element() { + if let Some(ele) = self.0.as_element() { ele .attributes .borrow_mut() @@ -87,9 +113,10 @@ impl NodeRepr { } } + /// Assign attributes K-V object to this node #[napi] pub fn set_attributes(&self, attrs: IndexMap) { - if let Some(ele) = self.node_ref.as_element() { + if let Some(ele) = self.0.as_element() { attrs.into_iter().for_each(|(name, value)| { ele .attributes @@ -99,16 +126,18 @@ impl NodeRepr { } } + /// Remove an attribute of this node by name #[napi] pub fn remove_attribute(&self, name: String) { - if let Some(ele) = self.node_ref.as_element() { + if let Some(ele) = self.0.as_element() { ele.attributes.borrow_mut().remove(LocalName::from(name)); } } + /// Remove all attributes of this node #[napi] pub fn remove_all_attributes(&self) { - if let Some(ele) = self.node_ref.as_element() { + if let Some(ele) = self.0.as_element() { ele.attributes.borrow_mut().map.clear(); } } diff --git a/crates/niddle_napi/src/node_repr/query.rs b/crates/niddle_napi/src/node_repr/query.rs index e9bc772..f890111 100644 --- a/crates/niddle_napi/src/node_repr/query.rs +++ b/crates/niddle_napi/src/node_repr/query.rs @@ -8,35 +8,40 @@ use super::NodeRepr; #[napi] impl NodeRepr { + /// Select the the fist node that match the given selector, like document.querySelector. #[napi] pub fn select(&self, selectors: String) -> Option { - self.node_ref.select_first(&selectors).ok().map(Into::into) + self.0.select_first(&selectors).ok().map(Into::into) } + /// Select all nodes that match the given selector, like document.querySelectorAll. #[napi] pub fn select_all(&self, selectors: String) -> Vec { self - .node_ref + .0 .select(&selectors) .map_or(vec![], |els| els.map(Into::into).collect()) } + /// Get all children nodes of this node. #[napi] pub fn get_children(&self) -> Vec { - self.node_ref.children().map(Into::into).collect() + self.0.children().map(Into::into).collect() } + /// Get attribute value of this node by given name. #[napi] pub fn get_attribute(&self, name: String) -> Option { self - .node_ref + .0 .as_element() .and_then(|e| e.attributes.borrow().get(name).map(|v| v.to_string())) } + /// Get attributes K-V object of this node. #[napi] pub fn get_attributes(&self) -> IndexMap { - self.node_ref.as_element().map_or_else(IndexMap::new, |e| { + self.0.as_element().map_or_else(IndexMap::new, |e| { e.attributes .borrow() .map @@ -49,6 +54,7 @@ impl NodeRepr { }) } + /// Get the serialized html of this node, including its all descendants and itelf;. #[napi] pub fn outer_html(&self) -> String { let mut u8_vec = Vec::new(); @@ -65,6 +71,7 @@ impl NodeRepr { unsafe { String::from_utf8_unchecked(u8_vec) } } + /// Get the serialized html of this node, only including its all descendants;. #[napi] pub fn inner_html(&self) -> String { let mut buf = Vec::::new(); @@ -81,10 +88,11 @@ impl NodeRepr { unsafe { String::from_utf8_unchecked(buf) } } + /// Get all text nodes content of this node, including its all descendants and itelf;. #[napi] pub fn text(&self) -> String { let mut buf = Vec::::new(); - serialize_text_only(&self.node_ref, &mut buf).unwrap(); + serialize_text_only(&self.0, &mut buf).unwrap(); unsafe { String::from_utf8_unchecked(buf) } } } diff --git a/crates/niddle_napi/src/serializer.rs b/crates/niddle_napi/src/serializer.rs index ae84822..7ce1067 100644 --- a/crates/niddle_napi/src/serializer.rs +++ b/crates/niddle_napi/src/serializer.rs @@ -16,7 +16,7 @@ impl Serialize for NodeRepr { serializer: &mut S, traversal_scope: TraversalScope, ) -> Result<()> { - match (traversal_scope, self.node_ref.data()) { + match (traversal_scope, self.0.data()) { (ref scope, NodeData::Element(element)) => { if *scope == IncludeNode { let attrs = element.attributes.borrow(); @@ -38,7 +38,7 @@ impl Serialize for NodeRepr { )? } - for child in self.node_ref.children() { + for child in self.0.children() { Serialize::serialize(&child, serializer, IncludeNode)? } @@ -49,7 +49,7 @@ impl Serialize for NodeRepr { } (_, &NodeData::DocumentFragment) | (_, &NodeData::Document(_)) => { - for child in self.node_ref.children() { + for child in self.0.children() { Serialize::serialize(&child, serializer, IncludeNode)? } Ok(()) diff --git a/index.d.ts b/index.d.ts index bd10074..657ff89 100644 --- a/index.d.ts +++ b/index.d.ts @@ -3,29 +3,86 @@ /* auto-generated by NAPI-RS */ +/** Parse string input to a html tree, return the root node. */ function parse(html: string): NodeRepr +/** The node object, cann't be instantiated in javascript. */ export declare class NodeRepr { + /** + * Append a child node to this node, after existing children. + * + * The child node will be remove from its previous position. + */ append(newChild: NodeRepr): void + /** + * Append some children nodes to this node by order, after existing children. + * + * These children nodes will be remove from their previous position. + */ appendSequence(newChildren: Array): void + /** + * Prepend a child node to this node, before existing children. + * + * The child node will be remove from its previous position. + */ prepend(newChild: NodeRepr): void + /** + * Prepend some children nodes to this node by order, before existing children. + * + * These children nodes will be remove from their previous position. + */ prependSequence(newChildren: Array): void + /** + * Insert a new sibling after this node. + * + * The sibling node will be remove from its previous position. + */ insertAfter(newSibling: NodeRepr): void + /** + * Insert some siblings after this node. + * + * These sibling nodes will be remove from their previous position. + */ insertSequenceAfter(newSiblings: Array): void + /** + * Insert a new sibling before this node. + * + * The sibling node will be remove from its previous position. + */ insertBefore(newSibling: NodeRepr): void + /** + * Insert some siblings before this node. + * + * These sibling nodes will be remove from their previous position. + */ insertSequenceBefore(newSiblings: Array): void + /** Remove a node from its parent and siblings. Children are not affected. */ remove(): void + /** Assign an attribute K-V to this node */ setAttribute(name: string, value: string): void + /** Assign attributes K-V object to this node */ setAttributes(attrs: Record): void + /** Remove an attribute of this node by name */ removeAttribute(name: string): void + /** Remove all attributes of this node */ removeAllAttributes(): void + /** Select the the fist node that match the given selector, like document.querySelector. */ select(selectors: string): NodeRepr | null + /** Select all nodes that match the given selector, like document.querySelectorAll. */ selectAll(selectors: string): Array + /** Get all children nodes of this node. */ getChildren(): Array + /** Get attribute value of this node by given name. */ getAttribute(name: string): string | null + /** Get attributes K-V object of this node. */ getAttributes(): Record + /** Get the serialized html of this node, including its all descendants and itelf;. */ outerHtml(): string + /** Get the serialized html of this node, only including its all descendants;. */ innerHtml(): string + /** Get all text nodes content of this node, including its all descendants and itelf;. */ text(): string + /** Clone this node to a new instance, not clone its descendants. */ clone(): NodeRepr + /** Clone this node to a new instance, including its all descendants. */ cloneRecursive(): NodeRepr }