hickory.select — org.clj-commons/hickory 0.7.5

Functions to query hickory-format HTML data.

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

after-subtree clj/s

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

ancestor clj/s

(ancestor & 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 start of a chain of descendant 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: (ancestor (tag :div) (class :foo) (attr :disabled)) will select the div in both

<div><span class="foo"><input disabled></input></span></div> and <div><span class="foo"><b><input disabled></input></b></span></div>

and clj/s

(and & selectors)

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

any clj/s

(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 clj/s

(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 clj/s

(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 clj/s

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

compose-unary clj/s

(compose-unary unary-selector-fn & selectors)

Takes a unary selection function and any number of selectors and returns a selector which returns true when each selector and the unary function applied to each subsequenct selector returns true.

Example: (compose-unary has-child (tag :div) (class :foo) (attr :disabled)) Produces the equivalent of: (and (tag :div) (has-child (and (class :foo) (has-child (and (attr :disabled))))))

count-until clj/s

(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 clj/s

(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 clj/s

(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 clj/s

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

element-child clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(or & selectors)

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

ordered clj/s

(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 clj/s

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

parent clj/s

(parent & 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 start of a chain of direct child relationships specified by the selectors given as arguments.

Example: (parent (tag :div) (class :foo) (attr :disabled)) will select the div in

<div><span class="foo"><input disabled></input></span></div> but not in <div><span class="foo"><b><input disabled></input></b></span></div>

precede clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

(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 clj/s

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

up-pred clj/s

(up-pred hzip-loc pred)

Like clojure.zip/up, 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.