luciano/specter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

add docstrings to the core select/transform/etc. macros

Browse source
This commit is contained in:
Nathan Marz 2016-06-04 09:29:45 -04:00
parent e1138747d9
commit d9443232d8
2 changed files with 46 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
src/clj/com/rpl/specter.cljx
View file

@ -40,7 +40,7 @@
;; Selection functions
(def ^{:doc "Version of select that takes in a path pre-compiled with comp-paths"}
(def ^{:doc "Version of select that takes in a path precompiled with comp-paths"}
compiled-select i/compiled-select*)
(defn select*

51
src/clj/com/rpl/specter/macros.clj
View file

@ -496,25 +496,64 @@
))
))
(defmacro select [apath structure]
(defmacro select
"Navigates to and returns a sequence of all the elements specified by the path.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation it it's not possible to
factor/cache the path."
[apath structure]
`(i/compiled-select* (path ~apath) ~structure))
(defmacro select-one! [apath structure]
(defmacro select-one!
"Returns exactly one element, throws exception if zero or multiple elements found.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation it it's not possible to
factor/cache the path."
[apath structure]
`(i/compiled-select-one!* (path ~apath) ~structure))
(defmacro select-one [apath structure]
(defmacro select-one
"Like select, but returns either one element or nil. Throws exception if multiple elements found.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation it it's not possible to
factor/cache the path."
[apath structure]
`(i/compiled-select-one* (path ~apath) ~structure))
(defmacro select-first [apath structure]
(defmacro select-first
"Returns first element found. Not any more efficient than select, just a convenience.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation it it's not possible to
factor/cache the path."
[apath structure]
`(i/compiled-select-first* (path ~apath) ~structure))
(defmacro transform [apath transform-fn structure]
(defmacro transform
"Navigates to each value specified by the path and replaces it by the result of running
the transform-fn on it.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation it it's not possible to
factor/cache the path."
[apath transform-fn structure]
`(i/compiled-transform* (path ~apath) ~transform-fn ~structure))
(defmacro setval [apath aval structure]
(defmacro setval
"Navigates to each value specified by the path and replaces it by `aval`.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation it it's not possible to
factor/cache the path."
[apath aval structure]
`(i/compiled-setval* (path ~apath) ~aval ~structure))
(defmacro replace-in
"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.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation it it's not possible to
factor/cache the path."
[apath transform-fn structure & args]
`(i/compiled-replace-in* (path ~apath) ~transform-fn ~structure ~@args))