From b2cb9f1940aea44443b5cee538068d900dc9c106 Mon Sep 17 00:00:00 2001 From: Nathan Marz Date: Tue, 24 May 2016 08:42:23 -0400 Subject: [PATCH] add doc for must-cache-paths --- CHANGES.md | 2 +- src/clj/com/rpl/specter.cljx | 12 +++++++++++- src/clj/com/rpl/specter/macros.clj | 7 ++++--- 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 1ce1196..f17157d 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,7 +4,7 @@ * BREAKING CHANGE: fixed-pathed-path and variable-pathed-path renamed to fixed-pathed-nav and variabled-pathed-nav * New `path` macro does intelligent inline caching of the provided path. The path is factored into a static portion and into params which may change on each usage of the path (e.g. local parameters). The static part is factored and compiled on the first run-through, and then re-used for all subsequent invocations. As an example, `[ALL (keypath k)]` is factored into `[ALL keypath]`, which is compiled and cached, and `[k]`, which is provided on each execution. If it is not possible to precompile the path (e.g. [ALL some-local-variable]), nothing is cached and the path will be compiled on each run-through. * Added `must-cache-paths!` function to throw an error if it is not possible to factor a path into a static portion and dynamic parameters. -* BREAKING CHANGE: all select/transform/setval/replace-in functions changed to macros and moved to com.rpl.specter.macros namespace. The new macros now automatically wrap the provided path in `path` to enable inline caching. Expect upwards of a 100x performance improvement without using explicit precompilation, and to be within 2% to 15% of the performance of explicitly precompiled usage. +* BREAKING CHANGE: all select/transform/setval/replace-in functions changed to macros and moved to com.rpl.specter.macros namespace. The new macros now automatically wrap the provided path in `path` to enable inline caching. Expect up to a 100x performance improvement without using explicit precompilation, and to be within 2% to 15% of the performance of explicitly precompiled usage. * Added select*/transform*/setval*/replace-in*/etc. functions that have the same functionality as the old select/transform/setval/replace-in functions. * Added `must` navigator to navigate to a key if and only if it exists in the structure * Added `ATOM` navigator (thanks @rakeshp) diff --git a/src/clj/com/rpl/specter.cljx b/src/clj/com/rpl/specter.cljx index a9850ce..92425d1 100644 --- a/src/clj/com/rpl/specter.cljx +++ b/src/clj/com/rpl/specter.cljx @@ -26,7 +26,17 @@ (defn comp-paths [& paths] (i/comp-paths* (vec paths))) -(def must-cache-paths! i/must-cache-paths!) +(def ^{:doc "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."} + must-cache-paths! i/must-cache-paths!) ;; Selection functions diff --git a/src/clj/com/rpl/specter/macros.clj b/src/clj/com/rpl/specter/macros.clj index 5723764..bc042a1 100644 --- a/src/clj/com/rpl/specter/macros.clj +++ b/src/clj/com/rpl/specter/macros.clj @@ -404,8 +404,7 @@ `(let [info# (i/get-path-cache ~cache-id) ^com.rpl.specter.impl.CachedPathInfo info# - (if (some? info#) - info# + (if (nil? info#) (let [info# (i/magic-precompilation ~prepared-path (quote ~used-locals) @@ -415,7 +414,9 @@ )] (i/add-path-cache! ~cache-id info#) info# - )) + ) + info# + ) ~precompiled-sym (.-precompiled info#) ~params-maker-sym (.-params-maker info#)]