com.rpl.rama.path
AFTER-ELEM
Navigates on a sequence 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 sequence 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 sequence 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-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)))
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.
END
Navigates on a sequence 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.
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)
multi-transform
macro
(multi-transform apath structure)
multi-transformed
(multi-transformed path)
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. In Rama dataflow code, use NONE> rather than (termval NONE)
since NONE
cannot be used in dataflow code.
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.