Visdom

A html DOM operation library written in Rust，like the Nodejs's cheerio library, they used the same API style of jQuery。

Usage

中文 API 文档

Cargo.toml

toml [depedencies] visdom = {git = "https://github.com/fefit/visdom", tag = "v0.0.7", version = "0.0.7"}

main.rs

```rust use visdom::Vis; use std::error::Error;

fn main()-> Result<(), Box>{ let html = r##"

"##; // load html let nodes = Vis::load(html)?; let listext = nodes.find("#header li").text(); println!("{}", listext); // will output "Hello,VisDom" } ```

Vis

Static method：load(html: &str) -> Result<NodeList, Box<dyn Error>>

Load the `html` string into a document `NodeList`

Static method：load_catch(html: &str, handle: Box<dyn Fn(Box<dyn Error>)>) -> NodeList

Load the `html` string into a document `NodeList`, and use the handle to do with the errors such as html parse error, wrong selectors, this is useful if you don't want the process paniced by the errors.

Static method：dom(ele: &BoxDynNode) -> NodeList

Change the `ele` node to single node `NodeList`, this will copy the `ele`, you don't need it if you just need do something with methods of the `BoxDynNode` its'own.

e.g.：

rust // go on the code before let texts = lis.map(|_index, ele|{ let ele = Vis::dom(ele); return String::from(ele.text()); }); // now `texts` will be a `Vec<String>`: ["Hello,", "Vis", "Dom"]

API

The following API are inherited from the library mesdoc 。

Selector Operation

| Selector API | Description | Remarks | | :----------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------: | | The caller Self is a NodeList, Return NodeList | Tha all APIs are same with the jQuery library | | | find(selector: &str) | Get the descendants of each element in the Self, filtered by the selector. | | | filter(selector: &str) | Reduce Self to those that match the selector. | | | filter_by(handle: |index: usize, ele: &BoxDynNode| -> bool) | Reduce Self to those that pass the handle function test. | | | filter_in(nodelist: &NodeList) | Reduce Self to those that also in the node_list | | | not(selector: &str) | Remove elements those that match the selector from Self. | | | not_by(handle: |index: usize, ele: &BoxDynNode| -> bool) | Remove elements those that pass the handle function test from Self. | | | not_in(nodelist: &NodeList) | Remove elements those that also in the node_list from Self. | | | is(selector: &str) | Check at least one element in Self is match the selector. | | | is_by(handle: |index: usize, ele: &BoxDynNode| -> bool) | Check at least one element call the handle function return true. | | | is_in(nodelist: &NodeList) | Check at least one element in Self is also in node_list. | | | is_all(selector: &str) | Check if each element in Self are all matched the selector. | | | is_all_by(handle: |index: usize, ele: &BoxDynNode| -> bool) | Check if each element in Self call the handle function are all returned true. | | | is_all_in(nodelist: &NodeList) | Check if each element in Self are all also in node_list. | | | has(selector: &str) | Reduce Self to those that have a descendant that matches the selector. | | | has_in(node_list: &NodeList) | Reduce Self to those that have a descendant that in the node_list. | | | children(selector: &str) | Get the children of each element in Self, when the selector is not empty, will filtered by the selector. | | | parent(selector: &str) | Get the parent of each element in Self, when the selector is not empty, will filtered by the selector. | | | parents(selector: &str) | Get the ancestors of each element in Self, when the selector is not empty, will filtered by the selector. | | | siblings(selector: &str) | Get the siblings of each element in Self, when the selector is not empty, will filtered by the selector. | | | next(selector: &str) | Get the next sibling of each element in Self, when the selector is not empty, will filtered by the selector. | | | next_all(selector: &str) | Get all following siblings of each element in Self, when the selector is not empty, will filtered by the selector. | | | prev(selector: &str) | Get the previous sibling of each element in Self, when the selector is not empty, will filtered by the selector. | | | prev_all(selector: &str) | Get all preceding siblings of each element in Self, when the selector is not empty, will filtered by the selector. | | | eq(index: usize) | Get one element at the specified index. | | | slice(range: Range) | Get a subset specified by a range of indices. | e.g.:slice(0..=2), will match the first three element. |

Helpers

| Helper API | Description | Remarks | | :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------: | | length() | Get the number of Self's element. | | | is_empty() | Check if Self has no element, length() == 0. | | | for_each(handle: |index: usize, ele: &mut BoxDynNode| -> bool) | Iterate over the elements in Self, when the handle return false, stop the iterator. | You can also use each if you like less code. | | map<T>(|index: usize, ele: &BoxDynNode| -> T) -> Vec<T> | Get a collection of values by iterate the each element in Self and call the handle function. | | | sort() | Sort each element in Self by the appear order in the html document.This should only used when you use a find method that the selector is a selector list, e.g. find(".a,.b"), which .a and .b are not ordered. | |

Supported Selectors

| Selectors | Description | Remarks | | :------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------: | | * | MDN Universal Selectors | | | #id | MDN Id Selector | | | .class | MDN Class Selector | | | p | MDN Type Selectors | | | [attr] | MDN Attribute Selectors | | | [attr=value] | See the above. | | | [attr*=value] | See the above. | | | [attr|=value] | See the above. | | | [attr~=value] | See the above. | | | [attr^=value] | See the above. | | | [attr$=value] | See the above. | | | [attr!=value] | jQuery supported, match the element that has an attribute of attr，but it's value is not equal to value. | | | span > a | MDN Child Combinator | match the element of a that who's parent is a span | | span a | MDN Descendant Combinator | | | span + a | MDN Adjacent Sibling Combinator | | | span ~ a | MDN Generic Sibling Combinator | | | span,a | MDN Selector list | | | span.a | Adjoining Selectors | match an element that who's tag type is span and also has a class of .a | | :empty | MDN :empty | Pseudo Selectors | | :first-child | MDN :first-child | | | :last-child | MDN :last-child | | | :only-child | MDN :only-child | | | :nth-child(nth) | MDN :nth-child() | nth support keyword odd and even | | :nth-last-child(nth) | MDN :nth-last-child() | | | :first-of-type | MDN :first-of-type | | | :last-of-type | MDN :last-of-type | | | :only-of-type | MDN :only-of-type | | | :nth-of-type(nth) | MDN :nth-of-type() | | | :nth-last-of-type(nth) | MDN :nth-last-of-type() | | | :not(selector) | MDN :not() | | | :header | All title tags，alias of: h1,h2,h3,h4,h5,h6. | | | :input | All form input tags, alias of: input,select,textarea,button. | | | :submit | Form submit buttons, alias of: input\[type="submit"\],button\[type="submit"\]. | |

Attribute Operation

| Attribute API | Description | Remarks | | :------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------------------------------------------------------------------------------------: | | attr(attrname: &str) -> Option<IAttrValue> | Get an atrribute of key attr_name | The return value is an Option Enum IAttrValue, IAttrValue has is_true(), is_str(&str), to_list() methods. | | set_attr(attrname: &str, value: Option<&str>) | Set an attribute of key attr_name，the value is an Option<&str>, when the value is None，that means the attribute does'n have a string value, it's a bool value of true. | | | remove_attr(attrname: &str) | Remove an attribute of key attr_name. | | | has_class(classname: &str) | Check if Self's ClassList contains class_name, multiple classes can be splitted by whitespaces. | | | add_class(classname: &str) | Add class to Self's ClassList, multiple classes can be splitted by whitespaces. | | | remove_class(classname: &str) | Remove class from Self's ClassList, multiple classes can be splitted by whitespaces.名 | | | toggle_class(class_name: &str) | Toggle class from Self's ClassList, multiple classes can be splitted by whitespaces.加 | |

Content Operation

| Content API | Description | Remarks | | :------------------------------- | :------------------------------------------------------------------------- | :-----: | | text() | Get the text of each element in Self，the html entity will auto decoded. | | | set_text(content: &str) | Set the Self's text, the html entity in content will auto encoded. | | | html() | Get the first element in Self's html. | | | set_html(content: &str) | Set the html to content of each element in Self. | | | outer_html() | Get the first element in Self's outer html. | |

DOM Operation

| DOM Insertion and Remove API | Description | Remarks | | :---------------------------------------- | :---------------------------------------------------------------------------------- | :-----: | | append(nodes: &NodeList) | Append all nodes into Self, after the last child | | | append_to(nodes: &mut NodeList) | The same as the above，but exchange the caller and the parameter target. | | | prepend(nodes: &mut NodeList) | Append all nodes into Self, befpre the first child | | | prepend_to(nodes: &mut NodeList) | The same as the above，but exchange the caller and the parameter target. | | | insert_after(nodes: &NodeList) | Insert all nodes after Self | | | after(nodes: &mut NodeList) | The same as the above，but exchange the caller and the parameter target. | | | insert_before(nodes: &NodeList) | Insert all nodes before Self | | | before(nodes: &mut NodeList) | The same as the above，but exchange the caller and the parameter target. | | | remove() | Remove the Self, it will take the ownership of Self, so you can't use it again. | | | empty() | Clear the all childs of each element in Self. | |

Example

``rust let html = r##" <div id="container"> <div class="first-child"></div> <div class="second-child"></div> </div> "##; let root = Vis::load(html); let child = root.find(".child"); let mut container = root.find("#container"); // append thechildelement to thecontainer` container.append(&child); // then the code become to below /*

/ // create new element by Vis::load let third_child = Vis::load(r##"

"##); container.append(&third_child); // then the code become to below /

*/ ```

Depedencies

Questions & Advices & Bugs?

Welcome to report Issue to us if you have any question or bug or good advice.

License

MIT License.