com.rpl.specter

ALL

Navigate to every element of the collection. For maps navigates to
a vector of `[key value]`.

ATOM

Navigates to atom value.

BEGINNING

Navigate to the empty subsequence before the first element of the collection.

bind-params*

Takes a compiled path that needs late-bound params and supplies it with
an array of params and a position in the array from which to begin reading
params. The return value is an executable selector.

codewalker

Like `walker` but maintains metadata of any forms traversed.

collect

(collect & path)
Adds the result of running select with the given path on the
current value to the collected vals.

collect-one

(collect-one & path)
Adds the result of running select-one with the given path on the
current value to the collected vals.

comp-paths

(comp-paths & apath)
Returns a compiled version of the given path for use with
compiled-{select/transform/setval/etc.} functions. This can compile navigators
(defined with `defnav`) without their parameters, and the resulting compiled
path will require parameters for all such navigators in the order in which
they were declared.

compiled-multi-transform

Version of `multi-transform` that takes in a path precompiled with `comp-paths`

compiled-replace-in

Version of replace-in that takes in a path precompiled with comp-paths

compiled-select

Version of select that takes in a path precompiled with comp-paths

compiled-select-any

Version of select-any that takes in a path precompiled with comp-paths

compiled-select-first

Version of select-first that takes in a path precompiled with comp-paths

compiled-select-one

Version of select-one that takes in a path precompiled with comp-paths

compiled-select-one!

Version of select-one! that takes in a path precompiled with comp-paths

compiled-selected-any?

Version of selected-any? that takes in a path precompiled with comp-paths

compiled-setval

Version of setval that takes in a path precompiled with comp-paths

compiled-transform

Version of transform that takes in a path precompiled with comp-paths

compiled-traverse

Version of traverse that takes in a path precompiled with comp-paths

cond-path

(cond-path & conds)
Takes in alternating cond-path path cond-path path...
Tests the structure if selecting with cond-path returns anything.
If so, it uses the following path for this portion of the navigation.
Otherwise, it tries the next cond-path. If nothing matches, then the structure
is not selected.

The input paths may be parameterized, in which case the result of cond-path
will be parameterized in the order of which the parameterized navigators
were declared.

continue-then-stay

(continue-then-stay & path)
Navigates to the provided path and then to the current element. This can be used
to implement post-order traversal.

continuous-subseqs

Navigates to every continuous subsequence of elements matching `pred`

DISPENSE

Drops all collected values for subsequent navigation.

END

Navigate to the empty subsequence after the last element of the collection.

filterer

(filterer & path)
Navigates to a view of the current sequence that only contains elements that
match the given path. An element matches the selector path if calling select
on that element with the path yields anything other than an empty sequence.

 The input path may be parameterized, in which case the result of filterer
 will be parameterized in the order of which the parameterized selectors
 were declared.

FIRST

Navigate to the first element of the collection. If the collection is
empty navigation is stopped at this point.

if-path

(if-path cond-p then-path)(if-path cond-p then-path else-path)
Like cond-path, but with if semantics.

keypath

Navigates to the specified key, navigating to nil if it does not exist.

LAST

Navigate to the last element of the collection. If the collection is
empty navigation is stopped at this point.

MAP-VALS

Navigate to each value of the map. This is more efficient than 
navigating via [ALL LAST]

META

Navigates to the metadata of the structure, or nil if
the structure has no metadata or may not contain metadata.

multi-path

(multi-path)(multi-path path)(multi-path path1 path2)(multi-path path1 path2 & paths)
A path that branches on multiple paths. For updates,
applies updates to the paths in order.

multi-transform*

(multi-transform* path structure)
Just like `transform` but expects transform functions to be specified
inline in the path using `terminal`. Error is thrown if navigation finishes
at a non-`terminal` navigator. `terminal-val` is a wrapper around `terminal` and is 
the `multi-transform` equivalent of `setval`.

must

Navigates to the key only if it exists in the map.

must-cache-paths!

Mandate that operations that do inline path factoring and compilation
(select/transform/setval/replace-in/path/etc.) must succeed in 
factoring the path into static and dynamic portions. If not, an
error will be thrown and the reasons for not being able to factor
will be printed. Defaults to false, and `(must-cache-paths! false)`
can be used to turn this feature off.

Reasons why it may not be able to factor a path include using
a local symbol, special form, or regular function invocation
where a navigator is expected.

NIL->LIST

Navigates to '() if the value is nil. Otherwise it stays
navigated at the current value.

NIL->SET

Navigates to #{} if the value is nil. Otherwise it stays
navigated at the current value.

nil->val

Navigates to the provided val if the structure is nil. Otherwise it stays
navigated at the structure.

NIL->VECTOR

Navigates to [] if the value is nil. Otherwise it stays
navigated at the current value.

NONE

Global value used to indicate no elements selected during
[[select-any]].

not-selected?

(not-selected? & path)

params-reset

(params-reset params-path)

parser

Navigate to the result of running `parse-fn` on the value. For 
transforms, the transformed value then has `unparse-fn` run on 
it to get the final value at this point.

pred

Keeps the element only if it matches the supplied predicate. This is the
late-bound parameterized version of using a function directly in a path.

putval

Adds an external value to the collected vals. Useful when additional arguments
are required to the transform function that would otherwise require partial
application or a wrapper function.

e.g., incrementing val at path [:a :b] by 3:
(transform [:a :b (putval 3)] + some-map)

replace-in*

(replace-in* path transform-fn structure & {:keys [merge-fn], :or {merge-fn concat}})
Similar to transform, except returns a pair of [transformed-structure sequence-of-user-ret].
The transform-fn in this case is expected to return [ret user-ret]. ret is
what's used to transform the data structure, while user-ret will be added to the user-ret sequence
in the final return. replace-in is useful for situations where you need to know the specific values
of what was transformed in the data structure.

select*

(select* path structure)
Navigates to and returns a sequence of all the elements specified by the path.

select-any*

(select-any* path structure)
Returns any element found or [[NONE]] if nothing selected. This is the most
efficient of the various selection operations.

select-first*

(select-first* path structure)
Returns first element found.

select-one!*

(select-one!* path structure)
Returns exactly one element, throws exception if zero or multiple elements found

select-one*

(select-one* path structure)
Like select, but returns either one element or nil. Throws exception if multiple elements found

selected-any?*

(selected-any?* path structure)
Returns true if any element was selected, false otherwise.

selected?

(selected? & path)
Filters the current value based on whether a path finds anything.
e.g. (selected? :vals ALL even?) keeps the current element only if an
even number exists for the :vals key.

The input path may be parameterized, in which case the result of selected?
will be parameterized in the order of which the parameterized navigators
were declared.

setval*

(setval* path val structure)
Navigates to each value specified by the path and replaces it by val

srange

Navigates to the subsequence bound by the indexes start (inclusive)
and end (exclusive)

srange-dynamic

Uses start-fn and end-fn to determine the bounds of the subsequence
to select when navigating. Each function takes in the structure as input.

STAY

Stays navigated at the current point. Essentially a no-op navigator.

stay-then-continue

(stay-then-continue & path)
Navigates to the current element and then navigates via the provided path.
This can be used to implement pre-order traversal.

STOP

Stops navigation at this point. For selection returns nothing and for 
transformation returns the structure unchanged

submap

Navigates to the specified submap (using select-keys).
In a transform, that submap in the original map is changed to the new
value of the submap.

subselect

(subselect & path)
Navigates to a sequence that contains the results of (select ...),
but is a view to the original structure that can be transformed.

Requires that the input navigators will walk the structure's
children in the same order when executed on "select" and then
"transform".

subset

Navigates to the specified subset (by taking an intersection).
In a transform, that subset in the original set is changed to the
new value of the subset.

terminal

For usage with `multi-transform`, defines an endpoint in the navigation
that will have the parameterized transform function run. The transform
function works just like it does in `transform`, with collected values
given as the first arguments

terminal-val

Like `terminal` but specifies a val to set at the location regardless of
the collected values or the value at the location.

transform*

(transform* path transform-fn structure)
Navigates to each value specified by the path and replaces it by the result of running
the transform-fn on it

transformed

(transformed path update-fn)
Navigates to a view of the current value by transforming it with the
specified path and update-fn.

The input path may be parameterized, in which case the result of transformed
will be parameterized in the order of which the parameterized navigators
were declared.

traverse*

(traverse* apath structure)
Return a reducible object that traverses over `structure` to every element
specified by the path

VAL

view

Navigates to result of running `afn` on the currently navigated value.

walker

Using clojure.walk, navigate the data structure until reaching
a value for which `afn` returns truthy.