Struct soup::QueryBuilder

pub struct QueryBuilder<'a, T: Query + 'a = (), U: Query + 'a = ()> { /* fields omitted */ }

Construct a query to apply to an HTML tree

Example

let soup = Soup::new(r#"<div id="foo">BAR</div><div id="baz">QUUX</div>"#);
let query = soup.tag("div")         // result must be a div
                .attr("id", "foo")  // with id "foo"
                .find();            // executes the query, returns the first result

Implementations

impl<'a, T, U> QueryBuilder<'a, T, U> where
    T: Query + 'a,
    U: Query + 'a, 

pub fn limit(self, limit: usize) -> QueryBuilder<'a, T, U>

Adds a limit to the number of results that can be returned

This method adds an upper bound to the number of results that will be returned by the query

Example

let soup = Soup::new(r#"<div id="one"></div><div id="two"></div><div id="three></div>"#);
let results = soup.tag("div").limit(2).find_all().collect::<Vec<_>>();
assert_eq!(results.len(), 2);

pub fn tag<P: Pattern>(
    self,
    tag: P
) -> QueryBuilder<'a, TagQuery<P>, QueryWrapper<'a, T, U>>

Specifies a tag for which to search

Example

let soup =
    Soup::new(r#"<div>Test</div><section><b id="bold-tag">SOME BOLD TEXT</b></section>"#);
let result = soup.tag("b").find().expect("Couldn't find tag 'b'");
assert_eq!(result.get("id"), Some("bold-tag".to_string()));

pub fn attr_name<P>(
    self,
    name: P
) -> QueryBuilder<'a, AttrQuery<P, bool>, QueryWrapper<'a, T, U>> where
    P: Pattern, 

Searches for a tag that has an attribute with the specified name

Example

let soup = Soup::new(r#"<div>Test</div><section><b id="bold-tag">SOME BOLD TEXT</b></section>"#);
let result = soup.attr_name("id").find().expect("Couldn't find element with an 'id'");
assert_eq!(result.name(), "b");

pub fn attr_value<P>(
    self,
    value: P
) -> QueryBuilder<'a, AttrQuery<bool, P>, QueryWrapper<'a, T, U>> where
    P: Pattern, 

Search for a node with any attribute with a value that matches the specified value

Example

let soup = Soup::new(r#"<div>Test</div><section><b id="bold-tag">SOME BOLD TEXT</b></section>"#);
let result = soup.attr_value("bold-tag").find().expect("Couldn't find a tag with attribute value 'bold-tag'");
assert_eq!(result.name(), "b");

pub fn attr<P, Q>(
    self,
    name: P,
    value: Q
) -> QueryBuilder<'a, AttrQuery<P, Q>, QueryWrapper<'a, T, U>> where
    P: Pattern,
    Q: Pattern, 

Specifies an attribute name/value pair for which to search

Example

let soup =
    Soup::new(r#"<div>Test</div><section><b id="bold-tag">SOME BOLD TEXT</b></section>"#);
let result = soup.attr("id", "bold-tag").find().expect("Couldn't find tag with id 'bold-tag'");
assert_eq!(result.name(), "b".to_string());

pub fn class<P: Pattern>(
    self,
    value: P
) -> QueryBuilder<'a, AttrQuery<&'static str, P>, QueryWrapper<'a, T, U>>

Specifies a class name for which to search

Example

let soup = Soup::new(
    r#"<div>Test</div><section class="content"><b id="bold-tag">SOME BOLD TEXT</b></section>"#,
);
let result = soup.class("content").find().expect("Couldn't find tag with class 'content'");
assert_eq!(result.name(), "section".to_string());

pub fn recursive(self, recursive: bool) -> Self

Specifies whether the query should recurse all the way through the document, or stay localized to the queried tag and it’s children

pub fn find(self) -> Option<Handle>

Executes the query, and returns either the first result, or None

Example

let soup = Soup::new(
    r#"<ul><li id="one">One</li><li id="two">Two</li><li id="three">Three</li></ul>"#,
);
let result = soup.tag("li").find().expect("Couldn't find 'li'");
assert_eq!(result.get("id"), Some("one".to_string()));

pub fn find_all(self) -> Box<dyn Iterator<Item = Handle> + 'a>

Executes the query, and returns an iterator of the results

Example

let soup = Soup::new(
    r#"<ul><li id="one">One</li><li id="two">Two</li><li id="three">Three</li></ul>"#,
);
let results = soup.tag("li").find_all().collect::<Vec<_>>();
assert_eq!(results.len(), 3);
assert_eq!(results[0].display(), "<li id=\"one\">One</li>");
assert_eq!(results[1].display(), "<li id=\"two\">Two</li>");
assert_eq!(results[2].display(), "<li id=\"three\">Three</li>");

Trait Implementations

impl<'a, T: Query + 'a, U: Query + 'a> Debug for QueryBuilder<'a, T, U>

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

Formats the value using the given formatter.

impl<'a, T: Query + 'a, U: Query + 'a> IntoIterator for QueryBuilder<'a, T, U>

type IntoIter = Box<dyn Iterator<Item = Handle> + 'a>

Which kind of iterator are we turning this into?

type Item = Handle

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.