hickory.select documentation

Functions to query hickory-format HTML data.

See clojure.zip for more information on zippers, locs, nodes, next, etc.

after-subtree

(after-subtree zip-loc)
Given a zipper loc, returns the zipper loc that is the first one after
the arg's subtree, if there is a subtree. If there is no loc after this
loc's subtree, returns the end node.

and

(and & selectors)
Takes any number of selectors and returns a selector that is true if
all of the argument selectors are true.

any

(any hzip-loc)
This selector takes no args, it simply is the selector function. It returns
true on any element it is called on; corresponds to the CSS '*' selector.

attr

(attr attr-name)(attr attr-name predicate)
Returns a function that takes a zip-loc argument and returns the
zip-loc passed in iff it has the given attribute, and that attribute
optionally satisfies a predicate given as an additional argument. With
a single argument, the attribute name (a string, keyword, or symbol),
the function returned will return the zip-loc if that attribute is
present (and has any value) on the zip-loc's node. The attribute name
will be compared case-insensitively, but the attribute value (if present),
will be passed as-is to the predicate.

If the predicate argument is given, it will only return the zip-loc if
that predicate is satisfied when given the attribute's value as its only
argument. Note that the predicate only gets called when the attribute is
present, so it can assume its argument is not nil.

child

(child & selectors)
Takes any number of selectors as arguments and returns a selector that
returns true when the zip-loc given as the argument is at the end of
a chain of direct child relationships specified by the selectors given as
arguments.

Example: (child (tag :div) (class :foo) (attr :disabled))
  will select the input in
<div><span class="foo"><input disabled></input></span></div>
  but not in
<div><span class="foo"><b><input disabled></input></b></span></div>

class

(class class-name)
Returns a function that takes a zip-loc argument and returns the
zip-loc passed in iff it has the given class. The class argument can
be a String or Named (keyword, symbol). The class name comparison
is done case-insensitively.

count-until

(count-until f val pred)
Calls f on val until pred called on the result is true. If not, it
repeats by calling f on the result, etc. The count of times this
process was repeated until pred returned true is returned.

descendant

(descendant & selectors)
Takes any number of selectors as arguments and returns a selector that
returns true when the zip-loc given as the argument is at the end of
a chain of descendant relationships specified by the
selectors given as arguments. To be clear, the node selected matches
the final selector, but the previous selectors can match anywhere in
the node's ancestry, provided they match in the order they are given
as arguments, from top to bottom.

Example: (descendant (tag :div) (class :foo) (attr :disabled))
  will select the input in both
<div><span class="foo"><input disabled></input></span></div>
  and
<div><span class="foo"><b><input disabled></input></b></span></div>

el-not

(el-not selector)
Takes a selector argument and returns a selector that is true if
the underlying selector is false on its argument and vice versa, and
additionally that argument is an element node. Compared to the 'not'
selector, this corresponds more closely to the CSS equivalent, which
will only ever select elements.

element

Another name for the any selector, to express that it can be used to only
select elements.

element-child

(element-child hzip-loc)
This selector takes no args, it simply is the selector function. It returns
the zip-loc passed in iff that loc is an element, and it has a parent
that is also an element.

find-in-text

(find-in-text re)
Returns a function that takes a zip-loc argument and returns the zip-loc
passed in iff it has some text node in its contents that matches the regular
expression. Note that this only applies to the direct text content of a node;
nodes which have the given text in one of their child nodes will not be
selected.

first-child

(first-child hzip-loc)
This selector takes no args, it is simply the selector. Returns
true if the node is the first child of its parent (and it has a
parent).

follow

(follow & selectors)
Takes any number of selectors as arguments and returns a selector that
returns true when the zip-loc given as the argument is at the end of
a chain of element sibling relationships specified by the selectors
given as arguments; intervening elements that do not satisfy a selector
are simply ignored and do not prevent a match.

Example: (follow (tag :div) (class :foo))
  will select the span in both
<div>...</div><span class="foo">...</span>
  and
<div>...</div><b>...</b><span class="foo">...</span>

follow-adjacent

(follow-adjacent & selectors)
Takes any number of selectors as arguments and returns a selector that
returns true when the zip-loc given as the argument is at the end of
a chain of direct element sibling relationships specified by the selectors
given as arguments.

Example: (follow-adjacent (tag :div) (class :foo))
  will select the span in
<div>...</div><span class="foo">...</span>
  but not in
<div>...</div><b>...</b><span class="foo">...</span>

has-child

(has-child selector)
Takes a selector as argument and returns a selector that returns true
when some direct child node of the zip-loc given as the argument satisfies
the selector.

Example: (has-child (tag :div))
  will select only the inner span in
<div><span><div></div></span></div>

has-descendant

(has-descendant selector)
Takes a selector as argument and returns a selector that returns true
when some descendant node of the zip-loc given as the argument satisfies
the selector.

Be aware that because this selector must do a full sub-tree search on
each node examined, it can have terrible performance. It's helpful if this is
a late clause in an `and`, to prevent it from even attempting to match
unless other criteria have been met first.

Example: (has-descendant (tag :div))
  will select the span and the outer div, but not the inner div, in
<span><div><div></div></div></span>

id

(id id)
Returns a function that takes a zip-loc argument and returns the
zip-loc passed in iff it has the given id. The id argument can be
a String or Named (keyword, symbol). The id name comparison
is done case-insensitively.

last-child

(last-child hzip-loc)
This selector takes no args, it is simply the selector. Returns
true if the node is the last child of its parent (and it has a
parent.

left-of-node-type

(left-of-node-type hzip-loc node-type)
Like clojure.zip/left, but only counts moves to nodes that have
the given type.

left-pred

(left-pred hzip-loc pred)
Like clojure.zip/left, but moves until it reaches a node that returns
true when the function in the pred argument is called on them, or reaches
the left boundary of the current group of siblings.

n-moves-until

(n-moves-until n c move term-pred)
This selector returns a selector function that selects its argument if
that argument is some "distance" from a "boundary." This is an abstract
way of phrasing it, but it captures the full generality.

The selector this function returns will apply the move argument to its own
output, beginning with its zipper loc argument, until the term-pred argument
called on its output returns true. At that point, the number of times the
move function was called successfully is compared to kn+c; if there exists
some value of k such that the two quantities are equal, then the selector
will return the argument zipper loc successfully.

For example, (n-moves-until 2 1 clojure.zip/left nil?) will return a selector
that calls zip/left on its own output, beginning with the argument zipper
loc, until its return value is nil (nil? returns true). Suppose it called
left 5 times before zip/left returned nil. Then the selector will return
with success, since 2k+1 = 5 for k = 2.

Most nth-child-* selectors in this package use n-moves-until in their
implementation.

next-of-node-type

(next-of-node-type hzip-loc node-type)
Like clojure.zip/next, but only counts moves to nodes that have
the given type.

next-pred

(next-pred hzip-loc pred)
Like clojure.zip/next, but moves until it reaches a node that returns
true when the function in the pred argument is called on them, or reaches
the end.

node-type

(node-type type)
Return a function that takes a zip-loc argument and returns the
zip-loc passed in iff it has the given node type. The type
argument can be a String or Named (keyword, symbol). The node type
comparison is done case-insensitively.

not

(not selector)
Takes a selector argument and returns a selector that is true if
the underlying selector is false on its argument, and vice versa.

nth-child

(nth-child c)(nth-child n c)
Returns a function that returns true if the node is the nth child of
its parent (and it has a parent). First element is 1, last is n.

nth-last-child

(nth-last-child c)(nth-last-child n c)
Returns a function that returns true if the node has n siblings after it,
and has a parent.

nth-last-of-type

(nth-last-of-type c typ)(nth-last-of-type n c typ)
Returns a function that returns true if the node is the nth last child of
its parent (and it has a parent) of the given tag type. First element is 1,
last is n.

nth-of-type

(nth-of-type c typ)(nth-of-type n c typ)
Returns a function that returns true if the node is the nth child of
its parent (and it has a parent) of the given tag type. First element is 1,
last is n.

or

(or & selectors)
Takes any number of selectors and returns a selector that is true if
any of the argument selectors are true.

ordered

(ordered move-fn & selectors)
Takes a zipper movement function and any number of selectors as arguments
and returns a selector that returns true when the zip-loc given as the
argument is satisfied by the first selector, and some zip-loc arrived at by
applying the move-fn argument *one or more times* is satisfied by the second
selector, and so on for all the selectors given as arguments. If the move-fn
moves to nil before a the full selector list is satisfied, the entire
selector fails, but note that success is checked before a move to nil is
checked, so satisfying the last selector with the last node you can move
to succeeds.

ordered-adjacent

(ordered-adjacent move-fn & selectors)
Takes a zipper movement function and any number of selectors as arguments
and returns a selector that returns true when the zip-loc given as the
argument is satisfied by the first selector, and the zip-loc arrived at by
applying the move-fn argument is satisfied by the second selector, and so
on for all the selectors given as arguments. If the move-fn
moves to nil before the full selector list is satisfied, the entire
selector fails, but note that success is checked before a move to nil is
checked, so satisfying the last selector with the last node you can move
to succeeds.

precede

(precede & selectors)
Takes any number of selectors as arguments and returns a selector that
returns true when the zip-loc given as the argument is at the beginning of
a chain of element sibling relationships specified by the selectors
given as arguments; intervening elements that do not satisfy a selector
are simply ignored and do not prevent a match.

Example: (precede (tag :div) (class :foo))
  will select the div in both
<div>...</div><span class="foo">...</span>
  and
<div>...</div><b>...</b><span class="foo">...</span>

precede-adjacent

(precede-adjacent & selectors)
Takes any number of selectors as arguments and returns a selector that
returns true when the zip-loc given as the argument is at the beginning of
a chain of direct element sibling relationships specified by the selectors
given as arguments.

Example: (precede-adjacent (tag :div) (class :foo))
  will select the div in
<div>...</div><span class="foo">...</span>
  but not in
<div>...</div><b>...</b><span class="foo">...</span>

prev-of-node-type

(prev-of-node-type hzip-loc node-type)
Like clojure.zip/prev, but only counts moves to nodes that have
the given type.

prev-pred

(prev-pred hzip-loc pred)
Like clojure.zip/prev, but moves until it reaches a node that returns
true when the function in the pred argument is called on them, or reaches
the beginning.

right-of-node-type

(right-of-node-type hzip-loc node-type)
Like clojure.zip/right, but only counts moves to nodes that have
the given type.

right-pred

(right-pred hzip-loc pred)
Like clojure.zip/right, but moves until it reaches a node that returns
true when the function in the pred argument is called on them, or reaches
the right boundary of the current group of siblings.

root

(root hzip-loc)
This selector takes no args, it simply is the selector function. It returns
the zip-loc of the root node (the HTML element).

select

(select selector-fn hickory-tree)
Given a selector function and a hickory data structure, returns a vector
containing all of the hickory nodes selected by the selector function.

select-locs

(select-locs selector-fn hickory-tree)
Given a selector function and a hickory data structure, returns a vector
containing all of the zipper locs selected by the selector function.

select-next-loc

(select-next-loc selector-fn hzip-loc)(select-next-loc selector-fn hzip-loc next-fn)(select-next-loc selector-fn hzip-loc next-fn end?-fn)
Given a selector function and a loc inside a hickory zip data structure,
returns the next zipper loc that satisfies the selection function. This can
be the loc that is passed in, so be sure to move to the next loc if you
want to use this function to exhaustively search through a tree manually.
Note that if there is no next node that satisfies the selection function, nil
is returned.

The third argument, if present, must be a function of one argument that is
called on a zipper loc to return the next loc to consider in the search. By
default, this argument is zip/next. The fourth argument, if present, must be
a function of one argument that is called on a zipper loc to determine if
the end of the search has been reached (true return value). When the fourth
argument returns true on a loc, that loc is not considered in the search and
the search finishes with a nil return. By default, the fourth argument is
zip/end?.

tag

(tag tag)
Return a function that takes a zip-loc argument and returns the
zip-loc passed in iff it has the given tag. The tag argument can be
a String or Named (keyword, symbol). The tag name comparison
is done case-insensitively.

until

(until f val pred)
Calls f on val until pred called on the result is true. If not, it
repeats by calling f on the result, etc. The value that made pred
return true is returned.