renamed adjust to under to line up with over from Iso and Control.New…

…type. added auf

lens.cabal

@@ -1,6 +1,6 @@
 name:          lens
 category:      Data, Lenses
-version:       2.0.1
+version:       2.1
 license:       BSD3
 cabal-version: >= 1.8
 license-file:  LICENSE
@@ -33,7 +33,7 @@ description:
   .
   The core of this hierarchy looks like:
   .
-  <<https://github.com/ekmett/lens/wiki/images/Hierarchy-2.0.png>>
+  <<https://github.com/ekmett/lens/wiki/images/Hierarchy-2.1.png>>
   .
   You can compose any two elements of the hierarchy above using (.) from the Prelude, and you can
   use any element of the hierarchy as any type it links to above it.

src/Control/Lens/Iso.hs

@@ -17,6 +17,8 @@ module Control.Lens.Iso
   , iso
   , isos
   , au
+  , auf
+  , over
   -- ** Combinators
   , via
   , from
@@ -162,24 +164,38 @@ iso ab ba = isos ab ba ab ba
 {-# SPECIALIZE iso :: Functor f => (a -> b) -> (b -> a) -> (b -> f b) -> a -> f a #-}
 {-# SPECIALIZE iso :: Functor f => (a -> b) -> (b -> a) -> Isomorphism (b -> f b) (a -> f a) #-}
 
--- | Based on @ala@ from Conor McBride's work on Epigram and @Control.Newtype@ from the
--- 'newtype package.
+-- | Based on @ala@ from Conor McBride's work on Epigram.
 --
 -- Mnemonically, /au/ is a French contraction of /à le/.
 --
 -- >>> :m + Control.Lens Data.Monoid.Lens Data.Foldable
 -- >>> au _sum foldMap [1,2,3,4]
 -- 10
-au :: Simple Iso a b -> ((a -> b) -> e -> b) -> e -> a
+au :: Simple Iso a b -> ((a -> b) -> c -> b) -> c -> a
 au l f e = f (view l) e ^. from l
+{-# INLINE au #-}
 
-{-
-under :: Setter a b c d -> (c -> d) -> a -> b
-under = adjust
+-- |
+-- Based on @ala'@ from Conor McBride's work on Epigram.
+--
+-- Mnemonically, the German /auf/ both plays a similar role to /à la/, and it is /au/ with an
+-- extra function argument.
+auf :: Simple Iso a b -> ((d -> b) -> c -> b) -> (d -> a) -> c -> a
+auf l f g e = f (view l . g) e ^. from l
+{-# INLINE auf #-}
 
+-- | The opposite of working 'under' an isomorphism.
+--
+-- @'over' = 'under' . 'from'@
+--
+-- >>> :m + Control.Lens Data.Monoid Data.Monoid.Lens
+-- >>> over _sum (mappend (Sum 2)) 10
+-- 12
+--
+-- @'over' :: Iso a b c d -> (a -> b) -> (c -> d)@
 over :: Isomorphism (c -> Identity d) (a -> Identity b) -> (a -> b) -> c -> d
 over = under . from
--}
+{-# INLINE over #-}
 
 -----------------------------------------------------------------------------
 -- Isomorphisms

src/Control/Lens/Setter.hs

@@ -31,7 +31,7 @@ module Control.Lens.Setter
   -- * Common Setters
   , mapped
   -- * Functional Combinators
-  , adjust
+  , under
   , mapOf
   , set
   , (.~), (%~)
@@ -73,8 +73,8 @@ infixr 2 <~
 -- However, two 'Functor' laws apply to a 'Setter':
 --
 -- @
--- 'adjust' l 'id' = 'id'
--- 'adjust' l f . 'adjust' l g = 'adjust' l (f . g)
+-- 'under' l 'id' = 'id'
+-- 'under' l f . 'under' l g = 'under' l (f . g)
 -- @
 --
 -- These an be stated more directly:
@@ -162,8 +162,8 @@ instance Settable Mutator where
 -- | This setter can be used to map over all of the values in a 'Functor'.
 --
 -- @
--- 'fmap' = 'adjust' 'mapped'
--- 'Data.Traversable.fmapDefault' = 'adjust' 'Data.Traversable.traverse'
+-- 'fmap' = 'under' 'mapped'
+-- 'Data.Traversable.fmapDefault' = 'under' 'Data.Traversable.traverse'
 -- ('<$') = 'set' 'mapped'
 -- @
 mapped :: Functor f => Setter (f a) (f b) a b
@@ -182,8 +182,8 @@ mapped = sets fmap
 -- Equational reasoning:
 --
 -- @
--- 'sets' . 'adjust' = 'id'
--- 'adjust' . 'sets' = 'id'
+-- 'sets' . 'under' = 'id'
+-- 'under' . 'sets' = 'id'
 -- @
 --
 -- Another way to view 'sets' is that it takes a \"semantic editor combinator\"
@@ -200,25 +200,25 @@ sets f g = pure . f (untainted . g)
 -- with a function.
 --
 -- @
--- 'fmap' = 'adjust' 'mapped'
--- 'Data.Traversable.fmapDefault' = 'adjust' 'Data.Traversable.traverse'
--- 'sets' . 'adjust' = 'id'
--- 'adjust' . 'sets' = 'id'
+-- 'fmap' = 'under' 'mapped'
+-- 'Data.Traversable.fmapDefault' = 'under' 'Data.Traversable.traverse'
+-- 'sets' . 'under' = 'id'
+-- 'under' . 'sets' = 'id'
 -- @
 --
--- Another way to view 'adjust' is to say that it transformers a 'Setter' into a
+-- Another way to view 'under' is to say that it transformers a 'Setter' into a
 -- \"semantic editor combinator\".
 --
--- @'adjust' :: 'Setter' a b c d -> (c -> d) -> a -> b@
-adjust :: Setting a b c d -> (c -> d) -> a -> b
-adjust l f = runMutator . l (Mutator . f)
-{-# INLINE adjust #-}
+-- @'under' :: 'Setter' a b c d -> (c -> d) -> a -> b@
+under :: Setting a b c d -> (c -> d) -> a -> b
+under l f = runMutator . l (Mutator . f)
+{-# INLINE under #-}
 
 -- | Modify the target of a 'Control.Lens.Type.Lens' or all the targets of a 'Setter' or 'Control.Lens.Traversal.Traversal'
--- with a function. This is an alias for adjust that is provided for consistency.
+-- with a function. This is an alias for 'under' that is provided for consistency.
 --
 -- @
--- 'mapOf' = 'adjust'
+-- 'mapOf' = 'under'
 -- 'fmap' = 'mapOf' 'mapped'
 -- 'fmapDefault' = 'mapOf' 'traverse'
 -- 'sets' . 'mapOf' = 'id'
@@ -232,7 +232,7 @@ adjust l f = runMutator . l (Mutator . f)
 -- mapOf :: 'Control.Lens.Traversal.Traversal' a b c d   -> (c -> d) -> a -> b
 -- @
 mapOf :: Setting a b c d -> (c -> d) -> a -> b
-mapOf = adjust
+mapOf = under
 {-# INLINE mapOf #-}
 
 -- | Replace the target of a 'Control.Lens.Type.Lens' or all of the targets of a 'Setter'
@@ -263,7 +263,7 @@ set l d = runMutator . l (\_ -> Mutator d)
 -- | Modifies the target of a 'Control.Lens.Type.Lens' or all of the targets of a 'Setter' or
 -- 'Control.Lens.Traversal.Traversal' with a user supplied function.
 --
--- This is an infix version of 'adjust'
+-- This is an infix version of 'under'
 --
 -- @
 -- 'fmap' f = 'mapped' '%~' f
@@ -281,7 +281,7 @@ set l d = runMutator . l (\_ -> Mutator d)
 -- (%~) :: 'Control.Lens.Traversal.Traversal' a b c d -> (c -> d) -> a -> b
 -- @
 (%~) :: Setting a b c d -> (c -> d) -> a -> b
-(%~) = adjust
+(%~) = under
 {-# INLINE (%~) #-}
 
 -- | Replace the target of a 'Control.Lens.Type.Lens' or all of the targets of a 'Setter'
@@ -334,7 +334,7 @@ l <.~ d = \a -> (d, l .~ d $ a)
 -- (+~) :: Num c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b
 -- @
 (+~) :: Num c => Setting a b c c -> c -> a -> b
-l +~ n = adjust l (+ n)
+l +~ n = under l (+ n)
 {-# INLINE (+~) #-}
 
 -- | Multiply the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal'
@@ -350,7 +350,7 @@ l +~ n = adjust l (+ n)
 -- (*~) :: 'Num' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b
 -- @
 (*~) :: Num c => Setting a b c c -> c -> a -> b
-l *~ n = adjust l (* n)
+l *~ n = under l (* n)
 {-# INLINE (*~) #-}
 
 -- | Decrement the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal'
@@ -366,7 +366,7 @@ l *~ n = adjust l (* n)
 -- (-~) :: 'Num' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b
 -- @
 (-~) :: Num c => Setting a b c c -> c -> a -> b
-l -~ n = adjust l (subtract n)
+l -~ n = under l (subtract n)
 {-# INLINE (-~) #-}
 
 -- | Divide the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal'
@@ -378,15 +378,15 @@ l -~ n = adjust l (subtract n)
 -- (//~) :: 'Fractional' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b
 -- @
 (//~) :: Fractional c => Setting a b c c -> c -> a -> b
-l //~ n = adjust l (/ n)
+l //~ n = under l (/ n)
 
 -- | Raise the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Setter' or 'Control.Lens.Traversal.Traversal' to a non-negative integral power
 --
 -- >>> import Control.Lens
 -- >>> _2 ^~ 2 $ (1,3)
 -- (1,9)
 (^~) :: (Num c, Integral e) => Setting a b c c -> e -> a -> b
-l ^~ n = adjust l (^ n)
+l ^~ n = under l (^ n)
 {-# INLINE (^~) #-}
 
 -- | Raise the target(s) of a fractionally valued 'Control.Lens.Type.Lens', 'Setter' or 'Control.Lens.Traversal.Traversal' to an integral power
@@ -403,7 +403,7 @@ l ^~ n = adjust l (^ n)
 -- @
 --
 (^^~) :: (Fractional c, Integral e) => Setting a b c c -> e -> a -> b
-l ^^~ n = adjust l (^^ n)
+l ^^~ n = under l (^^ n)
 {-# INLINE (^^~) #-}
 
 -- | Raise the target(s) of a floating-point valued 'Control.Lens.Type.Lens', 'Setter' or 'Control.Lens.Traversal.Traversal' to an arbitrary power.
@@ -419,7 +419,7 @@ l ^^~ n = adjust l (^^ n)
 -- (**~) :: 'Floating' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b
 -- @
 (**~) :: Floating c => Setting a b c c -> c -> a -> b
-l **~ n = adjust l (** n)
+l **~ n = under l (** n)
 {-# INLINE (**~) #-}
 
 -- | Logically '||' the target(s) of a 'Bool'-valued 'Control.Lens.Type.Lens' or 'Setter'
@@ -439,7 +439,7 @@ l **~ n = adjust l (** n)
 -- (||~):: 'Control.Lens.Traversal.Traversal' a b 'Bool' 'Bool' -> 'Bool' -> a -> b
 -- @
 (||~):: Setting a b Bool Bool -> Bool -> a -> b
-l ||~ n = adjust l (|| n)
+l ||~ n = under l (|| n)
 {-# INLINE (||~) #-}
 
 -- | Logically '&&' the target(s) of a 'Bool'-valued 'Control.Lens.Type.Lens' or 'Setter'
@@ -459,7 +459,7 @@ l ||~ n = adjust l (|| n)
 -- (&&~):: 'Control.Lens.Traversal.Traversal' a b 'Bool' 'Bool' -> 'Bool' -> a -> b
 -- @
 (&&~) :: Setting a b Bool Bool -> Bool -> a -> b
-l &&~ n = adjust l (&& n)
+l &&~ n = under l (&& n)
 {-# INLINE (&&~) #-}
 
 -- | Modify the target of a monoidally valued by 'mappend'ing another value.
@@ -475,7 +475,7 @@ l &&~ n = adjust l (&& n)
 -- (<>~) :: 'Monoid' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b
 -- @
 (<>~) :: Monoid c => Setting a b c c -> c -> a -> b
-l <>~ n = adjust l (`mappend` n)
+l <>~ n = under l (`mappend` n)
 {-# INLINE (<>~) #-}
 
 ------------------------------------------------------------------------------

src/Data/Array/Lens.hs

@@ -44,21 +44,21 @@ ix i f arr = (\e -> arr // [(i,e)]) <$> f (arr ! i)
 --
 -- This is a /contravariant/ 'Setter'.
 --
--- @'ixmap' = 'adjust' . 'ixmapped'@
+-- @'ixmap' = 'under' . 'ixmapped'@
 --
 -- @'ixmapped' = 'sets' . 'ixmap'@
 --
--- @'adjust' ('ixmapped' b) f arr '!' i = arr '!' f i@
+-- @'under' ('ixmapped' b) f arr '!' i = arr '!' f i@
 --
--- @'bounds' ('adjust' ('ixmapped' b) f arr) = b@
+-- @'bounds' ('under' ('ixmapped' b) f arr) = b@
 ixmapped :: (IArray a e, Ix i, Ix j) => (i,i) -> Setter (a j e) (a i e) i j
 ixmapped = sets . ixmap
 {-# INLINE ixmapped #-}
 
 -- | An 'IndexedTraversal' of the elements of an 'IArray', using the 
 -- index into the array as the index of the traversal.
 --
--- @'amap' = 'adjust' 'traverseArray'@
+-- @'amap' = 'under' 'traverseArray'@
 traverseArray :: (IArray a c, IArray a d, Ix i) => IndexedTraversal i (a i c) (a i d) c d
 traverseArray = index $ \f arr -> array (bounds arr) <$> traverse (\(i,a) -> (,) i <$> f i a) (assocs arr)
 {-# INLINE traverseArray #-}

src/Data/Bits/Lens.hs

@@ -30,15 +30,15 @@ infix 4 |=, &=
 -- >>> _2 |~ 6 $ ("hello",3)
 -- ("hello",7)
 (|~):: Bits c => Setting a b c c -> c -> a -> b
-l |~ n = adjust l (.|. n)
+l |~ n = under l (.|. n)
 {-# INLINE (|~) #-}
 
 -- | Bitwise '.&.' the target(s) of a 'Bool'-valued 'Lens' or 'Setter'
 --
 -- >>> _2 &~ 7 $ ("hello",254)
 -- ("hello",6)
 (&~) :: Bits c => Setting a b c c -> c -> a -> b
-l &~ n = adjust l (.&. n)
+l &~ n = under l (.&. n)
 {-# INLINE (&~) #-}
 
 -- | Modify the target(s) of a 'Simple' 'Lens', 'Setter' or 'Traversal' by computing its bitwise '.&.' with another value.

src/Data/IntSet/Lens.hs

@@ -45,7 +45,7 @@ members = folding IntSet.toAscList
 -- elements might change but you can manipulate it by reading using 'folded' and
 -- reindexing it via 'setmap'.
 --
--- >>> adjust setmapped (+1) (fromList [1,2,3,4])
+-- >>> under setmapped (+1) (fromList [1,2,3,4])
 -- fromList [2,3,4,5]
 setmapped :: Simple Setter IntSet Int
 setmapped = sets IntSet.map

src/Data/Set/Lens.hs

@@ -40,7 +40,7 @@ contains k f s = go <$> f (Set.member k s) where
 -- manipulate it by reading using 'folded' and reindexing it via 'setmap'.
 --
 -- >>> :m + Data.Set.Lens Control.Lens
--- >>> adjust setmapped (+1) (fromList [1,2,3,4])
+-- >>> under setmapped (+1) (fromList [1,2,3,4])
 -- fromList [2,3,4,5]
 setmapped :: (Ord i, Ord j) => Setter (Set i) (Set j) i j
 setmapped = sets Set.map