tupelo.forest

Allows the use of multiple tree structures. Provides tools to create, manipulate, and query
the the trees individually and/or collectively.

enlive-subtree-buffer-size

dynamic

Default output buffer size for `filter-enlive-subtrees`.

->Node

(->Node hids)

Inputs: [hids :- [HID]]
Returns: Node

Constructs a Node from a vector of HIDs

add-bush

(add-bush bush)

Inputs: [bush]
Returns: HID

Adds a bush to the forest

add-node

(add-node attrs-arg)(add-node attrs-arg kid-hids)

Inputs: ([attrs-arg] [attrs-arg :- (s/if map? tsk/KeyMap s/Keyword) kid-hids :- [HID]])
Returns: HID

add-tree

(add-tree tree-node)

Inputs: [tree-node :- tsk/KeyMap]
Returns: HID

Adds a tree to the forest.

add-tree-edn

(add-tree-edn arg)

Inputs: [arg]
Returns: HID

Adds a EDN-format tree to the forest.

add-tree-enlive

(add-tree-enlive arg)

Inputs: [arg]
Returns: HID

Adds an Enlive-format tree to the forest

add-tree-hiccup

(add-tree-hiccup arg)

Inputs: [arg]
Returns: HID

Adds a Hiccup-format tree to the forest.

add-tree-html

(add-tree-html html-str)

Inputs: [html-str :- s/Str]
Returns: HID

Adds a tree to the forest from an HTML string.

add-tree-xml

(add-tree-xml xml-str)

Inputs: [xml-str :- s/Str]
Returns: HID

Adds a tree to the forest from an XML string.

all-hids

(all-hids)

Inputs: []
Returns: #{HID}

Returns a set of all HIDs in the forest

attr-get

(attr-get hid attr-name)

Inputs: [hid :- HID attr-name :- s/Keyword]
Returns: tsk/KeyMap

Use the supplied function & arguments to update the attr value for a Node as in clojure.core/update

attr-remove

(attr-remove hid attr)

Inputs: [hid :- HID attr :- s/Keyword]
Returns: tsk/KeyMap

Removes the specified attribute for an element

attr-set

(attr-set hid attr-name attr-val)

Inputs: [hid :- HID attr-name :- s/Keyword attr-val :- s/Any]
Returns: Node

Resets the value of a leaf

attr-update

(attr-update hid attr-name fn-update-attr & fn-update-attr-args)

Inputs: [hid :- HID attr-name :- s/Keyword fn-update-attr & fn-update-attr-args]
Returns: tsk/KeyMap

Use the supplied function & arguments to update the attr value for a Node as in clojure.core/update

attrs-merge

(attrs-merge hid attrs-in)

Inputs: [hid :- HID attrs-in :- tsk/KeyMap]
Returns: tsk/KeyMap

Merge the supplied attrs map into the attrs of a Node

attrs-set

(attrs-set hid attrs-new)

Inputs: [hid :- HID attrs-new :- tsk/KeyMap]
Returns: tsk/KeyMap

Replace the attrs of a Node with the supplied attrs map

bush->enlive

(bush->enlive bush)

Inputs: [bush :- tsk/Vec]
Returns: tsk/KeyMap

Converts a Bush to an Enlive-format data structure

bush->hiccup

(bush->hiccup arg)

Inputs: [arg :- tsk/Vec]
Returns: tsk/Vec

Converts a Bush to a Hiccup-format data structure.

bush->tree

(bush->tree bush)

Inputs: [bush]
Returns: tsk/KeyMap

Converts a bush to a tree

bush-node?

(bush-node? arg)

Inputs: [arg]
Returns: s/Bool

edn->tree

(edn->tree data)(edn->tree idx data)

Inputs: ([data :- s/Any] [idx :- (s/if int? s/Int (s/eq nil)) data :- s/Any])

Creates a tree from an EDN data structure

enlive->bush

(enlive->bush arg)

Inputs: [arg :- tsk/KeyMap]
Returns: tsk/Vec

Converts an Enlive-format data structure to a Bush.

enlive->hiccup

(enlive->hiccup node)

Inputs: [node :- s/Any]
Returns: s/Any

enlive->tree

(enlive->tree enlive-tree)

Inputs: [enlive-tree :- tsk/KeyMap]
Returns: tsk/KeyMap

Convert an Enlive-format data structure to a tree.  Is tolerant of missing or nil values
for :attrs and :content keys.

enlive-node-lax?

(enlive-node-lax? arg)

Returns true for nominal Enlive nodes, else false

enlive-node-strict?

(enlive-node-strict? arg)

Returns true for strictly valid Enlive nodes, else false

filter-enlive-subtrees

(filter-enlive-subtrees enlive-tree-lazy subtree-path)

Lazily read an enlive tree, retaining only rooted subtrees as specified by `subtree-path`

find-hid

(find-hid root-spec tgt-path)

Inputs: [root-spec :- HidRootSpec tgt-path :- tsk/Vec]
Returns: HID

Searches as with `find-hids`, expecting & returning a single HID result.

find-hids

(find-hids root-spec tgt-path)

Inputs: [root-spec :- HidRootSpec tgt-path :- tsk/Vec]
Returns: [HID]

Searches for subtrees as for `find-paths`, but retains only the HID of each subtree root (i.e. the last
element of each path vector)

find-hids-with

(find-hids-with root-spec tgt-path hid-pred)

Inputs: [root-spec :- HidRootSpec tgt-path :- tsk/Vec hid-pred :- s/Any]

Searches for subtrees as for `find-hids`, discarding HIDs that fail the `hid-pred` function.

find-paths

(find-paths root-spec tgt-path)

Inputs: [root-spec :- HidRootSpec tgt-path :- tsk/Vec]
Returns: [[HID]]

Searches the forest for subtrees matching the `tgt-path` rooted at `root-spec`.
Returns a vector of hid-paths.

find-paths-with

(find-paths-with root-spec tgt-path path-pred)

Inputs: [root-spec :- HidRootSpec tgt-path :- tsk/Vec path-pred :- s/Any]

Searches for subtrees as for `find-paths`, discarding paths that fail the `path-pred` function.

forest-hid?

(forest-hid? arg)

Returns true if the arg type is a legal HID value

format-path

(format-path hids)

Inputs: [hids :- [HID]]

Format an HID path for printing (bush format)

format-paths

(format-paths solns)

Inputs: [solns :- [[HID]]]

Format a list of HID paths for printing (bush format)

has-descendant-with?

(has-descendant-with? root-spec tgt-path path-pred)

Inputs: [root-spec :- HidRootSpec tgt-path :- tsk/Vec path-pred :- s/Any]

Returns true iff `root-hid` has at least one matching subtree, after discarding paths failing the 'path-pred' function.

has-descendant?

(has-descendant? root-hid tgt-path)

Inputs: [root-hid :- HID tgt-path :- tsk/Vec]

Returns true iff `root-hid` has at least one matching subtree

hiccup->bush

(hiccup->bush arg)

Inputs: [arg :- tsk/Vec]
Returns: tsk/Vec

Converts a Hiccup-format data structure to a Bush.

hiccup->enlive

(hiccup->enlive node)

Inputs: [node :- s/Any]
Returns: s/Any

Converts a data from Hiccup -> Enlive format

hiccup->tree

(hiccup->tree arg)

Inputs: [arg :- tsk/Vec]
Returns: tsk/KeyMap

Converts a Hiccup-format data structure to a Tree.

HID

The Plumatic Schema type name for a pointer to a forest node (abbrev. for Hex ID)

hid->attr

(hid->attr hid attr)

Inputs: [hid :- HID attr :- s/Keyword]
Returns: s/Any

Given an HID, returns the value of a single attr

hid->attrs

(hid->attrs hid)

Inputs: [hid :- HID]
Returns: tsk/KeyMap

Given an HID, returns all node attributes as a map

hid->bush

(hid->bush hid)

Inputs: [hid :- HID]
Returns: tsk/Vec

Returns the subtree rooted ad an HID (bush format)

hid->edn

(hid->edn hid)

Inputs: [hid :- HID]

Returns the data rooted ad an HID (EDN format)

hid->enlive

(hid->enlive hid)

hid->hiccup

(hid->hiccup hid)

Inputs: [hid :- HID]
Returns: tsk/Vec

Returns the subtree rooted ad an HID (hiccup format)

hid->kids

(hid->kids hid)

Inputs: [hid :- HID]
Returns: [HID]

Returns the HIDs for a nodes children.

hid->leaf

(hid->leaf hid)

Inputs: [hid :- HID]
Returns: Node

Returns the leaf node corresponding to an HID

hid->node

(hid->node hid)

Inputs: [hid :- HID]
Returns: Node

Returns the node corresponding to an HID

hid->tree

(hid->tree hid)

Inputs: [hid :- HID]
Returns: tsk/KeyMap

hid->value

(hid->value hid)

Inputs: [hid :- HID]
Returns: s/Any

Given an HID, returns the :value attribute

HidRootSpec

The Plumatic Schema type name for the values accepted as starting points (roots) for a subtree path search.

html->enlive

(html->enlive html-str)

Inputs: [html-str :- s/Str]
Returns: tsk/KeyMap

Interceptor

Plumatic Schema type name for interceptor type used by `walk-tree`.

kids-append

(kids-append hid kids-new)

Inputs: [hid :- HID kids-new :- [HID]]
Returns: tsk/KeyMap

Appends a list of kids a Node

kids-prepend

(kids-prepend hid kids-in)

Inputs: [hid :- HID kids-in :- [HID]]
Returns: tsk/KeyMap

Appends a list of kids a Node

kids-set

(kids-set hid kids-new)

Inputs: [hid :- HID kids-new :- [HID]]
Returns: Node

Resets the kids of a Node to the supplied list

kids-update

(kids-update hid fn-update-kids & fn-update-kids-args)

Inputs: [hid :- HID fn-update-kids & fn-update-kids-args]
Returns: tsk/KeyMap

Updates the kids for a Node using a function, as in clojure.core/update

leaf-hid?

(leaf-hid? hid)

Inputs: [hid :- HID]

Returns true iff an HID is a leaf

leaf-path?

(leaf-path? path)

Inputs: [path :- [HID]]
Returns: s/Bool

Returns true if an HID path ends in a leaf

new-forest

(new-forest)

Returns a new, empty forest.

new-hid

(new-hid)

Inputs: []
Returns: HID

Returns a new HexID

Node

The Plumatic Schema description of a legal node in a forest of trees

raw-leaf-treenode?

(raw-leaf-treenode? node)

Inputs: [node :- tsk/KeyMap]
Returns: s/Bool

Returns true if a TreeNode is a leaf with {:tag ::raw}.

raw-whitespace-leaf-treenode?

(raw-whitespace-leaf-treenode? node)

Inputs: [node :- tsk/KeyMap]
Returns: s/Bool

Returns true if a TreeNode is a leaf with {:tag ::raw} and whitespace value.

remove-kids

(remove-kids hid kids-leaving)(remove-kids hid kids-leaving missing-kids-ok?)

Inputs: ([hid :- HID kids-leaving :- (s/if sequential? [HID] #{HID})] [hid :- HID kids-leaving :- (s/if sequential? [HID] #{HID}) missing-kids-ok? :- s/Bool])
Returns: tsk/KeyMap

Removes a set of children from a Node (including any duplcates).

remove-path-subtree

(remove-path-subtree path)

Inputs: [path :- [HID]]

Given an HID path, removes from the forest all nodes in the subtree rooted at the end of that path.

remove-whitespace-leaves

deprecated

(remove-whitespace-leaves)(remove-whitespace-leaves root-hid)

Inputs: ([] [root-hid :- HID])

Removes leaves from all trees in the forest that are whitespace-only strings
(including zero-length strings).

root-hids

(root-hids)

Inputs: []
Returns: #{HID}

Return a vector of all root HID's

set-node

(set-node hid node)(set-node hid attrs kids)

Inputs: ([hid :- HID node :- Node] [hid :- HID attrs :- tsk/KeyMap kids :- [HID]])

Unconditionally sets the value of a Node in the forest

tree->bush

(tree->bush tree-node)

Inputs: [tree-node :- tsk/Map]
Returns: tsk/Vec

tree->edn

(tree->edn node)

Converts a tree to an EDN data structure

tree->enlive

(tree->enlive tree-node)

Inputs: [tree-node :- tsk/KeyMap]
Returns: (s/if map? tsk/KeyMap tsk/Vec)

tree->hiccup

(tree->hiccup arg)

Inputs: [arg :- tsk/KeyMap]
Returns: tsk/Vec

Converts a Tree to a Hiccup-format data structure.

tree-node?

(tree-node? node)

Inputs: [node :- tsk/KeyMap]
Returns: s/Bool

Returns true if the arg is a legal tree node

valid-forest-leaf?

(valid-forest-leaf? node)

Inputs: [node :- tsk/KeyMap]
Returns: s/Bool

Returns true if the arg is a forest leaf node (empty :tupelo.forest/khids).

valid-forest-node?

(valid-forest-node? arg)

Inputs: [arg :- tsk/KeyMap]
Returns: s/Bool

Returns true if the arg is a legal forest node

validate-attrs

(validate-attrs attrs)

Inputs: [attrs :- tsk/KeyMap]
Returns: tsk/KeyMap

validate-forest

(validate-forest)

validate-hid

(validate-hid hid)

Inputs: [hid :- HID]

Returns HID arg iff it exists in the forest, else throws.

walk-tree

(walk-tree root-hid intc-map)

Inputs: [root-hid :- HID intc-map :- tsk/KeyMap]

Recursively walks a subtree of the forest, applying the supplied `:enter` and ':leave` functions
 to each node.   Usage:

     (walk-tree <subtree-root-hid> intc-map)

 where `intc-map` is an interceptor map like:

     { :enter <pre-fn>       ; defaults to `identity`
       :leave <post-fn> }    ; defaults to `identity`

 Here, `pre-fn` and `post-fn` look like:

     (fn [path] ...)

 where `path` is a vector of HIDs beginning at the root of the sub-tree being walked.

whitespace-leaf-hid?

(whitespace-leaf-hid? hid)

Inputs: [hid :- HID]
Returns: s/Bool

Returns true iff an HID is a leaf node (no children) and has a `:value` attribute containing only whitespace.

with-forest

macro

(with-forest forest-arg & forms)

with-forest-result