| Copyright | (C) 2012-16 Edward Kmett |
|---|---|
| License | BSD-style (see the file LICENSE) |
| Maintainer | Edward Kmett <ekmett@gmail.com> |
| Stability | provisional |
| Portability | Rank2Types |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
Control.Lens.Getter
Description
A is just any function Getter s a(s -> a), which we've flipped
into continuation passing style, (a -> r) -> s -> r and decorated
with Const to obtain:
typeGettingr s a = (a ->Constr a) -> s ->Constr s
If we restrict access to knowledge about the type r, we could get:
typeGetters a = forall r.Gettingr s a
However, for Getter (but not for Getting) we actually permit any
functor f which is an instance of both Functor and Functor:
typeGetters a = forall f. (Functorf,Functorf) => (a -> f a) -> s -> f s
Everything you can do with a function, you can do with a Getter, but
note that because of the continuation passing style (.) composes them
in the opposite order.
Since it is only a function, every Getter obviously only retrieves a
single value for a given input.
A common question is whether you can combine multiple Getters to
retrieve multiple values. Recall that all Getters are Folds and that
we have a instance to play
with. Knowing this, we can use Monoid m => Applicative (Const m) to glue <>Folds
together:
>>>import Data.Monoid>>>(1, 2, 3, 4, 5) ^.. (_2 <> _3 <> _5)[2,3,5]
Synopsis
- type Getter s a = forall f. (Functor f, Functor f) => (a -> f a) -> s -> f s
- type Getting r s a = (a -> Const r a) -> s -> Const r s
- type Accessing p m s a = p a (Const m a) -> s -> Const m s
- to :: (Profunctor p, Functor f) => (s -> a) -> Optic' p f s a
- like :: (Profunctor p, Functor f, Functor f) => a -> Optic' p f s a
- (^.) :: s -> Getting a s a -> a
- view :: MonadReader s m => Getting a s a -> m a
- views :: MonadReader s m => LensLike' (Const r) s a -> (a -> r) -> m r
- use :: MonadState s m => Getting a s a -> m a
- uses :: MonadState s m => LensLike' (Const r) s a -> (a -> r) -> m r
- listening :: MonadWriter w m => Getting u w u -> m a -> m (a, u)
- listenings :: MonadWriter w m => Getting v w u -> (u -> v) -> m a -> m (a, v)
- getting :: (Profunctor p, Profunctor q, Functor f, Functor f) => Optical p q f s t a b -> Optical' p q f s a
- newtype Const a (b :: k) :: forall k. Type -> k -> Type = Const {
- getConst :: a
Getters
type Getter s a = forall f. (Functor f, Functor f) => (a -> f a) -> s -> f s Source #
A Getter describes how to retrieve a single value in a way that can be
composed with other LensLike constructions.
Unlike a Lens a Getter is read-only. Since a Getter
cannot be used to write back there are no Lens laws that can be applied to
it. In fact, it is isomorphic to an arbitrary function from (s -> a).
Moreover, a Getter can be used directly as a Fold,
since it just ignores the Applicative.
type Getting r s a = (a -> Const r a) -> s -> Const r s Source #
When you see this in a type signature it indicates that you can
pass the function a Lens, Getter,
Traversal, Fold,
Prism, Iso, or one of
the indexed variants, and it will just "do the right thing".
Most Getter combinators are able to be used with both a Getter or a
Fold in limited situations, to do so, they need to be
monomorphic in what we are going to extract with Const. To be compatible
with Lens, Traversal and
Iso we also restricted choices of the irrelevant t and
b parameters.
If a function accepts a , then when Getting r s ar is a Monoid, then
you can pass a Fold (or
Traversal), otherwise you can only pass this a
Getter or Lens.
type Accessing p m s a = p a (Const m a) -> s -> Const m s Source #
This is a convenient alias used when consuming (indexed) getters and (indexed) folds in a highly general fashion.
Building Getters
Combinators for Getters and Folds
(^.) :: s -> Getting a s a -> a infixl 8 Source #
View the value pointed to by a Getter or Lens or the
result of folding over all the results of a Fold or
Traversal that points at a monoidal values.
This is the same operation as view with the arguments flipped.
The fixity and semantics are such that subsequent field accesses can be
performed with (.).
>>>(a,b)^._2b
>>>("hello","world")^._2"world"
>>>import Data.Complex>>>((0, 1 :+ 2), 3)^._1._2.to magnitude2.23606797749979
(^.) :: s ->Getters a -> a (^.) ::Monoidm => s ->Folds m -> m (^.) :: s ->Iso's a -> a (^.) :: s ->Lens's a -> a (^.) ::Monoidm => s ->Traversal's m -> m
view :: MonadReader s m => Getting a s a -> m a Source #
View the value pointed to by a Getter, Iso or
Lens or the result of folding over all the results of a
Fold or Traversal that points
at a monoidal value.
view.to≡id
>>>view (to f) af a
>>>view _2 (1,"hello")"hello"
>>>view (to succ) 56
>>>view (_2._1) ("hello",("world","!!!"))"world"
As view is commonly used to access the target of a Getter or obtain a monoidal summary of the targets of a Fold,
It may be useful to think of it as having one of these more restricted signatures:
view::Getters a -> s -> aview::Monoidm =>Folds m -> s -> mview::Iso's a -> s -> aview::Lens's a -> s -> aview::Monoidm =>Traversal's m -> s -> m
In a more general setting, such as when working with a Monad transformer stack you can use:
view::MonadReaders m =>Getters a -> m aview:: (MonadReaders m,Monoida) =>Folds a -> m aview::MonadReaders m =>Iso's a -> m aview::MonadReaders m =>Lens's a -> m aview:: (MonadReaders m,Monoida) =>Traversal's a -> m a
views :: MonadReader s m => LensLike' (Const r) s a -> (a -> r) -> m r Source #
View a function of the value pointed to by a Getter or Lens or the result of
folding over the result of mapping the targets of a Fold or
Traversal.
viewsl f ≡view(l.tof)
>>>views (to f) g ag (f a)
>>>views _2 length (1,"hello")5
As views is commonly used to access the target of a Getter or obtain a monoidal summary of the targets of a Fold,
It may be useful to think of it as having one of these more restricted signatures:
views::Getters a -> (a -> r) -> s -> rviews::Monoidm =>Folds a -> (a -> m) -> s -> mviews::Iso's a -> (a -> r) -> s -> rviews::Lens's a -> (a -> r) -> s -> rviews::Monoidm =>Traversal's a -> (a -> m) -> s -> m
In a more general setting, such as when working with a Monad transformer stack you can use:
views::MonadReaders m =>Getters a -> (a -> r) -> m rviews:: (MonadReaders m,Monoidr) =>Folds a -> (a -> r) -> m rviews::MonadReaders m =>Iso's a -> (a -> r) -> m rviews::MonadReaders m =>Lens's a -> (a -> r) -> m rviews:: (MonadReaders m,Monoidr) =>Traversal's a -> (a -> r) -> m r
views::MonadReaders m =>Gettingr s a -> (a -> r) -> m r
use :: MonadState s m => Getting a s a -> m a Source #
Use the target of a Lens, Iso, or
Getter in the current state, or use a summary of a
Fold or Traversal that points
to a monoidal value.
>>>evalState (use _1) (a,b)a
>>>evalState (use _1) ("hello","world")"hello"
use::MonadStates m =>Getters a -> m ause:: (MonadStates m,Monoidr) =>Folds r -> m ruse::MonadStates m =>Iso's a -> m ause::MonadStates m =>Lens's a -> m ause:: (MonadStates m,Monoidr) =>Traversal's r -> m r
uses :: MonadState s m => LensLike' (Const r) s a -> (a -> r) -> m r Source #
Use the target of a Lens, Iso or
Getter in the current state, or use a summary of a
Fold or Traversal that
points to a monoidal value.
>>>evalState (uses _1 length) ("hello","world")5
uses::MonadStates m =>Getters a -> (a -> r) -> m ruses:: (MonadStates m,Monoidr) =>Folds a -> (a -> r) -> m ruses::MonadStates m =>Lens's a -> (a -> r) -> m ruses::MonadStates m =>Iso's a -> (a -> r) -> m ruses:: (MonadStates m,Monoidr) =>Traversal's a -> (a -> r) -> m r
uses::MonadStates m =>Gettingr s t a b -> (a -> r) -> m r
listening :: MonadWriter w m => Getting u w u -> m a -> m (a, u) Source #
This is a generalized form of listen that only extracts the portion of
the log that is focused on by a Getter. If given a Fold or a Traversal
then a monoidal summary of the parts of the log that are visited will be
returned.
listening::MonadWriterw m =>Getterw u -> m a -> m (a, u)listening::MonadWriterw m =>Lens'w u -> m a -> m (a, u)listening::MonadWriterw m =>Iso'w u -> m a -> m (a, u)listening:: (MonadWriterw m,Monoidu) =>Foldw u -> m a -> m (a, u)listening:: (MonadWriterw m,Monoidu) =>Traversal'w u -> m a -> m (a, u)listening:: (MonadWriterw m,Monoidu) =>Prism'w u -> m a -> m (a, u)
listenings :: MonadWriter w m => Getting v w u -> (u -> v) -> m a -> m (a, v) Source #
This is a generalized form of listen that only extracts the portion of
the log that is focused on by a Getter. If given a Fold or a Traversal
then a monoidal summary of the parts of the log that are visited will be
returned.
listenings::MonadWriterw m =>Getterw u -> (u -> v) -> m a -> m (a, v)listenings::MonadWriterw m =>Lens'w u -> (u -> v) -> m a -> m (a, v)listenings::MonadWriterw m =>Iso'w u -> (u -> v) -> m a -> m (a, v)listenings:: (MonadWriterw m,Monoidv) =>Foldw u -> (u -> v) -> m a -> m (a, v)listenings:: (MonadWriterw m,Monoidv) =>Traversal'w u -> (u -> v) -> m a -> m (a, v)listenings:: (MonadWriterw m,Monoidv) =>Prism'w u -> (u -> v) -> m a -> m (a, v)
Implementation Details
getting :: (Profunctor p, Profunctor q, Functor f, Functor f) => Optical p q f s t a b -> Optical' p q f s a Source #
Coerce a Getter-compatible Optical to an Optical'. This
is useful when using a Traversal that is not simple as a Getter or a
Fold.
getting::Traversals t a b ->Folds agetting::Lenss t a b ->Getters agetting::IndexedTraversali s t a b ->IndexedFoldi s agetting::IndexedLensi s t a b ->IndexedGetteri s a
newtype Const a (b :: k) :: forall k. Type -> k -> Type #
The Const functor.
Instances
| Generic1 (Const a :: k -> Type) | |
| Bitraversable (Const :: Type -> Type -> Type) | Since: base-4.10.0.0 |
Defined in Data.Bitraversable Methods bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Const a b -> f (Const c d) # | |
| Bifoldable (Const :: Type -> Type -> Type) | Since: base-4.10.0.0 |
| Bifunctor (Const :: Type -> Type -> Type) | Since: base-4.8.0.0 |
| Eq2 (Const :: Type -> Type -> Type) | Since: base-4.9.0.0 |
| Ord2 (Const :: Type -> Type -> Type) | Since: base-4.9.0.0 |
Defined in Data.Functor.Classes | |
| Read2 (Const :: Type -> Type -> Type) | Since: base-4.9.0.0 |
Defined in Data.Functor.Classes Methods liftReadsPrec2 :: (Int -> ReadS a) -> ReadS [a] -> (Int -> ReadS b) -> ReadS [b] -> Int -> ReadS (Const a b) # liftReadList2 :: (Int -> ReadS a) -> ReadS [a] -> (Int -> ReadS b) -> ReadS [b] -> ReadS [Const a b] # liftReadPrec2 :: ReadPrec a -> ReadPrec [a] -> ReadPrec b -> ReadPrec [b] -> ReadPrec (Const a b) # liftReadListPrec2 :: ReadPrec a -> ReadPrec [a] -> ReadPrec b -> ReadPrec [b] -> ReadPrec [Const a b] # | |
| Show2 (Const :: Type -> Type -> Type) | Since: base-4.9.0.0 |
| Functor (Const m :: Type -> Type) | Since: base-2.1 |
| Monoid m => Applicative (Const m :: Type -> Type) | Since: base-2.0.1 |
| Foldable (Const m :: Type -> Type) | Since: base-4.7.0.0 |
Defined in Data.Functor.Const Methods fold :: Monoid m0 => Const m m0 -> m0 # foldMap :: Monoid m0 => (a -> m0) -> Const m a -> m0 # foldr :: (a -> b -> b) -> b -> Const m a -> b # foldr' :: (a -> b -> b) -> b -> Const m a -> b # foldl :: (b -> a -> b) -> b -> Const m a -> b # foldl' :: (b -> a -> b) -> b -> Const m a -> b # foldr1 :: (a -> a -> a) -> Const m a -> a # foldl1 :: (a -> a -> a) -> Const m a -> a # elem :: Eq a => a -> Const m a -> Bool # maximum :: Ord a => Const m a -> a # minimum :: Ord a => Const m a -> a # | |
| Traversable (Const m :: Type -> Type) | Since: base-4.7.0.0 |
| Eq a => Eq1 (Const a :: Type -> Type) | Since: base-4.9.0.0 |
| Ord a => Ord1 (Const a :: Type -> Type) | Since: base-4.9.0.0 |
Defined in Data.Functor.Classes | |
| Read a => Read1 (Const a :: Type -> Type) | Since: base-4.9.0.0 |
Defined in Data.Functor.Classes Methods liftReadsPrec :: (Int -> ReadS a0) -> ReadS [a0] -> Int -> ReadS (Const a a0) # liftReadList :: (Int -> ReadS a0) -> ReadS [a0] -> ReadS [Const a a0] # liftReadPrec :: ReadPrec a0 -> ReadPrec [a0] -> ReadPrec (Const a a0) # liftReadListPrec :: ReadPrec a0 -> ReadPrec [a0] -> ReadPrec [Const a a0] # | |
| Show a => Show1 (Const a :: Type -> Type) | Since: base-4.9.0.0 |
| Functor (Const a :: Type -> Type) | |
| Bounded a => Bounded (Const a b) | Since: base-4.9.0.0 |
| Enum a => Enum (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const Methods succ :: Const a b -> Const a b # pred :: Const a b -> Const a b # fromEnum :: Const a b -> Int # enumFrom :: Const a b -> [Const a b] # enumFromThen :: Const a b -> Const a b -> [Const a b] # enumFromTo :: Const a b -> Const a b -> [Const a b] # enumFromThenTo :: Const a b -> Const a b -> Const a b -> [Const a b] # | |
| Eq a => Eq (Const a b) | Since: base-4.9.0.0 |
| Floating a => Floating (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const Methods exp :: Const a b -> Const a b # log :: Const a b -> Const a b # sqrt :: Const a b -> Const a b # (**) :: Const a b -> Const a b -> Const a b # logBase :: Const a b -> Const a b -> Const a b # sin :: Const a b -> Const a b # cos :: Const a b -> Const a b # tan :: Const a b -> Const a b # asin :: Const a b -> Const a b # acos :: Const a b -> Const a b # atan :: Const a b -> Const a b # sinh :: Const a b -> Const a b # cosh :: Const a b -> Const a b # tanh :: Const a b -> Const a b # asinh :: Const a b -> Const a b # acosh :: Const a b -> Const a b # atanh :: Const a b -> Const a b # log1p :: Const a b -> Const a b # expm1 :: Const a b -> Const a b # | |
| Fractional a => Fractional (Const a b) | Since: base-4.9.0.0 |
| Integral a => Integral (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const Methods quot :: Const a b -> Const a b -> Const a b # rem :: Const a b -> Const a b -> Const a b # div :: Const a b -> Const a b -> Const a b # mod :: Const a b -> Const a b -> Const a b # quotRem :: Const a b -> Const a b -> (Const a b, Const a b) # divMod :: Const a b -> Const a b -> (Const a b, Const a b) # | |
| (Typeable k, Data a, Typeable b) => Data (Const a b) | Since: base-4.10.0.0 |
Defined in Data.Data Methods gfoldl :: (forall d b0. Data d => c (d -> b0) -> d -> c b0) -> (forall g. g -> c g) -> Const a b -> c (Const a b) # gunfold :: (forall b0 r. Data b0 => c (b0 -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Const a b) # toConstr :: Const a b -> Constr # dataTypeOf :: Const a b -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Const a b)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Const a b)) # gmapT :: (forall b0. Data b0 => b0 -> b0) -> Const a b -> Const a b # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Const a b -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Const a b -> r # gmapQ :: (forall d. Data d => d -> u) -> Const a b -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Const a b -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Const a b -> m (Const a b) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Const a b -> m (Const a b) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Const a b -> m (Const a b) # | |
| Num a => Num (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const | |
| Ord a => Ord (Const a b) | Since: base-4.9.0.0 |
| Read a => Read (Const a b) | This instance would be equivalent to the derived instances of the
Since: base-4.8.0.0 |
| Real a => Real (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const Methods toRational :: Const a b -> Rational # | |
| RealFloat a => RealFloat (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const Methods floatRadix :: Const a b -> Integer # floatDigits :: Const a b -> Int # floatRange :: Const a b -> (Int, Int) # decodeFloat :: Const a b -> (Integer, Int) # encodeFloat :: Integer -> Int -> Const a b # exponent :: Const a b -> Int # significand :: Const a b -> Const a b # scaleFloat :: Int -> Const a b -> Const a b # isInfinite :: Const a b -> Bool # isDenormalized :: Const a b -> Bool # isNegativeZero :: Const a b -> Bool # | |
| RealFrac a => RealFrac (Const a b) | Since: base-4.9.0.0 |
| Show a => Show (Const a b) | This instance would be equivalent to the derived instances of the
Since: base-4.8.0.0 |
| Ix a => Ix (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const Methods range :: (Const a b, Const a b) -> [Const a b] # index :: (Const a b, Const a b) -> Const a b -> Int # unsafeIndex :: (Const a b, Const a b) -> Const a b -> Int inRange :: (Const a b, Const a b) -> Const a b -> Bool # rangeSize :: (Const a b, Const a b) -> Int # unsafeRangeSize :: (Const a b, Const a b) -> Int | |
| Generic (Const a b) | |
| Semigroup a => Semigroup (Const a b) | Since: base-4.9.0.0 |
| Monoid a => Monoid (Const a b) | Since: base-4.9.0.0 |
| Storable a => Storable (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const | |
| Bits a => Bits (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const Methods (.&.) :: Const a b -> Const a b -> Const a b # (.|.) :: Const a b -> Const a b -> Const a b # xor :: Const a b -> Const a b -> Const a b # complement :: Const a b -> Const a b # shift :: Const a b -> Int -> Const a b # rotate :: Const a b -> Int -> Const a b # setBit :: Const a b -> Int -> Const a b # clearBit :: Const a b -> Int -> Const a b # complementBit :: Const a b -> Int -> Const a b # testBit :: Const a b -> Int -> Bool # bitSizeMaybe :: Const a b -> Maybe Int # isSigned :: Const a b -> Bool # shiftL :: Const a b -> Int -> Const a b # unsafeShiftL :: Const a b -> Int -> Const a b # shiftR :: Const a b -> Int -> Const a b # unsafeShiftR :: Const a b -> Int -> Const a b # rotateL :: Const a b -> Int -> Const a b # | |
| FiniteBits a => FiniteBits (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const Methods finiteBitSize :: Const a b -> Int # countLeadingZeros :: Const a b -> Int # countTrailingZeros :: Const a b -> Int # | |
| Prim a => Prim (Const a b) | Since: primitive-0.6.5.0 |
Defined in Data.Primitive.Types Methods sizeOf# :: Const a b -> Int# # alignment# :: Const a b -> Int# # indexByteArray# :: ByteArray# -> Int# -> Const a b # readByteArray# :: MutableByteArray# s -> Int# -> State# s -> (#State# s, Const a b#) # writeByteArray# :: MutableByteArray# s -> Int# -> Const a b -> State# s -> State# s # setByteArray# :: MutableByteArray# s -> Int# -> Int# -> Const a b -> State# s -> State# s # indexOffAddr# :: Addr# -> Int# -> Const a b # readOffAddr# :: Addr# -> Int# -> State# s -> (#State# s, Const a b#) # writeOffAddr# :: Addr# -> Int# -> Const a b -> State# s -> State# s # setOffAddr# :: Addr# -> Int# -> Int# -> Const a b -> State# s -> State# s # | |
| Wrapped (Const a x) Source # | |
| t ~ Const a' x' => Rewrapped (Const a x) t Source # | |
Defined in Control.Lens.Wrapped | |
| type Rep1 (Const a :: k -> Type) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const | |
| type Rep (Const a b) | Since: base-4.9.0.0 |
Defined in Data.Functor.Const | |
| type Unwrapped (Const a x) Source # | |
Defined in Control.Lens.Wrapped | |