com.rpl.rama.path

AFTER-ELEM

Navigates on a list to void element at end. Used in transforms to append a single element. Virtual value navigator.

For proxies transforms with this navigator produce SequenceInsertDiff.

ALL

Navigates to every element of a collection. Works on lists, maps, and sets. For maps navigates to key/value pair with {@link java.util.List} interface. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce diffs according to the type of data structure involved. For sequences produces SequenceIndexChangesDiff, SequenceIndexRemoveDiff, or a combination. For sets produces SetAddDiff, SetRemoveDiff, or a combination. For maps produces KeyDiff, KeyRemoveDiff, or a combination. When multiple diffs are produced they are combined with MultiDiff.

ATOM

Navigates to atom value.

BEFORE-ELEM

Navigates on a list to void element at beginning. Used in transforms to prepend a single element. Virtual value navigator.

For proxies transforms with this navigator produce SequenceInsertDiff.

before-index

(before-index index)

Navigates on list to void element before an index. Used in transforms to insert an element in middle of list. Virtual value navigator.

For proxies transforms with this navigator produce SequenceInsertDiff.

BEGINNING

Navigates on a list to empty subsequence at beginning. Used in transforms to prepend multiple elements. Substructure navigator.

For proxies transforms with this navigator produce SequenceInsertsDiff.

collect

(collect path)

Collects a list of values selected with given path from current point.

collect-one

(collect-one path)

Collects a single value selected with given path from current point. Exception if path selects zero values or more than one value.

collected?

macro

(collected? params & body)

Stops navigation if given function on collected values returns false. Otherwise, stays navigated at current point. Filter navigator.

comp-navs

This is an advanced navigator composition function that should only be used with instances of RichNavigator. Should generally prefer path instead.

comp-paths

(comp-paths & apath)

Returns a compiled version of the given path for use with compiled-{select/transform/setval/etc.} functions.

cond-path

(cond-path & path-pairs)

Alternates condition path with subsequent navigation paths. Condition path is considered true if it selects anything. Continues navigation with navigation path for first condition path to meet this condition.

Example:

(cond-path
  #(> (count %) 2) [:a MAP-VALS]
  [MAP-VALS even?] :b)

continue-then-stay

Navigates to the provided path and then to the current element. This can be used to implement post-order traversal.

continuous-subseqs

(continuous-subseqs bounds-fn)

Navigates to every continuous subsequence of elements based on bounds-fn. bounds-fn is function of element and result of bounds-fn on previous element. Truthy returns are matched into a subsequence.

Example:

(let [bounds (fn [elem prev]
               (cond
                 (identical? :START elem) true
                 (identical? :END elem) :END
                 (identical? :END prev) false
                 :else prev
               ))]
  (is (= [5 6 7]
         (setval (continuous-subseqs bounds)
                 nil
                 [:START 1 2 3 :END 5 6 7 :START 8 9 :END]))))

declarepath

macro

(declarepath name)

Declares a var to provide a path implementation later with providepath.

defcollector

macro

(defcollector name params [_ [_ structure-sym] & body])

Defines a collector that adds a value to collected list based on currently navigated value.

Example:

(defcollector MY-COLLECTOR
              []
              (collect-val [this structure]
                 (-> structure :a :b :c)))

defdynamicnav

macro

(defdynamicnav name & args)

Defines a function that can choose what navigator to use at runtime based on the dynamic context. The arguments will either be static values or objects satisfying dynamic-param?. Use late-bound to produce a runtime navigator that uses the values of the dynamic params. See selected? for an illustrative example of dynamic navs.

defnav

macro

See this page for an overview of defining new navigators with defnav.

defprotocolpath

macro

(defprotocolpath name)(defprotocolpath name params)

Defines a navigator that chooses the path to take based on the type of the value at the current point. See this page for more details.

DISPENSE

Drops all collected values for subsequent navigation.

dynamic-param?

(dynamic-param? object)

This function is used with defdynamicnav. True if object is a dynamic param.

eachnav

Turns a navigator that takes one argument into a navigator that takes many arguments and uses the same navigator with each argument. There is no performance cost to using this. See implementation of keypath

END

Navigates on a list to empty subsequence at end. Used in transforms to append multiple elements. Substructure navigator.

For proxies transforms with this navigator produce SequenceInsertsDiff.

extend-protocolpath

macro

(extend-protocolpath protpath & extensions)

Used in conjunction with defprotocolpath. See defprotocolpath.

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.

For transformation: NONE entries in the result sequence cause corresponding entries in input to be removed. A result sequence smaller than the input sequence is equivalent to padding the result sequence with NONE at the end until the same size as the input.

FIRST

Navigates on list to first element if not empty. If empty, stops navigation. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce SequenceIndexChangeDiff or SequenceIndexRemoveDiff.

if-path

(if-path cond-path then-path)(if-path cond-path then-path else-path)

Like cond-path, but with if semantics.

index-nav

(index-nav index)

Navigates to the index of a list if it exists. This navigates to the index, not to the value at that index. Changing the index in a transform will move the element in the resulting list. Value navigator.

For proxies transforms with this navigator produce SequenceReorderDiff.

INDEXED-VALS

indexed-vals with a starting index of 0.

indexed-vals

(indexed-vals start-index)

Navigates to pairs of [index, value] for every element of list, starting from start-index. Pairs are represented as lists of two elements. Transforms should produce new [index, value] pairs. Changing an index in a transform will move the element in the resulting list. Value navigator.

keypath

(keypath & keys)

Navigates to value for a key in a map. For convenience, can navigate into further nested maps by providing multiple key arguments. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce KeyDiff or KeyRemoveDiff.

LAST

Navigates on list to last element if not empty. If empty, stops navigation. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce SequenceIndexChangeDiff or SequenceIndexRemoveDiff.

late-bound

macro

(late-bound bindings & body)

Macro to efficiently resolve dynamic arguments from inline compilation to construct a navigator. Binding values can be static or dynamic params, and binding vars will be resolved to the runtime values. Use with late-path or late-resolved-fn to inform inline compiler how to handle those params.

Example:

(defdynamicnav
 my-dynamic-nav
 [i path]
 (late-bound [latei i
              late-path (late-path path)]
  (comp-navs (nthpath i) (selected? late-path))))

late-path

(late-path param)

Marks a potentially dynamic param as being a path, informing the inline compiler to optimize that param as a path.

late-resolved-fn

(late-resolved-fn param)

Marks a potentially dynamic param as resolving to a function, informing the inline compiler to optimize that accordingly. If it’s an expression with all static params, it will be resolved at compile-time. Otherwise, an expression to resolve at runtime is inserted.

local-declarepath

(local-declarepath)

Declare a path whose implementation will be provided later with providepath. Used to create recursive or mutually recursive paths.

map-key

(map-key key)

Navigates to a key in a map if it exists. In transforms, changing the key is the same as removing the original key and then adding the updated key with the original value. This navigator is generally only useful in transforms. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce KeyChangeDiff or KeyRemoveDiff.

MAP-KEYS

Navigates to every key of a map. In transforms, changing a key is the same as removing the original key and then adding the updated key with the original value. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce KeysRemoveDiff, KeysDiff, or a combination of the two with MultiDiff.

MAP-VALS

Navigates to every value of a map. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce KeysRemoveDiff, KeysDiff, or a combination of the two with MultiDiff.

multi-path

(multi-path & paths)

Navigates to each provided path in order, all starting from this point. Control navigator.

For proxies transforms with this navigator produce MultiDiff.

multi-transform

macro

(multi-transform apath structure)

Just like transform but expects transform functions to be specified inline in the path using term or termval. Error is thrown if navigation finishes at a non-terminal navigator. This macro will do inline caching of the path.

multi-transformed

(multi-transformed path)

Navigates to a view of the current value by transforming it with the specified path. The terminal positions of the path must be term or termval.

must

(must & keys)

Navigates to value for a key in a map only if key exists. If key does not exist, stops navigation. For convenience, can navigate into further nested maps by providing multiple key arguments. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce KeyDiff or KeyRemoveDiff.

NAME

Navigates to the name portion of the keyword or symbol.

NAMESPACE

Navigates to the namespace portion of the keyword or symbol.

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

(nil->val val)

Navigates to the provided value 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. Also used in transforms to remove elements from data structures.

NONE->val

Navigates to the provided val if the structure is NONE. Otherwise it stays navigated at the structure. Only valid in transforms.

NONE-ELEM

Navigates to void element of set. Used to add a single element to a set in transforms. Virtual value navigator.

For proxies transforms with this navigator produce SetAddDiff.

NONE?

Returns true if the given value is NONE, false otherwise.

not-selected?

(not-selected? & path)

Continues navigation if provided path executed on current value navigates to zero values. Otherwise, stops current branch of navigation. Filter navigator.

nthpath

(nthpath & indices)

Navigates to value for index in a list. For convenience, can navigate into further nested lists by providing multiple index arguments. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce SequenceIndexChangeDiff or SequenceIndexRemoveDiff.

parser

(parser parse-fn unparse-fn)

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.

path

macro

(path & path)

Same as calling comp-paths, except it caches the composition of the static parts of the path at compile-time for later re-use (when possible). For almost all idiomatic uses provides huge speedup. This macro is automatically used by the select/transform/setval/replace-in/etc. macros.

pred

(pred afn)

Continues navigation if provided function returns true on current value. Otherwise, stops current branch of navigation. Filter navigator.

pred<

(pred< v)

Same as (pred #(< % v)).

pred<=

(pred<= v)

Same as (pred #(<= % v)).

pred=

(pred= v)

Same as (pred #(= % v)).

pred>

(pred> v)

Same as (pred #(> % v)).

pred>=

(pred>= v)

Same as (pred #(>= % v)).

providepath

macro

(providepath name apath)

Provide a path implementation for a previously declared declarepath or local-declarepath.

putval

(putval val)

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

Example:

(transform [:a :b (putval 3)] + some-map)

This increments the value at path [:a :b] by 3:

recursive-path

macro

(recursive-path params self-sym path)

Defines a path that can refer to itself recursively.

Example:

(def TreeValues
  (recursive-path [] p
    (if-path vector?
      [ALL p]
      STAY
      )))

This navigates to every leaf of a tree represented as nested vectors.

select

macro

(select apath structure)

Navigates to and returns a sequence of all the elements specified by the path. This macro will do inline caching of the path.

select-any

macro

(select-any apath structure)

Returns any element found or NONE if nothing selected. This is the most efficient of the various selection operations. This macro will do inline caching of the path.

select-first

macro

(select-first apath structure)

Returns first element found. This macro will do inline caching of the path.

select-one

macro

(select-one apath structure)

Like select, but returns either one element or nil. Throws exception if multiple elements found. This macro will do inline caching of the path.

select-one!

macro

(select-one! apath structure)

Returns exactly one element, throws exception if zero or multiple elements found. This macro will do inline caching of the path.

selected-any?

macro

(selected-any? apath structure)

Returns true if any element was selected, false otherwise. This macro will do inline caching of the path.

selected?

(selected? & path)

Continues navigation if provided path executed on current value navigates to at least one value. Otherwise, stops current branch of navigation. Filter navigator.

set-elem

(set-elem elem)

Navigates to element of set if it exists. If element does not exist, stops navigation. Can transform to NONE to remove element. Value navigator.

For proxies transforms with this navigator produce SetAddDiff, SetRemoveDiff, or a combination with MultiDiff.

setval

macro

(setval apath aval structure)

Navigates to each value specified by the path and replaces it by aval. This macro will do inline caching of the path.

sorted-map-range

(sorted-map-range start-key end-key)(sorted-map-range start-key end-key options)

Navigates to the sorted submap bound by the keys start-key and end-key. Options map accepts :inclusive-start? and :inclusive-end?, defaulting to true and false respectively. Useful on subindexed maps. Substructure navigator.

For proxies transforms with this navigator that do fine-grained updates to the submap produce KeysRemoveDiff, KeysDiff, or a combination of the two with MultiDiff. If the submap is modified in a coarse-grained way (e.g. overridden completely with termVal), this navigator will produce a NewValueDiff.

sorted-map-range-from

(sorted-map-range-from start-key)(sorted-map-range-from start-key max-amt-or-options-map)

Navigates to the sorted submap starting at the key start-key. Second argument can be a number for max amount to fetch or a map that accepts :max-amt and :inclusive? (defaults to true). Useful on subindexed maps. Substructure navigator.

For proxies transforms with this navigator that do fine-grained updates to the submap produce KeysRemoveDiff, KeysDiff, or a combination of the two with MultiDiff. If the submap is modified in a coarse-grained way (e.g. overridden completely with termVal), this navigator will produce a NewValueDiff.

sorted-map-range-to

(sorted-map-range-to end-key)(sorted-map-range-to end-key max-amt-or-options-map)

Navigates to the sorted submap up to the key end-key. Second argument can be a number for max amount to fetch (reading backwards from that key) or a map accepts :max-amt and :inclusive? (defaults to false). Useful on subindexed maps. Substructure navigator.

For proxies transforms with this navigator that do fine-grained updates to the submap produce KeysRemoveDiff, KeysDiff, or a combination of the two with MultiDiff. If the submap is modified in a coarse-grained way (e.g. overridden completely with termVal), this navigator will produce a NewValueDiff.

sorted-set-range

(sorted-set-range start-elem end-elem)(sorted-set-range start-elem end-elem options)

Navigates to the sorted subset bound by start-elem and end-elem. Options map accepts :inclusive-start? and :inclusive-end?, defaulting to true and false respectively. Useful on subindexed sets. Substructure navigator.

sorted-set-range-from

(sorted-set-range-from start-elem)(sorted-set-range-from start-elem max-amt-or-options-map)

Navigates to the sorted subset starting at start-elem. Second argument can be a number for max amount to fetch or a map that accepts :max-amt and :inclusive? (defaults to true). Useful on subindexed sets. Substructure navigator.

sorted-set-range-to

(sorted-set-range-to end-elem)(sorted-set-range-to end-elem max-amt-or-options-map)

Navigates to the sorted subset up to end-elem. Second argument can be a number for max amount to fetch (reading backwards from that element) or a map that accepts :max-amt and :inclusive? (defaults to false). Useful on subindexed sets. Substructure navigator.

srange

(srange start end)

Navigates to sublist bounded by two indexes. Substructure navigator.

For proxies transforms with this navigator produce sequence diffs according to the rest of the transform path.

srange-dynamic

(srange-dynamic start-fn end-fn)

Navigates to sublist bounded by indexes chosen by functions. Substructure navigator.

start-fn takes in the structure as input, and end-fn takes in the structure and the result of start-fn.

For proxies transforms with this navigator produce sequence diffs according to the rest of the transform path.

STAY

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

STOP

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

submap

(submap keys)

Navigates to a map containing subset of keys/values of starting map. Substructure navigator.

For proxies transforms with this navigator that do fine-grained updates to the submap produce KeysRemoveDiff, KeysDiff, or a combination of the two with MultiDiff. If the submap is modified in a coarse-grained way (e.g. overridden completely with termval), this navigator will produce a NewValueDiff.

subselect

(subselect & path)

Navigates to list of values navigated by provided path. Transforms on that list will update original locations of each value, no matter how nested. Control navigator.

For proxies transforms with this navigator produce diffs according to rest of transform path.

subset

(subset elems)

Navigates to subset of starting set with given elements. Substructure navigator.

For proxies transforms with this navigator produce SetAddDiff, SetRemoveDiff, or a combination with MultiDiff.

term

(term term-obj)

For usage with multi-transform or local-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

termval

(termval v)

Like term but specifies a val to set at the location regardless of the collected values or the value at the location. NONE is a special value that can be set to indicate a navigator should perform a removal of the key leading to that value. In Rama dataflow code NONE> should be used instead of (termval NONE)

transform

macro

(transform apath transform-obj structure)

Navigates to each value specified by the path and replaces it by the result of running the transform function on it. Any values collected in the path will be the first arguments to the transform function. This macro will do inline caching of the path.

transformed

(transformed path update-fn)

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

traverse

macro

(traverse apath structure)

Return a reducible object that traverses over structure to every element specified by the path. This macro will do inline caching of the path.

traverse-all

macro

(traverse-all apath)

Returns a transducer that traverses over each element with the given path.

VAL

Collects the currently navigated value.

view

(view afn)(view afn & args)

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

For proxies transforms with this navigator produce NewValueDiff.

with-fresh-collected

(with-fresh-collected & path)

Continues navigating on the given path with the collected values reset to []. Once navigation leaves the scope of with-fresh-collected, the collected values revert to what they were before.