luciano/specter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
specter/com.rpl.specter.macros.html
Nathan Marz 621c483859 update docs
2017-03-01 12:36:21 -05:00

97 lines
No EOL
24 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC ""
"">
<html><head><meta charset="UTF-8" /><link href="css/default.css" rel="stylesheet" type="text/css" /><script src="js/jquery.min.js" type="text/javascript"></script><script src="js/page_effects.js" type="text/javascript"></script><title>com.rpl.specter.macros documentation</title></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Specter</span> <span class="project-version">0.12.0</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>com</span></div></div></li><li class="depth-2"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>rpl</span></div></div></li><li class="depth-3"><a href="com.rpl.specter.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>specter</span></div></a></li><li class="depth-4 branch current"><a href="com.rpl.specter.macros.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>macros</span></div></a></li><li class="depth-4 branch"><a href="com.rpl.specter.protocols.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>protocols</span></div></a></li><li class="depth-4 branch"><a href="com.rpl.specter.transients.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>transients</span></div></a></li><li class="depth-4"><a href="com.rpl.specter.zipper.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>zipper</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="com.rpl.specter.macros.html#var-cljs-macroexpand"><div class="inner"><span>cljs-macroexpand</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-cljs-macroexpand-all"><div class="inner"><span>cljs-macroexpand-all</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-cljs-macroexpand-all*"><div class="inner"><span>cljs-macroexpand-all*</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-collected.3F"><div class="inner"><span>collected?</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-declarepath"><div class="inner"><span>declarepath</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-defcollector"><div class="inner"><span>defcollector</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-defnav"><div class="inner"><span>defnav</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-defnavconstructor"><div class="inner"><span>defnavconstructor</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-defpathedfn"><div class="inner"><span>defpathedfn</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-defprotocolpath"><div class="inner"><span>defprotocolpath</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-extend-protocolpath"><div class="inner"><span>extend-protocolpath</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-fixed-pathed-nav"><div class="inner"><span>fixed-pathed-nav</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-multi-transform"><div class="inner"><span>multi-transform</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-nav"><div class="inner"><span>nav</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-paramscollector"><div class="inner"><span>paramscollector</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-paramsfn"><div class="inner"><span>paramsfn</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-path"><div class="inner"><span>path</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-pathed-collector"><div class="inner"><span>pathed-collector</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-providepath"><div class="inner"><span>providepath</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-replace-in"><div class="inner"><span>replace-in</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-richnav"><div class="inner"><span>richnav</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-select"><div class="inner"><span>select</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-select-any"><div class="inner"><span>select-any</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-select-first"><div class="inner"><span>select-first</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-select-one"><div class="inner"><span>select-one</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-select-one.21"><div class="inner"><span>select-one!</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-selected-any.3F"><div class="inner"><span>selected-any?</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-setval"><div class="inner"><span>setval</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-transform"><div class="inner"><span>transform</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-traverse"><div class="inner"><span>traverse</span></div></a></li><li class="depth-1"><a href="com.rpl.specter.macros.html#var-variable-pathed-nav"><div class="inner"><span>variable-pathed-nav</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">com.rpl.specter.macros</h1><div class="doc"><pre class="plaintext"></pre></div><div class="public anchor" id="var-cljs-macroexpand"><h3>cljs-macroexpand</h3><div class="usage"><code>(cljs-macroexpand env form)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L476">view source</a></div></div><div class="public anchor" id="var-cljs-macroexpand-all"><h3>cljs-macroexpand-all</h3><div class="usage"><code>(cljs-macroexpand-all env form)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L491">view source</a></div></div><div class="public anchor" id="var-cljs-macroexpand-all*"><h3>cljs-macroexpand-all*</h3><div class="usage"><code>(cljs-macroexpand-all* env form)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L483">view source</a></div></div><div class="public anchor" id="var-collected.3F"><h3>collected?</h3><h4 class="type">macro</h4><div class="usage"><code>(collected? params &amp; body)</code></div><div class="doc"><pre class="plaintext">Creates a filter function navigator that takes in all the collected values
as input. For arguments, can use `(collected? [a b] ...)` syntax to look
at each collected value as individual arguments, or `(collected? v ...)` syntax
to capture all the collected values as a single vector.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L696">view source</a></div></div><div class="public anchor" id="var-declarepath"><h3>declarepath</h3><h4 class="type">macro</h4><div class="usage"><code>(declarepath name)</code><code>(declarepath name params)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L308">view source</a></div></div><div class="public anchor" id="var-defcollector"><h3>defcollector</h3><h4 class="type">macro</h4><div class="usage"><code>(defcollector name &amp; body)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L182">view source</a></div></div><div class="public anchor" id="var-defnav"><h3>defnav</h3><h4 class="type">macro</h4><div class="usage"><code>(defnav name &amp; body)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L179">view source</a></div></div><div class="public anchor" id="var-defnavconstructor"><h3>defnavconstructor</h3><h4 class="type">macro</h4><div class="usage"><code>(defnavconstructor name &amp; args)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L405">view source</a></div></div><div class="public anchor" id="var-defpathedfn"><h3>defpathedfn</h3><h4 class="type">macro</h4><div class="usage"><code>(defpathedfn name &amp; args)</code></div><div class="doc"><pre class="plaintext">Defines a higher order navigator that itself takes in one or more paths
as input. This macro is generally used in conjunction with [[fixed-pathed-nav]]
or [[variable-pathed-nav]]. When inline factoring is applied to a path containing
one of these higher order navigators, it will automatically interepret all
arguments as paths, factor them accordingly, and set up the callsite to
provide the parameters dynamically. Use ^:notpath metadata on arguments
to indicate non-path arguments that should not be factored – note that in order
to be inline factorable, these arguments must be statically resolvable (e.g. a
top level var). See `transformed` for an example.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L390">view source</a></div></div><div class="public anchor" id="var-defprotocolpath"><h3>defprotocolpath</h3><h4 class="type">macro</h4><div class="usage"><code>(defprotocolpath name)</code><code>(defprotocolpath name params)</code></div><div class="doc"><pre class="plaintext">Defines a navigator that chooses the path to take based on the type
of the value at the current point. May be specified with parameters to
specify that all extensions must require that number of parameters.
Currently not available for ClojureScript.
Example of usage:
(defrecord SingleAccount [funds])
(defrecord FamilyAccount [single-accounts])
(defprotocolpath FundsPath)
(extend-protocolpath FundsPath
SingleAccount :funds
FamilyAccount [ALL FundsPath]
)
</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L242">view source</a></div></div><div class="public anchor" id="var-extend-protocolpath"><h3>extend-protocolpath</h3><h4 class="type">macro</h4><div class="usage"><code>(extend-protocolpath protpath &amp; extensions)</code></div><div class="doc"><pre class="plaintext">Used in conjunction with `defprotocolpath`. See [[defprotocolpath]].
</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L359">view source</a></div></div><div class="public anchor" id="var-fixed-pathed-nav"><h3>fixed-pathed-nav</h3><h4 class="type">macro</h4><div class="usage"><code>(fixed-pathed-nav bindings impl1 impl2)</code></div><div class="doc"><pre class="plaintext">This helper is used to define navigators that take in a fixed number of other
paths as input. Those paths may require late-bound params, so this helper
will create a parameterized navigator if that is the case. If no late-bound params
are required, then the result is executable.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L185">view source</a></div></div><div class="public anchor" id="var-multi-transform"><h3>multi-transform</h3><h4 class="type">macro</h4><div class="usage"><code>(multi-transform apath structure)</code></div><div class="doc"><pre class="plaintext">Just like `transform` but expects transform functions to be specified
inline in the path using `terminal`. Error is thrown if navigation finishes
at a non-`terminal` navigator. `terminal-val` is a wrapper around `terminal` and is
the `multi-transform` equivalent of `setval`.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L655">view source</a></div></div><div class="public anchor" id="var-nav"><h3>nav</h3><h4 class="type">macro</h4><div class="usage"><code>(nav params impl1 impl2)</code></div><div class="doc"><pre class="plaintext">Defines a navigator with late bound parameters. This navigator can be precompiled
with other navigators without knowing the parameters. When precompiled with other
navigators, the resulting path takes in parameters for all navigators in the path
that needed parameters (in the order in which they were declared).</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L116">view source</a></div></div><div class="public anchor" id="var-paramscollector"><h3>paramscollector</h3><h4 class="type">macro</h4><div class="usage"><code>(paramscollector params impl)</code></div><div class="doc"><pre class="plaintext">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).
</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L167">view source</a></div></div><div class="public anchor" id="var-paramsfn"><h3>paramsfn</h3><h4 class="type">macro</h4><div class="usage"><code>(paramsfn params [structure-sym] &amp; impl)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L156">view source</a></div></div><div class="public anchor" id="var-path"><h3>path</h3><h4 class="type">macro</h4><div class="usage"><code>(path &amp; path)</code></div><div class="doc"><pre class="plaintext">Same as calling comp-paths, except it caches the composition of the static part
of the path for later re-use (when possible). For almost all idiomatic uses
of Specter provides huge speedup. This macro is automatically used by the
select/transform/setval/replace-in/etc. macros.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L497">view source</a></div></div><div class="public anchor" id="var-pathed-collector"><h3>pathed-collector</h3><h4 class="type">macro</h4><div class="usage"><code>(pathed-collector [name path] impl)</code></div><div class="doc"><pre class="plaintext">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.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L221">view source</a></div></div><div class="public anchor" id="var-providepath"><h3>providepath</h3><h4 class="type">macro</h4><div class="usage"><code>(providepath name apath)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L346">view source</a></div></div><div class="public anchor" id="var-replace-in"><h3>replace-in</h3><h4 class="type">macro</h4><div class="usage"><code>(replace-in apath transform-fn structure &amp; args)</code></div><div class="doc"><pre class="plaintext">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 if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L684">view source</a></div></div><div class="public anchor" id="var-richnav"><h3>richnav</h3><h4 class="type">macro</h4><div class="usage"><code>(richnav num-params impl1 impl2)</code></div><div class="doc"><pre class="plaintext">Defines a navigator with full access to collected vals, the parameters array,
and the parameters array index. `next-fn` expects to receive the params array,
a params index, the collected vals, and finally the next structure.
`next-fn` will automatically skip ahead in params array by `num-params`, so the
index passed to it is ignored.
This is the lowest level way of making navigators.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L127">view source</a></div></div><div class="public anchor" id="var-select"><h3>select</h3><h4 class="type">macro</h4><div class="usage"><code>(select apath structure)</code></div><div class="doc"><pre class="plaintext">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 if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L597">view source</a></div></div><div class="public anchor" id="var-select-any"><h3>select-any</h3><h4 class="type">macro</h4><div class="usage"><code>(select-any apath structure)</code></div><div class="doc"><pre class="plaintext">Returns any element found or [[NONE]] if nothing selected. This is the most
efficient of the various selection operations.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L629">view source</a></div></div><div class="public anchor" id="var-select-first"><h3>select-first</h3><h4 class="type">macro</h4><div class="usage"><code>(select-first apath structure)</code></div><div class="doc"><pre class="plaintext">Returns first element found.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L621">view source</a></div></div><div class="public anchor" id="var-select-one"><h3>select-one</h3><h4 class="type">macro</h4><div class="usage"><code>(select-one apath structure)</code></div><div class="doc"><pre class="plaintext">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 if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L613">view source</a></div></div><div class="public anchor" id="var-select-one.21"><h3>select-one!</h3><h4 class="type">macro</h4><div class="usage"><code>(select-one! apath structure)</code></div><div class="doc"><pre class="plaintext">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 if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L605">view source</a></div></div><div class="public anchor" id="var-selected-any.3F"><h3>selected-any?</h3><h4 class="type">macro</h4><div class="usage"><code>(selected-any? apath structure)</code></div><div class="doc"><pre class="plaintext">Returns true if any element was selected, false otherwise.
This macro will attempt to do inline factoring and caching of the path, falling
back to compiling the path on every invocation if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L638">view source</a></div></div><div class="public anchor" id="var-setval"><h3>setval</h3><h4 class="type">macro</h4><div class="usage"><code>(setval apath aval structure)</code></div><div class="doc"><pre class="plaintext">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 if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L667">view source</a></div></div><div class="public anchor" id="var-transform"><h3>transform</h3><h4 class="type">macro</h4><div class="usage"><code>(transform apath transform-fn structure)</code></div><div class="doc"><pre class="plaintext">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 if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L646">view source</a></div></div><div class="public anchor" id="var-traverse"><h3>traverse</h3><h4 class="type">macro</h4><div class="usage"><code>(traverse apath structure)</code></div><div class="doc"><pre class="plaintext">Return a reducible object that traverses over `structure` to every element
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 if it's not possible to
factor/cache the path.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L675">view source</a></div></div><div class="public anchor" id="var-variable-pathed-nav"><h3>variable-pathed-nav</h3><h4 class="type">macro</h4><div class="usage"><code>(variable-pathed-nav [latepaths-seq-sym paths-seq] impl1 impl2)</code></div><div class="doc"><pre class="plaintext">This helper is used to define navigators that take in a variable number of other
paths as input. Those paths may require late-bound params, so this helper
will create a parameterized navigator if that is the case. If no late-bound params
are required, then the result is executable.</pre></div><div class="src-link"><a href="https://github.com/nathanmarz/specter/tree/0.12.0/src/clj/com/rpl/specter/macros.clj#L204">view source</a></div></div></div></body></html>
Reference in a new issue View git blame Copy permalink