lens
Lenses, Folds and Traversals
http://github.com/ekmett/lens/
Version on this page: | 5.1.1@rev:1 |
LTS Haskell 22.43: | 5.2.3@rev:5 |
Stackage Nightly 2024-12-07: | 5.3.2@rev:2 |
Latest on Hackage: | 5.3.2@rev:2 |
lens-5.1.1@sha256:c633a481e69bf911d9a6ed11ef156809db8b1d7c7d296fd03249b93be399e3a7,15015
Module documentation for 5.1.1
- Control
- Control.Exception
- Control.Lens
- Control.Lens.At
- Control.Lens.Combinators
- Control.Lens.Cons
- Control.Lens.Each
- Control.Lens.Empty
- Control.Lens.Equality
- Control.Lens.Extras
- Control.Lens.Fold
- Control.Lens.Getter
- Control.Lens.Indexed
- Control.Lens.Internal
- Control.Lens.Internal.Bazaar
- Control.Lens.Internal.ByteString
- Control.Lens.Internal.CTypes
- Control.Lens.Internal.Context
- Control.Lens.Internal.Deque
- Control.Lens.Internal.Exception
- Control.Lens.Internal.FieldTH
- Control.Lens.Internal.Fold
- Control.Lens.Internal.Getter
- Control.Lens.Internal.Indexed
- Control.Lens.Internal.Instances
- Control.Lens.Internal.Iso
- Control.Lens.Internal.Level
- Control.Lens.Internal.List
- Control.Lens.Internal.Magma
- Control.Lens.Internal.Prism
- Control.Lens.Internal.PrismTH
- Control.Lens.Internal.Profunctor
- Control.Lens.Internal.Review
- Control.Lens.Internal.Setter
- Control.Lens.Internal.TH
- Control.Lens.Internal.Zoom
- Control.Lens.Iso
- Control.Lens.Lens
- Control.Lens.Level
- Control.Lens.Operators
- Control.Lens.Plated
- Control.Lens.Prism
- Control.Lens.Profunctor
- Control.Lens.Reified
- Control.Lens.Review
- Control.Lens.Setter
- Control.Lens.TH
- Control.Lens.Traversal
- Control.Lens.Tuple
- Control.Lens.Type
- Control.Lens.Unsound
- Control.Lens.Wrapped
- Control.Lens.Zoom
- Control.Monad
- Control.Monad.Error
- Control.Parallel
- Control.Parallel.Strategies
- Control.Seq
- Data
- Data.Array
- Data.Bits
- Data.ByteString
- Data.ByteString.Lazy
- Data.ByteString.Lens
- Data.ByteString.Strict
- Data.Complex
- Data.Data
- Data.Dynamic
- Data.HashSet
- Data.IntSet
- Data.List
- Data.Map
- Data.Sequence
- Data.Set
- Data.Text
- Data.Text.Lazy
- Data.Text.Lens
- Data.Text.Strict
- Data.Tree
- Data.Typeable
- Data.Vector
- Data.Vector.Generic
- Data.Vector.Lens
- GHC
- GHC.Generics
- Language
- Language.Haskell
- Language.Haskell.TH
- Language.Haskell
- Numeric
- Numeric.Lens
- Numeric.Natural
- System
- System.Exit
- System.FilePath
- System.IO
- System.IO.Error
Lens: Lenses, Folds, and Traversals
This package provides families of lenses, isomorphisms, folds, traversals, getters and setters.
If you are looking for where to get started, a crash course video on how lens
was constructed and how to use the basics is available on youtube. It is best watched in high definition to see the slides, but the slides are also available if you want to use them to follow along.
The FAQ, which provides links to a large number of different resources for learning about lenses and an overview of the derivation of these types can be found on the Lens Wiki along with a brief overview and some examples.
Documentation is available through github (for HEAD) or hackage for the current and preceding releases.
Field Guide
Examples
(See wiki/Examples
)
First, import Control.Lens
.
ghci> import Control.Lens
Now, you can read from lenses
ghci> ("hello","world")^._2
"world"
and you can write to lenses.
ghci> set _2 42 ("hello","world")
("hello",42)
Composing lenses for reading (or writing) goes in the order an imperative programmer would expect, and just uses (.)
from the Prelude
.
ghci> ("hello",("world","!!!"))^._2._1
"world"
ghci> set (_2._1) 42 ("hello",("world","!!!"))
("hello",(42,"!!!"))
You can make a Getter
out of a pure function with to
.
ghci> "hello"^.to length
5
You can easily compose a Getter
with a Lens
just using (.)
. No explicit coercion is necessary.
ghci> ("hello",("world","!!!"))^._2._2.to length
3
As we saw above, you can write to lenses and these writes can change the type of the container. (.~)
is an infix alias for set
.
ghci> _1 .~ "hello" $ ((),"world")
("hello","world")
Conversely view
, can be used as a prefix alias for (^.)
.
ghci> view _2 (10,20)
20
There are a large number of other lens variants provided by the library, in particular a Traversal
generalizes traverse
from Data.Traversable
.
We’ll come back to those later, but continuing with just lenses:
You can let the library automatically derive lenses for fields of your data type
data Foo a = Foo { _bar :: Int, _baz :: Int, _quux :: a }
makeLenses ''Foo
This will automatically generate the following lenses:
bar, baz :: Lens' (Foo a) Int
quux :: Lens (Foo a) (Foo b) a b
A Lens
takes 4 parameters because it can change the types of the whole when you change the type of the part.
Often you won’t need this flexibility, a Lens'
takes 2 parameters, and can be used directly as a Lens
.
You can also write to setters that target multiple parts of a structure, or their composition with other lenses or setters. The canonical example of a setter is ‘mapped’:
mapped :: Functor f => Setter (f a) (f b) a b
over
is then analogous to fmap
, but parameterized on the Setter.
ghci> fmap succ [1,2,3]
[2,3,4]
ghci> over mapped succ [1,2,3]
[2,3,4]
The benefit is that you can use any Lens
as a Setter
, and the composition of setters with other setters or lenses using (.)
yields
a Setter
.
ghci> over (mapped._2) succ [(1,2),(3,4)]
[(1,3),(3,5)]
(%~)
is an infix alias for ‘over’, and the precedence lets you avoid swimming in parentheses:
ghci> _1.mapped._2.mapped %~ succ $ ([(42, "hello")],"world")
([(42, "ifmmp")],"world")
There are a number of combinators that resemble the +=
, *=
, etc. operators from C/C++ for working with the monad transformers.
There are +~
, *~
, etc. analogues to those combinators that work functionally, returning the modified version of the structure.
ghci> both *~ 2 $ (1,2)
(2,4)
There are combinators for manipulating the current state in a state monad as well
fresh :: MonadState Int m => m Int
fresh = id <+= 1
Anything you know how to do with a Foldable
container, you can do with a Fold
ghci> :m + Data.Char Data.Text.Lens
ghci> allOf (folded.text) isLower ["hello"^.packed, "goodbye"^.packed]
True
You can also use this for generic programming. Combinators are included that are based on Neil Mitchell’s uniplate
, but which
have been generalized to work on or as lenses, folds, and traversals.
ghci> :m + Data.Data.Lens
ghci> anyOf biplate (=="world") ("hello",(),[(2::Int,"world")])
True
As alluded to above, anything you know how to do with a Traversable
you can do with a Traversal
.
ghci> mapMOf (traverse._2) (\xs -> length xs <$ putStrLn xs) [(42,"hello"),(56,"world")]
"hello"
"world"
[(42,5),(56,5)]
Moreover, many of the lenses supplied are actually isomorphisms, that means you can use them directly as a lens or getter:
ghci> let hello = "hello"^.packed
"hello"
ghci> :t hello
hello :: Text
but you can also flip them around and use them as a lens the other way with from
!
ghci> hello^.from packed.to length
5
You can automatically derive isomorphisms for your own newtypes with makePrisms
. e.g.
newtype Neither a b = Neither { _nor :: Either a b } deriving (Show)
makePrisms ''Neither
will automatically derive
_Neither :: Iso (Neither a b) (Neither c d) (Either a b) (Either c d)
such that
_Neither.from _Neither = id
from _Neither._Neither = id
Alternatively, you can use makeLenses
to automatically derive isomorphisms for your own newtypes. e.g..
makeLenses ''Neither
will automatically derive
nor :: Iso (Either a b) (Either c d) (Neither a b) (Neither c d)
which behaves identically to _Neither
above.
There is also a fully operational, but simple game of Pong in the examples/ folder.
There are also a couple of hundred examples distributed throughout the haddock documentation.
Contact Information
Contributions and bug reports are welcome!
Please feel free to contact me through GitHub or on the #haskell-lens or #haskell IRC channel on Libera Chat.
-Edward Kmett
Changes
5.1.1 [2022.05.17]
-
Add
Data.HashSet.Lens.hashMap
, anIso
between aHashSet a
and aHashMap a ()
. -
Allow building with
transformers-0.6.*
andmtl-2.3.*
.Note that
lens
no longer definesZoom
instances forErrorT
orListT
when building withmtl-2.3
or later. This is becauseMonadState
is a superclass ofZoom
, and theMonadState
instances forErrorT
andListT
were removed inmtl-2.3
. Be watchful of this if you buildlens
withmtl-2.3
(or later) combined with an older version oftransformers
(pre-0.6
) that definesErrorT
orListT
.
5.1 [2021.11.15]
-
Allow building with GHC 9.2.
-
Drop support for GHC 7.10 and older.
-
The type of
_ConP
inLanguage.Haskell.TH.Lens
is nowPrism' Pat (Name, [Type], [Pat])
instead ofPrism' Pat (Name, [Pat])
when building withtemplate-haskell-2.18
or later. -
Define
_CharTyLit
inLanguage.Haskell.TH.Lens
when building withtemplate-haskell-2.18
or later. -
Add
Prefixed
andSuffixed
classes toControl.Lens.Prism
, which provideprefixed
andsuffixed
prisms for prefixes and suffixes of sequence types. These classes generalize theprefixed
andsuffixed
functions inData.List.Lens
, which were previously top-level functions. In addition to providingPrefixed
andSuffixed
instances for lists, instances forText
andByteString
types are also provided.At present,
Prefixed
andSuffixed
are re-exported fromData.List.Lens
for backwards compatibility. This may change in a future version oflens
, however. -
Add a
traversal
function toControl.Lens.Traversal
. This function, aside from acting as aTraversal
counterpart to thelens
andprism
functions, provides documentation on how to defineTraversal
s. -
Add a
matching'
function toControl.Lens.Prism
.matching'
is likematching
, but with a slightly more general type signature that allows it to work with combinations ofLens
es,Prism
s, andTraversal
s.
5.0.1 [2021.02.24]
- Fix a bug in which
makeLenses
could produce ill kinded optics for poly-kinded datatypes in certain situations.
5 [2021.02.17]
-
Support building with GHC 9.0.
-
Remove the
Swapped
type class in favor ofSwap
from theassoc
package. -
Remove the
Strict
type class in favor ofStrict
from thestrict
package.The
swapped
,strict
andlazy
isomorphisms are now defined using “new” type classes.Users which define own instances of old type classes are advised to define instances of the new ones.
import qualified Data.Bifunctor.Swap as Swap import qualified Control.Lens as Lens instance Swap.Swap MyType where swap = ... #if !MIN_VERSION_lens(4,20,0) instance Lens.Swapped MyType where swapped = iso Swap.swap Swap.swap #endif
-
The
FunctorWithIndex
,FoldableWithIndex
andTraversableWithIndex
type classes have been migrated to a new package,indexed-traversable
.The
imapped
,ifolded
anditraversed
methods are now top-level functions. If you are not defining these methods in your instances, you don’t need to change your definitions.Beware: the
optics-core
package (versions <0.4) defines similar classes, and will also migrate to useindexed-traversable
classes. Therefore, you might get duplicate instance errors if your package defines both.If you define your own
FunctorWithIndex
etc. instances, we recommend that you depend directly on theindexed-traversable
package. If you want to continue supportlens-4
users, you may write-- from indexed-traversable import Data.Functor.WithIndex -- from lens import qualified Control.Lens as L -- your (indexed) container data MySeq a = ... -- indexed-traversable instance instance FunctorWithIndex Int MySeq where imap = ... instance FoldableWithIndex Int MySeq where ifoldMap = ... instance TraversableWithIndex Int MySeq where itraverse = ... -- lens <5 instance, note the ! #if !MIN_VERSION_lens(5,0,0) instance L.FunctorWithIndex Int MySeq where imap = imap instance L.FoldableWithIndex Int MySeq where ifoldMap = ifoldMap instance L.TraversableWithIndex Int MySeq where itraverse = itraverse #endif
In other words, always provide
indexed-traversable
instances. If your package depends onlens
and allowslens-4
, you should additionally provide instances forlens-4
type classes that can reuse theindexed-traversable
instances. -
Make the functions in
Control.Lens.TH
work more robustly with poly-kinded data types. This can cause a breaking change under certain situations:- TH-generated optics for poly-kinded data types are now much more likely to
mention kind variables in their definitions, which will require enabling
the
PolyKinds
extension at use sites in order to typecheck. - Because TH-generated optics now quantify more kind variables than they did previously, this can affect the order of visible type applications.
- TH-generated optics for poly-kinded data types are now much more likely to
mention kind variables in their definitions, which will require enabling
the
-
Generalize the types of
generic
andgeneric1
to allow type-changing updates. If you wish to use the old, more restricted types of these functions, usesimple . generic
orsimple . generic1
instead. -
Add
Control.Lens.Profunctor
with conversion functions to and from profunctor optic representation. -
Add
Control.Lens.Review.reviewing
, which is likereview
but with a more polymorphic type. -
Mark
Control.Lens.Equality
as Trustworthy. -
The build-type has been changed from
Custom
toSimple
. To achieve this, thedoctests
test suite has been removed in favor of usingcabal-docspec
to run the doctests. -
Use
alterF
inAt (HashMap k)
instance implementation. -
Use
alterF
inAt
andContains
instances forSet
,IntSet
, andHashSet
. -
Avoid re-inserting keys already present in
ix
forSet
,IntSet
, andHashSet
. ForSet
andHashSet
, this changes the semantics slightly; if the user-supplied key is==
to one already present in the set, then the latter will not be replaced in the result. -
Consume
()
values lazily inControl.Lens.At
.
4.19.2 [2020.04.15]
- Remove the test suite’s dependency on
test-framework-th
.
4.19.1 [2020.02.13]
- Fix a bug introduced in 4.19 where using
_TupE
topreview
a value would always fail.
4.19 [2020.02.03]
- Support building with GHC 8.10.
- The types of
_TupE
and_UnboxedTupE
are nowPrism' Exp [Maybe Exp]
when built againsttemplate-haskell-2.16
or later to reflect the new types ofTupE
andUnboxedTupE
. - Add
_ForallVisT
and_BytesPrimL
prisms when building againsttemplate-haskell-2.16
or later. - Make
<>~
and<>=
and their<op
and<<op
state variants require onlySemigroup
, notMonoid
. - Add
{Functor,Foldable,Traversable}WithIndex
instances forControl.Applicative.Const
andData.Functor.Constant.Constant
.
4.18.1 [2019.09.13]
- Remove the use of
cpp-options: -traditional
. This should be unnecessary on all versions of GHC thatlens
supports, as modern GHCs already use-traditional
internally during preprocessing. More critically, the use ofcpp-options: -traditional
breaks profiling builds on GHC 8.8 (see https://gitlab.haskell.org/ghc/ghc/issues/17185).
4.18 [2019.09.06]
-
Support building with GHC 8.8.
-
Add
xplat
andxplatf
. -
Flip
auf
to take theIso
in the same direction asau
. Use the newxplatf
or just callcoerce
for the old form. -
Weaken
holeInOne
’sCategory p
constraint toComonad (Corep p)
. -
Generalize the type of
GHC.Generics.Lens.generic1
fromIso' (f a) (Rep1 f a)
toIso (f a) (f b) (Rep1 f a) (Rep1 f b)
. -
makeClassyPrisms
now supports generating prisms for data types that share a name with one of its constructors. In such a scenario, the name of the classy prism for the data type will be prefixed with an extra_
(for prefix names) or.
(for infix names) to disambiguate it from the prism for the constructor. -
Several type classes in
Control.Exception.Lens
now have additional prisms corresponding to the data type that they focus on, in accordance with the new convention established in the bullet point above. For example,AsNonTermination
now has an additional__NonTermination :: Prism' t NonTermination
method, and the existing_NonTermination :: Prism' t ()
method now has a default implementation in terms of__NonTermination
.As a consequence of this change, you may need to update instances of these classes to implement the new prisms.
-
Add additional bifunctor instances for
Swapped
. -
New lenses
head1
andlast1
, to access the first/last elements of aTraversable1
container. -
Add
filteredBy
. -
Add
adjoin
toControl.Lens.Unsound
. -
Add
Each (Either a a) (Either b b) a b
instance. -
Make
magnify
offer its getter argument theContravariant
andFunctor
instances it will require. This allowsmagnify
to be used without knowing the concrete monad being magnified. -
Add
equality
,equality'
,withEquality
,underEquality
,overEquality
,fromLeibniz
,fromLeibniz'
andcloneEquality
toControl.Lens.Equality
. -
Add
withLens
toControl.Lens.Lens
. -
Make
substEq
andsimply
inControl.Lens.Equality
andwithIso
inControl.Lens.Iso
levity polymorphic.
4.17.1 [2019.04.26]
- Support
th-abstraction-0.3.0.0
or later. - Only incur
semigroups
andvoid
dependencies on old GHCs. - Add
holes1Of
- Add
locally
https://github.com/ekmett/lens/pull/829 - Add
ilocally
https://github.com/ekmett/lens/pull/836 - Add third
Prism
law. - Add
gplate1
- Add
Wrapped
/Rewrapped
instances forData.Monoid.Ap
.
4.17 [2018.07.03]
- Allow building with GHC 8.6.
- Make the instances for
Product
and(:*:)
inControl.Lens.Tuple
poly-kinded. - Make the definitions in
GHC.Generics.Lens
poly-kinded. - Make
(%%@~)
,(%%@=)
,(<%@=)
, and(<<%@=)
consume anOver (Indexed i)
instead of anIndexedLensLike i
to improve type inference. - Add an
AsEmpty
instance forZipList
.
4.16.1 [2018.03.23]
- Re-export
(<&>)
fromData.Functor
onbase-4.11
and later. - Added
Cons
andSnoc
instances forControl.Applicative.ZipList
- Fix a bug in which
makeFields
would generate equality constraints for field types involving data families, which are unnecessary. - Improve the performance of
holesOf
.
4.16 [2018.01.28]
-
The
Semigroup
instances forTraversed
andSequenced
are now more constrained (going fromApply
toApplicative
andMonad
, respectively). In GHC 8.4,Semigroup
is a superclass ofMonoid
, therefore we’d need to haveApply
constraint in theMonoid
instances. We opted to weaken our ability to useApply
than to lose compatibility with third-party packages that don’t supply instances forApply
.In practice this changes the (specialised) type signature of
traverseOf_
- traverseOf_ :: Apply f => Fold1 s a -> (a -> f r) -> s -> f () + traverseOf_ :: Applicative f => Fold1 s a -> (a -> f r) -> s -> f ()
and similarly for
forOf_
andsequenceOf_
.As part of this change, new combinators
traverse1Of_
,for1Of_
andsequence1Of_
were added forApply
-only effects.Similar instance context changes were made for
Folding
andEffect
, but these changes aren’t publicly visible. -
Add
Control.Lens.Unsound
, which exports unsound functionality for forming products of lenses and sums of prisms. -
Add
Numeric.Natural.Lens
, which export convenient isomorphisms for natural numbers. -
Add
Strict
instances for strict and lazyST
. -
Adapt
Language.Haskell.TH.Lens
fortemplate-haskell-2.13
(bundled with GHC 8.4). -
Add
Semigroup
andMonoid
instances forIndexing
.
4.15.4
-
makeFields
anddeclareFields
are now smarter with respect to type families. Because GHC does not allow mentioning type families in instance heads, the Template Haskell machinery works around this restriction by instead generating instances of the form:type family Fam a data Rec a = Rec { _recFam :: Fam a } makeFields ''Rec ===> instance (b ~ Fam a) => HasFam (Rec a) b where ...
This requires enabling the
UndecidableInstances
extension, so this trick is only employed when a field’s type contains a type family application. -
declareFields
now avoids creating duplicate field classes that are shared among multiple datatypes within the same invocation. -
The Template Haskell machinery will no longer generate optics for fields whose types mention existentially quantified type variables.
-
Add
HasCallStack
constraints to partial operations -
Reexport
(.@~)
and(.@=)
fromControl.Lens.Operators
-
Support
doctest-0.13
4.15.3
- Generalized types of
transformMOf
,transformOf
,transformMOnOf
,transformOnOf
,rewriteMOf
,rewriteOf
,rewriteMOnOf
andrewriteOnOf
. - Depend on
th-abstraction
package for normalizing differences acrosstemplate-haskell
versions
4.15.2
- Build with GHC 8.2
- Expand tuple accessors to support up to 19-tuples
- Add more
Rewrapped
andWrapped
instances for data types from thebase
,bifunctors
,exceptions
,free
,profunctors
, andsemigroupoids
libraries - Add a
Generic
default implementation forWrapped
- Add
Wrapped
instances for data types introduced inForeign.C.Types
andSystem.Posix.Types
inbase-4.10.0.0
- Add prisms for recently introduced data types in
Control.Exception
- Revamp
Setup.hs
to usecabal-doctest
. This makes it build withCabal-1.25
, and makes thedoctest
s work withcabal new-build
and sandboxes. - Add
makeFieldsNoPrefix
, a variant ofmakeFields
which gives the desired behavior in the presence ofDuplicateRecordFields
. Also addclassUnderscoreNoPrefixFields
andclassUnderscoreNoPrefixNamer
, the correspondingLensRules
andFieldNamer
, respectively. - Add
toNonEmptyOf
,first1Of
,last1Of
,minimum1Of
, andmaximum1Of
toControl.Lens.Fold
- Add
both1
toControl.Lens.Traversal
- Generalize the type of
levels
andilevels
inControl.Lens.Level
to work onFold
s - Generalize the type of
getting
inControl.Lens.Getter
to work with anyOptical
- Add
throwing_
toControl.Monad.Error.Lens
andControl.Exception.Lens
- Fix the meta-data in the .cabal file to properly indicate that this project has a BSD2 license
4.15.1
- Restore the
generic
andgeneric1
functions inGHC.Generics.Lens
4.15
- Remove
Generics.Deriving.Lens
module. - Incorporate
URec
, which was introduced inGHC.Generics
inbase-4.9
. For compatibility with older versions ofbase
,lens
now conditionally depends ongeneric-deriving
- Add
Rewrapped
instance forExceptT
- Add
FunctorWithIndex
,FoldableWithIndex
, andTraversableWithIndex
instances forSum
,Proxy
,Tagged
and data types inGHC.Generics
- Remove unneeded context from
*WithIndex HashMap
instances - Add
Data.Map.Lens.toMapOf
- Add moral
Functor
constraint forto
ito
ilike
ilike
to allow the “indented” type signature using Getter with redundant warnings turned on.
4.14
- Remove
Cons
andSnoc
instances forNonEmpty
.
4.13.2.1
- Fixed
itraverse_
andimapM_
returning bottom
4.13.2
- Restore default signature for
Control.Lens.At.at
- Improve operations for
Data.Sequence.Seq
- Fix
declarePrisms
behavior on GHC 8 using GADT record syntax
4.13.1
- Modified to enable the
doctests
to build withstack
. - Removed
.ghci
. - Added
lookupOf
- Support GHC 8
- Support
transformers
0.5 - Support
kan-extensions
5 - Support
comonad
5 - Better support for
Closed
fromprofunctors
.
4.13
- Pattern synonyms
- Moved
foldMapBy
andfoldBy
intoreflection
2.1 - Added
traverseByOf
,sequenceByOf
. - Reexported
traverseBy
andsequenceBy
fromreflection
2.1. - Modified the signatures of
alaf
andauf
to work with aFunctor
rather than aProfunctor
and rather drastically generalized them. - Removed
Control.Lens.Internal.Getter.coerce
in favor of the upstreamphantom
combinator incontravariant
1.3+ - Renamed
coerced
tophantasm
to get it out of the way. - Added
Wrapped
instance forDown
4.12.3
- Move
Review
andAReview
toControl.Lens.Type
fixing a bug inmakePrisms
- Expose
HasTypes
class inLanguage.Haskell.TH.Lens
- Make types of
foldByOf
andfoldMapByOf
more specific to hide implementation details - Add Prisms to
Language.Haskell.TH
for new constructors intemplate-haskell-2.10
- Generalize type of
_FunDep
to anIso
4.12.2
- Incorporated a bug fix for
foldByOf
andfoldMapByOf
to actually let them work on folds. - Added a
Plated
instance forCofreeT
4.12.1
- The
Simple
type alias is now poly-kinded. This lets you useSimple Field1 s a
and the like in constraints. - Added
HasTypes
toLanguage.Haskell.TH.Lens
. - Support for
vector-0.11.0
which changesStream
toBundle
4.12
reflection 2
support.
4.11.2
- Give
cosmosOn
a more general type.
4.11.1
- Added
cosmos
,cosmosOf
,cosmosOn
,cosmosOnOf
toControl.Lens.Plated
. - Added
icontains
,iat
,iix
. - Made various documentation improvements.
- Added a
test-templates
flag.
4.11
- Proper
profunctors
5.1 support. This extended the superclass constraints forConjoined
, so it resulted in a major version bump.
4.10
- Added
elemIndexOf
,elemIndicesOf
,findIndexOf
, andfindIndicesOf
. - Fixed
Ixed
instance forTree
. It no longer drops nodes prior to the traversed node. bifunctors
5,profunctors
5 andsemigroupoids
5 support.
4.9.1
- Added
_Wrapped
support forNonEmpty
. - Added
_Wrapped
support forAlt
. - Fixed
Rewrapped
instance forLast
.
4.9
filepath
1.4 support- Removed
Control.Monad.Primitive.Lens
and shed theprimitive
dependency. - Add missing
_WithIndex
instances fromkeys
package - Much more code is inferred
Safe
rather thanTrustworthy
. - Documented the difference between
unsafeSingular
andsingular
. folding
now produces an actualFold
.- Cleaned up builds for GHC 7.10 to get rid of redundant import warnings.
4.8
- When built with
profunctors
4.4 on GHC 7.8+ we no longer need to useunsafeCoerce
at all! This drastically reduces the level of trust involved in the way we have optimizedlens
. - Added
fusing
. This optimizes longLens
chains, by enfocing a form offmap
fusion based on the Yoneda lemma. This is particularly effective at making faster lenses the definition is recursive or complex enough that it cannot be inlined. - Added
confusing
. This optimizes longTraversal
chains. As withfusing
it is best used when the definition for theTraversal
chain in question is recursive or complex enough that it cannot be inlined, but the implementation is much more confusing. - Remove deprecated stuff:
Control.Lens.Loupe
,headOf
,makeFieldsWith
,strippingPrefix
,strippingSuffix
- Added
Cons
andSnoc
instances forNonEmpty
- Removed
Data.List.Split.Lens
module - Reimplemented
bytestring
traversals to avoid internal modules - Added
gplate
, an implementation ofplate
for any type implementingGeneric
- Strictness revisited
- Add
generateLazyPatterns
configuration flag tomakeLenses
rules. - Make the default
makeLenses
behavior to generate STRICT optics - Add strict variants of
_1
.._9
named_1'
.._9'
- Add
- Generalized some combinators in
Data.Vector.Generic.Lens
and addedconverted
4.7
- Migrated
Control.Lens.Action
tolens-action
. - Added
Data.Vector.Generic.Lens.vectorIx
function for indexing vectors with onlyVector
constraint. - Added
Field1
andField2
instances forData.Functor.Product.Product
. - Removed the “typeclass synonym”
Gettable
. - Added new flag to
makeLenses
,generateUpdateableOptics
, which allows the generation of onlyGetter
s andFold
s. This feature is intended to be used when the constructors are hidden behind validating, “smart” constructors. - Fixed Template Haskell name generation when using GHC 7.10
- Fixed Template Haskell generation of classes methods where field types used existential quantification
4.6.0.1 [maintenance release]
- Compatibility with
base
4.8 [Edit: this turned out to not work for the final release of GHC 7.10]
4.6
- Reduced
Review
to two arguments, likeGetter
. - Added
abbreviatedFields
to permitmakeFieldsWith
to be invoked with an argument that lets it act like it did pre-4.5 and accept arbitrary common prefixes.
4.5
- Provide access to the typename in
lensRules
naming function. makeFields
camelcasing rules now properly support types with camelcasing.MyType
with fieldmyTypeFieldA
generatesfieldA
now. Previously the prefix ignore capitalization and the field would need to be namedmytypeFieldA
.makeClassy
works on types even when none of the fields would generate optics.- Added
Monad
,MonadReader
,MonadPlus
andBind
instances forReifiedMonadicFold
- Added missing fixity declarations on many operators.
- Migrated
Codec.Compression.Zlib.Lens
tozlib-lens
package.
4.4.0.2
text
1.2.0.0 support- Remove the use of the TemplateHaskell extension from the library to enable lens to be used on stage1 cross-compilers
4.4.0.1
- Restore previous default of
makeFields
using the camel case field namer.
4.4
- Internals of Template Haskell code generation rewritten. makeLenses, makeClassy, and makeFields have been unified into the same generator.
- TH generated single constructor Lens use irrefutable pattern matching to enable construction starting with undefined.
- TH generated traverals unify their field arguments (type synonyms not currently expanded) enabling exotic traversals to be generated.
- Added instances for
Text
toData.Aeson.Lens
- Reimplemented
makePrisms
, adding support formakeClassyPrisms
, infix constructrs generate periods (.) prefixed prisms. - Added
Choice
toReview
so thatPrism
is a proper subtype ofReview
- Migrated
Data.Aeson.Lens
tolens-aeson
package. - Fixed
GHC.Generics.Lens.tinplate
behavior on single-field data types and empty data types.
4.3.3
semigroupoids
4.2 support
4.3.2
contravariant
1.0 support
4.3.1
- Added
bytewise
toData.Bits
4.3
- Switched the “direction” of the
Iso
argument toau
to match the order generated bymakePrisms
andmakeLenses
. - Removed
makeIsos
in favor ofmakePrisms
andmakeLenses
. Each of these functions will constructIso
s when appropriate. - Removed
declareIsos
in favor ofdeclarePrisms
anddeclareLenses
. Each of these functions will constructIso
s when appropriate. - Added
matching
for type-changing matches withPrism
s. - Added
withPrism
for recovering the functions passed toprism
. - Added
negated
, the isomorphism for thenegate
function.
4.2
- Added
_Text
isomorphisms to make the proper use with(#)
more obvious and fit newer convention. - Added
Wrapped
instances forVector
types - Resolved issue #439. The various
Prism
s for string-like types inData.Aeson.Lens
are now law-abidingPrism
s “up to quotient.” - Added
selfIndex
. - Support
attoparsec
0.12.
4.1.2
- When used with
exceptions
0.4,throwingM
will permit use with a mereMonadThrow
.
4.1.1
- Generalized the types of
mapping
,bimapping
,contramapping
,dimapping
,lmapping
,rmapping
to support changing theFunctor
,Bifunctor
,Contravariant
, andProfunctor
respectively. - Compatibility with
free
4.6
4.1
- Added
Plated
instances for various free monad variants. - Compatibility with GHC HEAD (7.9+)
4.0.7
- Removed dependency on
constraints
. It was used in a pre-release version of 4.0 but never made it into 4.0, but the dependency had remained around complicating builds for GHC 7.4.
4.0.6
makeLenses
attempt to make the accessors it can under existential quantification.- Added
(&~)
. - Experimental support for parallel builds on GHC 7.8 with
cabal install lens -fj
. Due to at last one known issue with GHC, it isn’t recommended to use this option when rebuilding lens, as a race condition on at least one platform has been seen in the wild. - Added
RoleAnnotations
for GHC 7.8.1. These rule out a few user-accessible bottoms that could be caused by creative abuse of the newCoercible
machinery. However, there was nounsafeCoerce
exposed. - Removed some impossible cases that required unwritable instances from the example doctypes.
4.0.5
- Added
bimapping
toControl.Lens.Iso
- Restored correct behavior of
makePrism
on types with a single constructor. makeLenses
now generatesGetter
s andFold
s on universally quantified fields.
4.0.4
- Made
declareFields
work again.
4.0.3
- Fixed random segfaulting when using
foldMapBy
.
4.0.2
- Properly bundled the modules needed for the properties test suite into the tarball for hackage.
4.0.1
- Typo fixes
- Exporting
Rewrapping
fromControl.Lens.Wrapped
. - Removed the dependency on
cpphs
.
4.0
- Added
nearly
toControl.Lens.Prism
. - Added
Control.Lens.Empty
, exporting_Empty
. - We now require
DefaultSignatures
. - Added
failing
andifailing
toControl.Lens.Traversal
. - Changed the signature of
Data.List.Split.Lens.condensing
due to the addition ofDropBlankFields
toData.List.Split.CondensePolicy
insplit
. - Simplified
Each
,Ixed
, andContains
. They are no longer indexed. The previous design was actively getting in the way of user-defined instances. - Replaced more of our home-grown types with standard ones. They had previously been defined to help make more intelligible error messages, but when we switched to using
(Contravariant f, Functor f)
instead of(Gettable f)
, these ceased to really help. Now you can define even morelens
-compatible types (e.g.Getter
andFold
) without depending onlens
.- Replaced the use of
Accessor
withConst
. - Replaced the use of
Mutator
withIdentity
. - Replaced the use of
Reviewed
withTagged
.
- Replaced the use of
- Removed the deprecated
Control.Lens.Simple
module. - Repurposed
Control.Lens.Combinators
to re-exportControl.Lens
sans any operators; previous residents rehomed toControl.Lens.Lens
. - Added
Control.Lens.Operators
to export just the operators. Varying your import styles between these supports many qualified usage scenarios. - Simplified
Cons
andSnoc
. Now they must be aPrism
. - Simplified
Contains
. This necessitated losing many instancs ofContains
, but makes it much easier and more consistent to use and instantiate. - Simplified the various
AsFoo
types inControl.Exception.Lens
- Simplified the types in
System.IO.Error.Lens
. - Merged
lens-aeson
intolens
. - We’re exiling
Control.Lens.Zipper
to a separate package. This will let the design for it iterate faster and let us explore the trade-offs between the 3.8 style and the 3.9 style of zippers. - Generalized
alongside
,inside
,both
. - Switched to a new
Typeable
version ofreflection
for the harder combinators inControl.Exception.Lens
. This enables us to comply with GHC 7.7’s ban on hand-writtenTypeable
instances. - Added a
_Show
Prism
. - Added
Control.Lens.Extras
for the combinator names we don’t have the gall to claim outright, but which are consistent with the rest. - Renamed the constructors for
ReifiedLens
, etc. to just be the name of their base type. - Added many many missing instances for
ReifiedFold
andReifiedGetter
. This permits things likerunFold ((,) <$> Fold (traverse._1) <*> Fold (traverse._2))
to be aFold
andReifiedFold
can be used as aMonad
,Profunctor
, etc. - Many performance optimizations.
- Switched to
exceptions
fromMonadCatchIO-transformers
- Added types for working with
RelevantFold
andRelevantTraversal
. These are aFold
orTraversal
that always has at least one target. SinceApply
isn’t a superclass ofApplicative
, you occasionally need to convert between them, but it lets you more readily work with less unsafety. - Changed
unwrapping
andwrapping
to have the same constructor-oriented order as aPrism
and renamed them t_Wrapping
and_Unwrapping
respectively. - Drastically changed the way
_Wrapping
and_Unwrapping
are built to get much better inference. - There are about 15,000 lines of patches over the last year, so I’m sure we missed a few big changes.
3.10.1 [maintenance release]
- Compatibility with
base
4.7
3.10.0.1 [maintenance release]
- Compatibility with
text
1.0
3.10
- Switched to
bifunctors
,comonad
,profunctors
, andsemigroupoids
4.0.
3.9.2
- Generalized signatures for
throwing
andthrowingM
.
3.9.1
- ‘condensingPolicy’ was updated to work with ‘split’ 0.2.2
3.9.0.3
- Bumped dependency on
generic-deriving
again.
3.9.0.2
- Bumped dependency on
generic-deriving
to enable building on GHC HEAD.
3.9.0.1
- Updated the field guide image to link to imgur. Sadly the overview haddock and the haddocks are not generated in the same directory, so the haddock hook for copying the image only works locally.
3.9
- Changed
Getting
to take 3 arguments instead of 5. If you need the old behavior for portability you can useOverloaded (Accessor r) s t a b
instead ofGetting r s t a b
and it’ll work consistently back through the last few releases. - Added
involuted
toControl.Lens.Iso
. - Factored out a common
reversed
definition from all the various forms of it around the library and placed it inControl.Lens.Iso
. - Added
binary
,octal
,decimal
andhex
toNumeric.Lens
. - Added
sans
toControl.Lens.At
. - Improved interoperability:
- Reimplemented
Gettable
as an alias forContravariant
andFunctor
together to deriveGetter
andFold
. This means you can now implement aGetter
orFold
with only a Haskell 98 dependency (contravariant
). - Removed
Reviewable
. We now useBifunctor
andProfunctor
together to deriveReview
. This means you can now implement aReview
with Haskell 98 dependencies (profunctors
andbifunctors
). - These changes enables more types to be defined without incurring a dependency on the
lens
package.
- Reimplemented
3.8.7.0-3.8.7.3 [maintenance releases]
- Fixes to dependencies and pragmas.
3.8.6 [maintenance release]
- Fixed an issue with
DefaultSignatures
being used outside of the appropriate#ifdef
that caused compilation issues on GHC 7.0.2. - Generalized the signature of
prism'
- Added
\_Void
andonly
toControl.Lens.Prism
anddevoid
toControl.Lens.Lens
. - Added
\_Nothing
toControl.Lens.Prism
. - Added
devoid
andunited
toControl.Lens.Lens
.
3.8.5
- Fixed more sporadic issues in doctests, caused by carrying flags from
$setup
between modules.
3.8.4
- Renamed
strippingPrefix
toprefixed
,strippingSuffix
tosuffixed
. Left the old names as deprecated aliases. - Fixed issues with the test suite caused by
doctests
carrying flags from the$setup
block between modules. - Benchmarks now use
generic-deriving
rather thanghc-prim
directly, like the rest of the package. - Added
Generics.Deriving.Lens
, which is now simply re-exported fromGHC.Generics.Lens
.
3.8.3
- Added
strippingSuffix
andstripSuffix
toData.Data.Lens
- Added
unpackedBytes
andunpackedChars
toData.ByteString.*.Lens
- Added
unpacked
toData.Text.*.Lens
- Added
(#)
as an infix form ofreview
to ease using aPrism
like a smart constructor inControl.Lens.Review
.
3.8.2
- Added a notion of
Handleable(handler, handler_)
toControl.Exception.Lens
to facilitate constructing aHandler
from an arbitraryFold
orPrism
. - Added a notion of
Handler
andcatches
to andControl.Monad.Error.Lens
to mirror theControl.Exception
andControl.Monad.CatchIO
constructions. - Added additional doctests and documentation.
- Improved error messages and support for types with arguments in
makeFields
.
3.8.1
- Fixed a bug in
makeFields
in hierarchical modules.
3.8.0.2
- Fixed an issue with running the
doctests
test suite when an older version ofsemigroups
is installed.
3.8
- Overall:
- Replaced each of the different
SimpleFoo
type aliases withFoo'
throughout. The variousSimple
aliases can still be found inControl.Lens.Simple
but are now deprecated. - Made sweeping changes to
Iso
andPrism
andIndexed
lenses internally. They are now based onprofunctors
. This affects how you useindexed
in the resulting code and dramatically changed the meaning ofOverloaded
. - Generalized combinators to pass through indices unmodified wherever possible and added indexed variants to existing combinators. There are hundreds of these changes and they would swamp this list.
- Replaced each of the different
Control.Exception.Lens
- This module was created to add combinators and prisms that make it possible to work with GHC’s extensible exceptions and monad transformer stacks more easily. There are knock-on changes in
Data.Dynamic.Lens
,System.Exit.Lens
, andSystem.IO.Error.Lens
.
- This module was created to add combinators and prisms that make it possible to work with GHC’s extensible exceptions and monad transformer stacks more easily. There are knock-on changes in
Control.Lens.At
- Moved
At(at)
andContains(contains)
and factored outIxed(ix)
. - Deprecated
_at
andresultAt
. - Removed various
ordinal
andix
combinators, which are subsumed byIxed(ix)
.
- Moved
Control.Lens.Cons
- Consoldiated the various
_head
,_tail
,_init
and_last
traversals that were scattered around the place into a pair ofCons
andSnoc
classes that provide_Cons
and_Snoc
prisms respectively, and combinators that build on top.
- Consoldiated the various
Control.Lens.Each
- Generalized the signature of
Each
to permit it to provide anIndexedSetter
for((->) e)
. Each
now uses anIndex
type family that is shared withAt
,Ixed
andContains
to indicate these operations are related.
- Generalized the signature of
Control.Lens.Equality
- Added as a stronger form of
Iso
that can be used to safely cast. - Added the adverb
simply
, which can be used to simplify the types of most combinators in the library so they only take a simple lens, simple traversal, etc as their first argument instead. e.g.simply view
forcesa ~ b
,s ~ t
in the argument toview
.
- Added as a stronger form of
Control.Lens.Fold
- Added
foldr1Of'
andfoldl1Of'
. - Added
has
andhasn't
.
- Added
Control.Lens.Indexed
- The various indexed combinators for each type were distributed to their respective modules. This module grew to encompass the remaining index-specifics.
- Added
index
andindices
, and removediwhere
andiwhereOf
. Useitraversed.indices even
andbar.indices (>3)
instead.
Control.Lens.Internal
- This module was exploded into more manageable component modules.
Control.Lens.Iso
Strict(strict)
is now aSimple Iso
.- Added
magma
andimagma
which can be used to provide a ‘debugging view’ of aTraversal
.
Control.Lens.Lens
- Restructuring split this module out from
Control.Lens.Type
and merged the contentsControl.Lens.IndexedLens
.
- Restructuring split this module out from
Control.Lens.Level
- This module was created to provide the breadth-first-search Traversals
levels
andilevels
which can be used to do (optionally depth-limited) breadth-first searches through arbitrary traversals reaching all leaves at finite depth in finite time. To use these in full accordance with the laws you should restrict yourself to commutative operations and finite containers, but they are useful even in the absence of these properties.
- This module was created to provide the breadth-first-search Traversals
Control.Lens.Loupe
- In the interest of consistency, the
Loupe
alias has been deprecated in favor ofALens
. Loupe
(andALens
) are now defined in terms ofPretext
rather thanContext
. This permits them to be cloned at a reduced cost reducing the call forReifiedLens
.
- In the interest of consistency, the
Control.Lens.Operators
- Added this module for users who insist on qualified use, but want access to the operators. They can
import qualified Control.Lens as Lens
andimport Control.Lens.Operators
unqualified.
- Added this module for users who insist on qualified use, but want access to the operators. They can
Control.Lens.Prism
- Added
prism'
to constructSimplePrism
s.
- Added
Control.Lens.Reified
- Consolidated the various
ReifiedFoo
definitions into one module.
- Consolidated the various
Control.Lens.Representable
- This module was removed. Its functionality may be split out into a separate package, but currently the
linear
package exports is ownLinear.Core
module to provide this functionality. It was taking lots of useful names for little functionality and didn’t feel like the rest of the API.
- This module was removed. Its functionality may be split out into a separate package, but currently the
Control.Lens.Review
- This module now factors the
review
functionality out ofPrism
and exposesunto
, which is toreview
whatto
is toview
.
- This module now factors the
Control.Lens.Setter
- Added
contramapped
andargument
for mapping over inputs.
- Added
Control.Lens.Simple
- Removed the infix lens aliases and repurposed the module to house the now deprecated
SimpleFoo
type aliases, which were replaced universally withFoo'
.
- Removed the infix lens aliases and repurposed the module to house the now deprecated
Control.Lens.TH
makeLenses
now generatesLens'
andTraversal'
where appropriate- Added
makePrisms
as a generalizedmakeIso
that automatically generates aPrism
for each constructor.makePrisms
generates names with an_Foo
convention. This was consolidated upon throughout the library to reduce namespace conflicts between prisms and lenses. - Added
makeFields
, which generates classes for each individual field in a data type. - Added
makeWrapped
, which automatically generates aWrapped
instance for a newtype.
Control.Lens.Type
- This module was repurposed to provide a single home for all the standard lens-like type aliases used when producing lenses. You still need to go to their respective modules to find the types for consuming lens-likes if you want to generate your own lens combinators
Control.Lens.Wrapped
- Added
wrapped'
andunwrapped'
for scenarios where you need the help with type inference.
- Added
Control.Lens.Zipper
- Converted
Zipper
to walk a magma based on the original structure and to use indices from indexed traversals when restoring from tape. This also means that when zipping around within a balanced structure with ascending keysmoveTo
can operate in logarithmic time, but required changing theZipper
type to add the index type.
- Converted
Data.Bits.Lens
- Added
byteAt
.
- Added
Data.ByteString.Lens
Data.ByteString.Lazy.Lens
now usesInt64
-based indexing.- The
Traversal
for strictByteStrings
now construct a balanced tree up to a given grain size. This permits zipper based seeking to operate in logarithmic time and speeds up many traversals.
Numeric.Lens
- Created.
base
shows and reads integers at base-2 through base-36.integral
can be used as a safefromInteger
/toInteger
.
- Created.
3.7.6 [maintenance release]
- Fixed an issue with the
Complex
Each
instance.
3.7.5 [maintenance release]
- Fixed an errant
LANGUAGE
pragma
3.7.4 [maintenance release]
- Backported the API for
ALens
andALens'
to supportsnap
builds on old platforms.
3.7.3 [maintenance release]
- Removed my intra-package dependency upper bounds for my own packages. In particular this enables us to work with
semigroups
0.9. - Switched to
transformers-compat
to avoid having unbuilding modules at the top of the documentation, and to ease 3rd party compatibility. - Updated
Setup.lhs
to be compatible with Cabal 1.17
3.7.2 [maintenance release]
- Bug fix for
Magnify
. It was missing functional dependencies to determine itsk
parameter fromm
orn
.
3.7.1.2 [maintenance release]
- Made the doctest test suite hide all but the exact versions of packages used to build this package to avoid problems with complicated user environments.
- Removed doctests based on
:t
as they are fragile and break across GHC versions. - Fixed GHC 7.0.4 compatibility by guarding
DefaultSignatures
inControl.Lens.Each
.
3.7.1.1 [maintenance release]
- Removed tests that will (likely) fail in the presence of
hashable
1.2
3.7.1
- Added
preuse
,preuses
toControl.Lens.Fold
- Added
Each(each)
toControl.Lens.Each
for indexed traversal of potentially monomorphic containers. - Added
indexing64
andtraversed64
for help with large containers. - Generalized the type signature of
choosing
. - Exported
unwrapped
fromControl.Lens.Wrapped
. - Support for
hashable
1.2 - Added
(??)
toControl.Lens.Combinators
.
3.7.0.2
- Fixed flagging for Safe Haskell.
- Fixed examples.
- Cleaned up the statement of the Prism laws.
3.7.0.1
- Corrected bounds for hashable.
- Fixed compatibility with Haskell Platform 2011.4.0.0 – you may have to install with –constraint=“transformers = 0.2.2.0” to avoid getting new mtl and transformer versions installed.
3.7
- Renamed
Projection
toPrism
. - Implemented a complete redesign of the way
Iso
andPrism
are handled internally. AnyIso
can now be used as aPrism
. - The
isos
combinator is no longer required.iso
can now be used to construct anIso
. - Changes to the signature of
from
andunder
were necessitated by the new design. - Added
Control.Lens.Wrapped
providing a canonical isomorphism for newtypes. - Repurposed
ala
to be closer to the original design innewtype
, but addedau
andalaf
. - Added
_magnitude
,_phase
and_conjugate
toData.Complex.Lens
. Renamed other lenses for consistency:_realPart
,_imagPart
,_polar
. - Promoted
_left
and_right
to prisms and moved them toControl.Lens.Prism
. - Generalized
view
andviews
to subsume the old functionality ofperuse
andperuses
. - Generalized
review
andreviews
to both return aMonadReader
and to work on aProjection
. - Added
view'
/views'
anduse'
/uses'
forSimple
access to the environment/state. - Added
set'
, aSimple
version ofset
. - Added
reuse
:use
::review
:view
andreuses
:uses
::reviews
:views
for working aProjection
from the currentMonadState
. - Removed many isomorphisms for various newtypes.
_const
,identity
,_sum
, etc. Usewrapping Const
,wrapping Identity
, etc. - Removed
Data.Monoid.Lens
now that its newtypes are instances ofWrapped
, exporting the (<>=
)-variants fromControl.Lens.*
. - Renamed
via
tocloneIso
for consistency. - Moved
Indexed(..)
toControl.Lens.Classes
. - Renamed
index
toindexed
to reduce conflicts with third-party libraries. - Added
curried
anduncurried
toControl.Lens.Iso
. - Added
Strict(strict)
for ad hoc overloading of conversions between strict and lazy variants ofByteString
andText
. - Bug fixes for
tugTo
andjerkTo
. - These no longer traverse in the wrong direction:
scanl1Of
,scanr1Of
,mapAccumLOf
, andmapAccumROf
. - Added
anon
toControl.Lens.Iso
. - Generalized the types of the
Control.Lens.Zipper
combinators to work with other MonadPlus instances. - Added
withins
toControl.Lens.Zipper
now that they can work better with []. - Added
singular
andunsafeSingular
toControl.Lens.Traversal
to assert aTraversal
is aLens
, aFold
is aGetter
or aMonadicFold
is anAction
. - Generalized
sequenceAOf_
’s type to matchsequenceA_
. - Renamed
up
/down
/left
/right
toupward
/downward
/leftward
/rightward
to reduce conflicts – in particular withControl.Arrow
. - Readded
leftmost
andrightmost
due to the verbosity offarthest leftward
/farthest rightward
. - Added
preview
/previews
/firstOf
and deprecatedheadOf
. - Added
iview
/iviews
/iuse
/iuses
toControl.Lens.IndexedGetter
. - We’ve generalized the type of Bazaar and provided generalized variants of
partsOf
, etc. that used it.
3.6.0.4 [maintenance release]
- Added support for
test-framework
0.8
3.6.0.3 [maintenance release]
- Added support for
test-framework
0.7
3.6.0.2 [maintenance release]
- Added more explicit dependencies to the doctest suite.
- Disabled the ‘expected failure’ quickcheck tests that occasionally would fail with internal QuickCheck errors.
3.6.0.1 [maintenance release]
- Added explicit dependency on containers and unordered-containers to the doctest suite
3.6
- Added
upon
(along with variants of it) toData.Data.Lens
, which can be used to generate aTraversal
from a field accessor or any function that returns, unmodified, a single field that would be visited bytemplate
. - Added some missing
examples/
files to the distribution. - Renamed
Data.Bits.Lens.traverseBits
tobits
. - Removed
(^!?)
, which was an alias for(^?!)
. - Removed the need for
Trustworthy
by changing the implementation ofcoerce
forBazaarT
. - Moved BazaarT to
Control.Lens.Internal
. - Added
(<&>)
toControl.Lens.Combinators
. element
andelementOf
are now indexed traversals rather than lenses and have moved toControl.Lens.IndexedTraversal
. This both fixes their former partiality and lets you use chain indexed combinators with them.- Added
elements
andelementsOf
as indexed traversals for ordinal indexing into regular traversals that generalizeelement
andelementOf
. - Renamed
Data.Complex.Lens.traverseComplex
tocomplex
. - Changed
Data.Complex.Lens.polarize
to aSimple Iso
, due to theRealFloat
constraint causing inference problems. - Renamed
traverseLeft
andtraverseRight
to_left
and_right
respectively. - Renamed
traverseSlice
,traverseFrom
, andtraverseTo
inData.Sequence.Lens
tosliced
,slicedFrom
, andslicedTo
respectively. - Renamed
traverseAt
to_at
inControl.Lens.IndexedTraversal
. - Renamed
traverseArray
to_array
inData.Array.Lens
. - Renamed and made the combinators in
Control.Lens.Zipper
more compositional to reduce third-party naming conflicts down to justleft
andright
. - Renamed
&=
and|=
to.&.=
and.|.=
for consistency, mutatis mutandis their related operations. - Added a
Plated
instances forLanguage.Haskell.TH
types. - Renamed
atIndex
andatIndices
inData.Vector.Lens
andData.Vector.Generic.Lens
toordinal
andordinals
to matchData.Sequence.Lens
3.5.1
- Improved SafeHaskell inference.
3.5
- Fixed a potential SafeHaskell issue where a user could use
undefined
to deriveunsafeCoerce
. You now have to import an explicitly Unsafe module and create an instance ofTrustworthy
for your type to cause this behavior, so if you do, it’s on your head, not mine. :) - Renamed
EvilBazaar
toBazaarT
. - Moved a lot of internals around. Most notably,
Gettable
,Settable
andEffective
have moved toControl.Lens.Classes
. - Exposed
partsOf'
andunsafePartsOf'
inControl.Lens.Traversal
to reduce reliance onBazaarT
inControl.Lens.Zipper
3.4
- Renamed
(%)
to(&)
and(^%)
to(^&)
. This avoids the conflict withData.Ratio
, which was our highest priority conflict with a third party library. - Switched to a more liberal type for
ignored
- Removed some “
isplitting
” bad combinators fromControl.Lens.IndexedFold
. - Made
indexed
,taking
, anddropping
andelementOf
lazier and capable of dealing with infinite traversals and infinite folds. - Improved
Indexing
to support infinite traversals and folds. - Removed some of the more redundant combinators from
Control.Lens.Plated
, which already had existing aliases in the rest of the traversal API. - Moved
partsOf
,holesOf
, andelementOf
intoControl.Lens.Traversal
. - Renamed
query
toperuse
andqueries
toperuses
. These are much less contentious names, both containuse
in their name for analogy touse
anduses
and the word is about reading. - Simpler
simple
. - Added
enum
andnon
toControl.Lens.Iso
. - Added
(^?!)
toControl.Lens.Fold
for unsafe access to the head of aFold
. - Changed
_head
,_tail
,_init
and_last
to traversals inData.List.Lens
andData.Sequence.Lens
. - Eliminated
traverseHead
,traverseTail
,traverseInit
andtraverseLast
. partsOf
andunsafePartsOf
can now also be applied to aFold
yielding aGetter
or to aMonadicFold
yielding anAction
.
3.3
- Redefined
simple
and moved it toControl.Lens.Iso
. Instead of usingsimple l
you can now composel.simple
orsimple.l
providing more nuanced control and a more compositional API. - Moved the various
foo#
combinators used to emit cleaner core into an unexported module,Control.Lens.Unsafe
. This removesMagicHash
from the public API. - Removed the
bazaar#
andrunBazaar#
coercions that caused issues on GHC HEAD. - Changed the default definition of
plate
touniplate
fromignored
. - Added
Data.Vector.Lens
and instances forData.Vector
. - Added support for the
split
package, which is now part of the Haskell platform. - Removed redundant
Data.List.traverseList
. Useitraversed
ortraverse
instead. - Moved
(:<->)
toControl.Lens.Simple
. - Fixed a bug in
Control.Lens.TH
that was causingmakeIso
not to work. - Added
lifted
toControl.Lens.Setter
for mapping over monads. - Added
beside
toControl.Lens.Traversal
. - Removed the operators from
Data.List.Lens
, they broke the overall pattern of the rest of the API, and were terrible clutter. - Fixed a bug that caused
resultAt
to give wrong answers most of the time. - Changed
resultAt
to anIndexedLens
and moved it toControl.Lens.IndexedLens
- Changed
ignored
to anIndexedTraversal
and moved it toControl.Lens.IndexedTraversal
- We’ve relinquished the name
value
.
3.2
- Made
elementOf
lazier and moved it fromControl.Lens.Traversal
toControl.Lens.Plated
. - Made
holesOf
andpartsOf
lazier to deal with infinite structures. - Resolved issue #75. We now generate nicer core for most
Setter
andFold
operations, and some others. - Made lenses for field access like
_1
,_2
, etc. lazier. - Added
Control.Lens.Loupe
, which provides a limited form ofLens
that can be read from and written to and which can compose with other lenses, but can also be returned in a list or as a monadic result, but cannot be used directly for most combinators without cloning it first. It is easier to compose than aReifiedLens
, but slightly slower. - Moved (
:=>
) and (:->
) intoControl.Lens.Simple
, which is not exported byControl.Lens
by default to reduce name conflicts with third party libraries.
3.1
- Simplified the type of
filtered
, so that it can be composed with other folds rather than be parameterized on one. Included the caveat that the newfiltered
is still not a legalTraversal
, despite seeming to compose like one. - Renamed
ifiltered
toifiltering
, and while it still must take an indexed lens-like as an argument, I included a similar caveat about the result not being a legalIndexedLens
when given anIndexedLens
. The function was renamed because its signature no longer lined up with the newfiltered
and the gerundive ‘-ing’ suffix has come to indicate an operator that transformers another lens/traversal/etc. into a new one. - Added
taking
anddropping
toControl.Lens.Traversal
.
3.0.6
- Alpha-renamed all combinators to a new scheme. Instead of
Foo a b c d
, they now followFoo s t a b
. This means that you don’t need to alpha rename everything in your head to work through the examples, simplifies exposition, and uses s and t for common state monad parameters. Thanks go to Shachaf Ben-Kiki for the grunt work of slogging through hundreds of definitions by hand and with regular expressions! - Restored lenses to
Trustworthy
status so they can be used with Safe Haskell once more.
3.0.5
- Fixed a bug in
rights1
andlefts1
inControl.Lens.Zipper
which would cause them to loop forever when given a 0 offset.
3.0.4
- Added
?~
,<?~
,?=
and<?=
toControl.Lens.Setter
for setting the target(s) of a Lens toJust
a value. They are particularly useful when combined withat
.
3.0.3
- Refined the behavior of
substType
inControl.Lens.TH
to match the behavior oftypeVarsEx
when moving under binders.
3.0.2
- Added
generateSignatures
option toControl.Lens.TH
to allow the end user to disable the generation of type signatures for the template-haskell generated lenses. This lets the user supply hand-written haddocks and more restricted signatures.
3.0.1
- Added
Control.Lens.Type.simple
.
3.0
- Added
Control.Lens.Zipper
. - Added
<<~
, a version of<~
that supports chaining assignment. - Added
:->
,:=>
, and:<->
as type operator aliases forSimple Lens
,Simple Traversal
, andSimple Iso
respectively.
2.9
- Added
<<%~
,<<.~
,<<%=
and<<.=
for accessing the old values targeted by aLens
(or a summary of those targeted by aTraversal
) - Renamed
|>
to%
, as%~
is the lensed version of%
, and moved it toControl.Lens.Getter
along with a version^%
with tighter precedence that can be interleaved with^.
- Upgraded to
doctest
0.9, which lets us factor out common$setup
for our doctests - Renamed
merged
tochoosing
. Added a simplerchosen
operation to mirrorboth
. - Added
Control.Lens.Projection
- Renamed
traverseException
toexception
andtraverseDynamic
todynamic
, upgrading them to useProjection
. makeClassy
now places each generatedLens
orTraversal
inside the class it constructs when possible. This makes it possible for users to just exportHasFoo(..)
, rather than have to enumerate each lens in the export list. It can only do that if it creates the class. If thecreateClass
flag is disabled, then it will default to the old behavior.- Added
performs
toControl.Lens.Action
to mirrorviews
inControl.Lens.Getter
.
2.8
- Restored compatibility with GHC 7.2. This required a major version bump due to making some MPTC-based default signatures conditional.
2.7.0.1
- Added the missing
Control.Lens.Combinators
to exported-modules! Its absence was causing it not to be included on hackage.
2.7
- Generalized the signature of
Getting
,Acting
andIndexedGetting
to help out with the common user code scenario of needing to read and then write to change types. - Documentation cleanup and additional examples.
- Renamed
au
toala
, introducing further incompatibility with thenewtype
package, but reducing confusion. - Removed need for
Data.Map.Lens
andData.IntMap.Lens
by addingTraverseMin
andTraverseMax
toControl.Lens.IndexedTraversal
. - Flipped fixity of
~:
and<~:
- Added
++~
,++=
,<++~
and<++=
to Data.List.Lens in response to popular demand. - Added
|>
,<$!>
and<$!
toControl.Lens.Combinators
, which exports combinators that are often useful in lens-based code, but that don’t strictly involve lenses. - Added an HUnit-based test suite by @orenbenkiki
2.6.1
- Fixed bugs in
Traversal
code-generation.
2.6
- Added build option
-f-inlining
to facilitate building with the various TH 2.8 versions used by GHC 7.6 and HEAD. - Added build option
-f-template-haskell
for testing without template haskell. (Users should be able to assume TH is enabled; use this only for testing!) - Added support for generating a
Traversal
rather than aLens
when multiple fields map to the same name or some constructors are missing a field. - Removed
_
from the lens names inSystem.FilePath.Lens
. - Added
iwhere
,withIndices
,withIndicesOf
,indices
andindicesOf
to ease work with indexed traversals - Added
assign
as an alias for(.=)
inControl.Lens.Setter
. - Added
~:
,=:
,<~:
and<=:
toData.List.Lens
2.5
- Added
Control.Lens.Plated
, a port of Neil Mitchell’suniplate
that can be used on anyTraversal
. - Added
Data.Data.Lens
with smart traversals that know how to avoid traversing parts of a structure that can’t contain a given type. - Added
Data.Typeable.Lens
with_cast
and_gcast
liketraverseData
- Renamed
IndexedStore
toContext
now that it is used in user-visible locations, and since I also use it asuniplate
’s notion of a context. - Renamed
Kleene
toBazaar
– “a bazaar contains a bunch of stores.” - Added
Comonad
instances forContext
andBazaar
, so we can use stores directly as the notion of an editable context in uniplate - Compatibility with both sets of template haskell quirks for GHC 7.6.1-rc1 and the GHC 7.6.1 development head.
- Renamed
children
tobranches
inData.Tree.Lens
. - Added
At
andContains
toControl.Lens.IndexedLens
. - Added
FunctorWithIndex
,FoldableWithIndex
, andTraversableWithIndex
underControl.Lens.WithIndex
- Added support for
unordered-containers
.
2.4.0.2
- GHC 7.6.1 development HEAD compatibility (but broke 7.6.1-rc1)
2.4.0.1
- Haddock cleanup
2.4
- Added the indexed
Kleene
store toControl.Lens.Internal
- Moved
Gettable
,Accessor
,Settable
andMutator
toControl.Lens.Internal
- Added
cloneTraversal
toControl.Lens.Traversal
- Renamed
clone
tocloneLens
inControl.Lens.Type
- Generalized the type of
zoom
to subsumefocus
. - Removed
Focus(..)
fromControl.Lens.Type
. - Factored out
Control.Lens.Isomorphic
. - Moved many private types to
Control.Lens.Internal
- Added
conFields
toLanguage.Haskell.TH.Lens
. - Added
System.FilePath.Lens
.
2.3
- Added missing
{-# INLINE #-}
pragmas - Renamed
meanwhile
tothroughout
inControl.Parallel.Strategies.Lens
- Added
Magnify
toControl.Lens.Getter
. - Added
Zoom
toControl.Lens.Type
.
2.2
- Added
<&=
,<&~
,<|=
, and<|~
- Moved
<>~
,<<>~
,<>=
, and<<>=
toData.Monoid.Lens
- Template Haskell now uses eager binding to avoid adding dependencies.
2.1
- Renamed
adjust
toover
- Added
au
,auf
andunder
- Added
Data.Monoid.Lens
- Increased lower dependency bound on
mtl
for cleaner installation.