/usr/share/doc/libghc-lens-doc/html/Data-Data-Lens.html is in libghc-lens-doc 4.15.4-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Data.Data.Lens</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script src="file:///usr/share/javascript/mathjax/MathJax.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Data-Data-Lens.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Data-Data-Lens.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">lens-4.15.4: Lenses, Folds and Traversals</p></div><div id="content"><div id="module-header"><table class="info"><tr><th valign="top">Copyright</th><td>(C) 2012-2016 Edward Kmett (C) 2006-2012 Neil Mitchell</td></tr><tr><th>License</th><td>BSD-style (see the file LICENSE)</td></tr><tr><th>Maintainer</th><td>Edward Kmett <ekmett@gmail.com></td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Portability</th><td>Rank2Types</td></tr><tr><th>Safe Haskell</th><td>Trustworthy</td></tr><tr><th>Language</th><td>Haskell98</td></tr></table><p class="caption">Data.Data.Lens</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Generic Traversal</a></li><li><a href="#g:2">Field Accessor Traversal</a></li><li><a href="#g:3">Data Traversal</a></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>Smart and naïve generic traversals given <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a></code> instances.</p><p><code><a href="Data-Data-Lens.html#v:template">template</a></code>, <code><a href="Data-Data-Lens.html#v:uniplate">uniplate</a></code>, and <code><a href="Data-Data-Lens.html#v:biplate">biplate</a></code> each build up information about what
types can be contained within another type to speed up <code><a href="Control-Lens-Type.html#t:Traversal">Traversal</a></code>.</p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><a href="#v:template">template</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => <a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a> s a</li><li class="src short"><a href="#v:tinplate">tinplate</a> :: (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => <a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a> s a</li><li class="src short"><a href="#v:uniplate">uniplate</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> a => <a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a> a a</li><li class="src short"><a href="#v:biplate">biplate</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => <a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a> s a</li><li class="src short"><a href="#v:upon">upon</a> :: <span class="keyword">forall</span> p f s a. (<a href="Control-Lens-Internal-Indexed.html#t:Indexable">Indexable</a> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>] p, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Control-Applicative.html#t:Applicative">Applicative</a> f, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> a) => (s -> a) -> p a (f a) -> s -> f s</li><li class="src short"><a href="#v:upon-39-">upon'</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> a) => (s -> a) -> <a href="Control-Lens-Type.html#t:IndexedLens-39-">IndexedLens'</a> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>] s a</li><li class="src short"><a href="#v:onceUpon">onceUpon</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => (s -> a) -> <a href="Control-Lens-Type.html#t:IndexedTraversal-39-">IndexedTraversal'</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> s a</li><li class="src short"><a href="#v:onceUpon-39-">onceUpon'</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => (s -> a) -> <a href="Control-Lens-Type.html#t:IndexedLens-39-">IndexedLens'</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> s a</li><li class="src short"><a href="#v:gtraverse">gtraverse</a> :: (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Control-Applicative.html#t:Applicative">Applicative</a> f, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> a) => (<span class="keyword">forall</span> d. <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> d => d -> f d) -> a -> f a</li></ul></div><div id="interface"><h1 id="g:1">Generic Traversal</h1><div class="top"><p class="src"><a id="v:template" class="def">template</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => <a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a> s a <a href="src/Data-Data-Lens.html#template" class="link">Source</a> <a href="#v:template" class="selflink">#</a></p><div class="doc"><p>Find every occurrence of a given type <code>a</code> recursively that doesn't require
passing through something of type <code>a</code> using <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a></code>, while avoiding traversal
of areas that cannot contain a value of type <code>a</code>.</p><p>This is <code><a href="Data-Data-Lens.html#v:uniplate">uniplate</a></code> with a more liberal signature.</p></div></div><div class="top"><p class="src"><a id="v:tinplate" class="def">tinplate</a> :: (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => <a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a> s a <a href="src/Data-Data-Lens.html#tinplate" class="link">Source</a> <a href="#v:tinplate" class="selflink">#</a></p><div class="doc"><p>Naïve <code><a href="Control-Lens-Type.html#t:Traversal">Traversal</a></code> using <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a></code>. This does not attempt to optimize the traversal.</p><p>This is primarily useful when the children are immediately obvious, and for benchmarking.</p></div></div><div class="top"><p class="src"><a id="v:uniplate" class="def">uniplate</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> a => <a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a> a a <a href="src/Data-Data-Lens.html#uniplate" class="link">Source</a> <a href="#v:uniplate" class="selflink">#</a></p><div class="doc"><p>Find descendants of type <code>a</code> non-transitively, while avoiding computation of areas that cannot contain values of
type <code>a</code> using <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a></code>.</p><p><code><a href="Data-Data-Lens.html#v:uniplate">uniplate</a></code> is a useful default definition for <code><a href="Control-Lens-Plated.html#v:plate">plate</a></code></p></div></div><div class="top"><p class="src"><a id="v:biplate" class="def">biplate</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => <a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a> s a <a href="src/Data-Data-Lens.html#biplate" class="link">Source</a> <a href="#v:biplate" class="selflink">#</a></p><div class="doc"><p><code><a href="Data-Data-Lens.html#v:biplate">biplate</a></code> performs like <code><a href="Data-Data-Lens.html#v:template">template</a></code>, except when <code>s ~ a</code>, it returns itself and nothing else.</p></div></div><h1 id="g:2">Field Accessor Traversal</h1><div class="top"><p class="src"><a id="v:upon" class="def">upon</a> :: <span class="keyword">forall</span> p f s a. (<a href="Control-Lens-Internal-Indexed.html#t:Indexable">Indexable</a> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>] p, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Control-Applicative.html#t:Applicative">Applicative</a> f, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> a) => (s -> a) -> p a (f a) -> s -> f s <a href="src/Data-Data-Lens.html#upon" class="link">Source</a> <a href="#v:upon" class="selflink">#</a></p><div class="doc"><p>This automatically constructs a <code><a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a></code> from an function.</p><pre class="screen"><code class="prompt">>>> </code><strong class="userinput"><code>(2,4) & upon fst *~ 5
</code></strong>(10,4)
</pre><p>There are however, caveats on how this function can be used!</p><p>First, the user supplied function must access only one field of the specified type. That is to say the target
must be a single element that would be visited by <code><code>holesOnOf</code> <code><a href="Data-Data-Lens.html#v:template">template</a></code> <code><a href="Data-Data-Lens.html#v:uniplate">uniplate</a></code></code></p><p>Note: this even permits a number of functions to be used directly.</p><pre class="screen"><code class="prompt">>>> </code><strong class="userinput"><code>[1,2,3,4] & upon head .~ 0
</code></strong>[0,2,3,4]
</pre><pre class="screen"><code class="prompt">>>> </code><strong class="userinput"><code>[1,2,3,4] & upon last .~ 5
</code></strong>[1,2,3,5]
</pre><pre class="screen"><code class="prompt">>>> </code><strong class="userinput"><code>[1,2,3,4] ^? upon tail
</code></strong>Just [2,3,4]
</pre><pre class="screen"><code class="prompt">>>> </code><strong class="userinput"><code>"" ^? upon tail
</code></strong>Nothing
</pre><p>Accessing parents on the way down to children is okay:</p><pre class="screen"><code class="prompt">>>> </code><strong class="userinput"><code>[1,2,3,4] & upon (tail.tail) .~ [10,20]
</code></strong>[1,2,10,20]
</pre><p>Second, the structure must not contain strict or unboxed fields of the same type that will be visited by <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a></code></p><pre><code><a href="Data-Data-Lens.html#v:upon">upon</a></code> :: (<code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a></code> s, <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a></code> a) => (s -> a) -> <code><a href="Control-Lens-Type.html#t:IndexedTraversal-39-">IndexedTraversal'</a></code> [Int] s a</pre></div></div><div class="top"><p class="src"><a id="v:upon-39-" class="def">upon'</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> a) => (s -> a) -> <a href="Control-Lens-Type.html#t:IndexedLens-39-">IndexedLens'</a> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>] s a <a href="src/Data-Data-Lens.html#upon%27" class="link">Source</a> <a href="#v:upon-39-" class="selflink">#</a></p><div class="doc"><p>The design of <code><a href="Data-Data-Lens.html#v:onceUpon-39-">onceUpon'</a></code> doesn't allow it to search inside of values of type <code>a</code> for other values of type <code>a</code>.
<code><a href="Data-Data-Lens.html#v:upon-39-">upon'</a></code> provides this additional recursion.</p><p>Like <code><a href="Data-Data-Lens.html#v:onceUpon-39-">onceUpon'</a></code>, <code><a href="Data-Data-Lens.html#v:upon-39-">upon'</a></code> trusts the user supplied function more than <code><a href="Data-Data-Lens.html#v:upon">upon</a></code> using it directly
as the accessor. This enables reading from the resulting <code><a href="Control-Lens-Type.html#t:Lens">Lens</a></code> to be considerably faster at the risk of
generating an illegal lens.</p><pre class="screen"><code class="prompt">>>> </code><strong class="userinput"><code>upon' (tail.tail) .~ [10,20] $ [1,2,3,4]
</code></strong>[1,2,10,20]
</pre></div></div><div class="top"><p class="src"><a id="v:onceUpon" class="def">onceUpon</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => (s -> a) -> <a href="Control-Lens-Type.html#t:IndexedTraversal-39-">IndexedTraversal'</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> s a <a href="src/Data-Data-Lens.html#onceUpon" class="link">Source</a> <a href="#v:onceUpon" class="selflink">#</a></p><div class="doc"><p>This automatically constructs a <code><a href="Control-Lens-Type.html#t:Traversal-39-">Traversal'</a></code> from a field accessor.</p><p>The index of the <code><a href="Control-Lens-Type.html#t:Traversal">Traversal</a></code> can be used as an offset into <code><code><a href="Control-Lens-Traversal.html#v:elementOf">elementOf</a></code> (<code><a href="Control-Lens-Internal-Indexed.html#v:indexing">indexing</a></code> <code><a href="Data-Data-Lens.html#v:template">template</a></code>)</code> or into the list
returned by <code><code><a href="Control-Lens-Traversal.html#v:holesOf">holesOf</a></code> <code><a href="Data-Data-Lens.html#v:template">template</a></code></code>.</p><p>The design of <code><a href="Data-Data-Lens.html#v:onceUpon">onceUpon</a></code> doesn't allow it to search inside of values of type <code>a</code> for other values of type <code>a</code>.
<code><a href="Data-Data-Lens.html#v:upon">upon</a></code> provides this additional recursion, but at the expense of performance.</p><pre class="screen"><code class="prompt">>>> </code><strong class="userinput"><code>onceUpon (tail.tail) .~ [10,20] $ [1,2,3,4] -- BAD
</code></strong>[1,10,20]
</pre><pre class="screen"><code class="prompt">>>> </code><strong class="userinput"><code>upon (tail.tail) .~ [10,20] $ [1,2,3,4] -- GOOD
</code></strong>[1,2,10,20]
</pre><p>When in doubt, use <code><a href="Data-Data-Lens.html#v:upon">upon</a></code> instead.</p></div></div><div class="top"><p class="src"><a id="v:onceUpon-39-" class="def">onceUpon'</a> :: <span class="keyword">forall</span> s a. (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> s, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Typeable-Internal.html#t:Typeable">Typeable</a> a) => (s -> a) -> <a href="Control-Lens-Type.html#t:IndexedLens-39-">IndexedLens'</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> s a <a href="src/Data-Data-Lens.html#onceUpon%27" class="link">Source</a> <a href="#v:onceUpon-39-" class="selflink">#</a></p><div class="doc"><p>This more trusting version of <code><a href="Data-Data-Lens.html#v:upon">upon</a></code> uses your function directly as the getter for a <code><a href="Control-Lens-Type.html#t:Lens">Lens</a></code>.</p><p>This means that reading from <code><a href="Data-Data-Lens.html#v:upon-39-">upon'</a></code> is considerably faster than <code><a href="Data-Data-Lens.html#v:upon">upon</a></code>.</p><p>However, you pay for faster access in two ways:</p><ol><li>When passed an illegal field accessor, <code><a href="Data-Data-Lens.html#v:upon-39-">upon'</a></code> will give you a <code><a href="Control-Lens-Type.html#t:Lens">Lens</a></code> that quietly violates
the laws, unlike <code><a href="Data-Data-Lens.html#v:upon">upon</a></code>, which will give you a legal <code><a href="Control-Lens-Type.html#t:Traversal">Traversal</a></code> that avoids modifying the target.</li><li>Modifying with the lens is slightly slower, since it has to go back and calculate the index after the fact.</li></ol><p>When given a legal field accessor, the index of the <code><a href="Control-Lens-Type.html#t:Lens">Lens</a></code> can be used as an offset into
<code><code><a href="Control-Lens-Traversal.html#v:elementOf">elementOf</a></code> (<code><a href="Control-Lens-Internal-Indexed.html#v:indexed">indexed</a></code> <code><a href="Data-Data-Lens.html#v:template">template</a></code>)</code> or into the list returned by <code><code><a href="Control-Lens-Traversal.html#v:holesOf">holesOf</a></code> <code><a href="Data-Data-Lens.html#v:template">template</a></code></code>.</p><p>When in doubt, use <code><a href="Data-Data-Lens.html#v:upon-39-">upon'</a></code> instead.</p></div></div><h1 id="g:3">Data Traversal</h1><div class="top"><p class="src"><a id="v:gtraverse" class="def">gtraverse</a> :: (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Control-Applicative.html#t:Applicative">Applicative</a> f, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> a) => (<span class="keyword">forall</span> d. <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#t:Data">Data</a> d => d -> f d) -> a -> f a <a href="src/Data-Data-Lens.html#gtraverse" class="link">Source</a> <a href="#v:gtraverse" class="selflink">#</a></p><div class="doc"><p>A generic applicative transformation that maps over the immediate subterms.</p><p><code><a href="Data-Data-Lens.html#v:gtraverse">gtraverse</a></code> is to <code><a href="Control-Lens-Traversal.html#v:traverse">traverse</a></code> what <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Data.html#v:gmapM">gmapM</a></code> is to <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Traversable.html#v:mapM">mapM</a></code></p><p>This really belongs in <code>Data.Data</code>.</p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.17.3</p></div></body></html>
|