From 224369f4eb668616810faef8842f596c62cafb79 Mon Sep 17 00:00:00 2001 From: Nathan Marz Date: Fri, 11 Sep 2015 11:21:21 -0400 Subject: [PATCH] add comments about what can be parameterized --- src/com/rpl/specter.cljc | 81 ++++++++++++++++++++++++++++++++++------ 1 file changed, 69 insertions(+), 12 deletions(-) diff --git a/src/com/rpl/specter.cljc b/src/com/rpl/specter.cljc index d2289e2..8d55c3e 100644 --- a/src/com/rpl/specter.cljc +++ b/src/com/rpl/specter.cljc @@ -106,15 +106,29 @@ ;; Helpers for defining selectors and collectors with late-bound params -(def bind-params* i/bind-params*) +(def ^{:doc "Takes a compiled selector 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."} + bind-params* i/bind-params*) -(defmacro paramspath [params & impls] +(defmacro paramspath + "Defines a StructurePath with late bound parameters. This path can be precompiled + with other selectors without knowing the parameters. When precompiled with other + selectors, the resulting selector takes in parameters for all selectors in the path + that needed parameters (in the order in which they were declared)." + [params & impls] (let [num-params (count params) retrieve-params (i/make-param-retrievers params)] (i/paramspath* retrieve-params num-params impls) )) -(defmacro paramscollector [params impl] +(defmacro paramscollector + "Defines a Collector with late bound parameters. This collector can be precompiled + with other selectors without knowing the parameters. When precompiled with other + selectors, the resulting selector takes in parameters for all selectors in the path + that needed parameters (in the order in which they were declared). + " + [params impl] (let [num-params (count params) retrieve-params (i/make-param-retrievers params)] (i/paramscollector* retrieve-params num-params impl) @@ -126,7 +140,12 @@ (defmacro defparamscollector [name & body] `(def ~name (paramscollector ~@body))) -(defmacro fixed-pathed-path [bindings & impls] +(defmacro fixed-pathed-path + "This helper is used to define selectors that take in a fixed number of other selector + paths as input. Those selector paths may require late-bound params, so this helper + will create a parameterized selector if that is the case. If no late-bound params + are required, then the result is executable." + [bindings & impls] (let [bindings (partition 2 bindings) paths (mapv second bindings) names (mapv first bindings) @@ -140,7 +159,12 @@ (mapcat (fn [n l] [n `(~l ~i/PARAMS-SYM ~i/PARAMS-IDX-SYM)]) names latefn-syms) impls))) -(defmacro variable-pathed-path [[latepaths-seq-sym paths-seq] & impls] +(defmacro variable-pathed-path + "This helper is used to define selectors that take in a variable number of other selector + paths as input. Those selector paths may require late-bound params, so this helper + will create a parameterized selector if that is the case. If no late-bound params + are required, then the result is executable." + [[latepaths-seq-sym paths-seq] & impls] (let [latefns-sym (gensym "latefns")] (i/pathed-path* i/paramspath* @@ -152,7 +176,12 @@ impls ))) -(defmacro pathed-collector [[name path] impl] +(defmacro pathed-collector + "This helper is used to define collectors that take in a single selector + paths as input. That path may require late-bound params, so this helper + will create a parameterized selector if that is the case. If no late-bound params + are required, then the result is executable." + [[name path] impl] (let [latefns-sym (gensym "latefns") latefn (gensym "latefn")] (i/pathed-path* @@ -175,14 +204,22 @@ (def FIRST (i/->PosStructurePath first i/set-first)) -(defparamspath srange-dynamic [start-fn end-fn] +(defparamspath + ^{:doc "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."} + srange-dynamic + [start-fn end-fn] (select* [this structure next-fn] (i/srange-select structure (start-fn structure) (end-fn structure) next-fn)) (transform* [this structure next-fn] (i/srange-transform structure (start-fn structure) (end-fn structure) next-fn) )) -(defparamspath srange [start end] +(defparamspath + ^{:doc "Navigates to the subsequence bound by the indexes start (inclusive) + and end (exclusive)"} + srange + [start end] (select* [this structure next-fn] (i/srange-select structure start end next-fn)) (transform* [this structure next-fn] @@ -197,7 +234,15 @@ (defn codewalker [afn] (i/->CodeWalkerStructurePath afn)) -(defn filterer [& path] +(defn filterer + "Navigates to a view of the current sequence that only contains elements that + match the given selector path. An element matches the selector path if calling select + on that element with the selector 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." + [& path] (fixed-pathed-path [late path] (select* [this structure next-fn] (->> structure (filter #(i/selected?* late %)) doall next-fn)) @@ -225,7 +270,11 @@ (defn selected? "Filters the current value based on whether a selector finds anything. e.g. (selected? :vals ALL even?) keeps the current element only if an - even number exists for the :vals key" + 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 selectors + were declared." [& path] (fixed-pathed-path [late path] (select* [this structure next-fn] @@ -254,7 +303,11 @@ (defn transformed "Navigates to a view of the current value by transforming it with the - specified selector and update-fn." + specified selector 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 selectors + were declared." [path update-fn] (fixed-pathed-path [late path] (select* [this structure next-fn] @@ -314,7 +367,11 @@ Tests the structure if selecting with cond-path returns anything. If so, it uses the following selector for this portion of the navigation. Otherwise, it tries the next cond-path. If nothing matches, then the structure - is not selected." + 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 selectors + were declared." [& conds] (variable-pathed-path [compiled-paths conds] (select* [this structure next-fn]