diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,16 @@ +# optics-0.2 (2019-10-18) +* Add `non`, `non'` and `anon` to `Optics.Iso` +* `ix` can produce optic kinds other than `AffineTraversal` +* Generalise type of `generic1` +* Move `use` from `Optics.View` to `Optics.State` and restrict its type +* Add `preuse` to `Optics.State` +* Rename `use`, `uses`, `listening` and `listenings` to reflect the fact that + they have `ViewResult`-generalised types +* Add `noPrefixFieldLabels` and `noPrefixNamer` to `Optics.TH` +* Move some internal definitions out to new `indexed-profunctors` package +* Introduce `OpticKind` and `IxList` type synonyms for better type inference +* Make `itraverse` for `Seq` faster for `containers >= 0.6.0` +* Assorted documentation improvements + +# optics-0.1 (2019-09-02) +* Initial release diff --git a/optics.cabal b/optics.cabal --- a/optics.cabal +++ b/optics.cabal @@ -1,12 +1,12 @@ name: optics -version: 0.1 +version: 0.2 license: BSD3 license-file: LICENSE build-type: Simple maintainer: optics@well-typed.com author: Adam Gundry, Andres Löh, Andrzej Rybczak, Oleg Grenrus cabal-version: 1.24 -tested-with: ghc ==8.0.2 || ==8.2.2 || ==8.4.4 || ==8.6.5 || ==8.8.1 +tested-with: ghc ==8.0.2 || ==8.2.2 || ==8.4.4 || ==8.6.5 || ==8.8.1, GHCJS ==8.4 synopsis: Optics as an abstract interface category: Data, Optics, Lenses description: @@ -14,12 +14,18 @@ and other optics, using an abstract interface. See the main module "Optics" for the documentation. . + This is the "batteries-included" variant with many dependencies; see the - @optics-core@ package and other @optics-*@ dependencies if you need a more - limited dependency footprint. + @@ package and + other @optics-*@ dependencies if you need a more limited dependency footprint. + . + Note: Hackage does not yet display documentation for reexported-modules, + but you can start from the "Optics" module documentation or see the module + list in @@. extra-doc-files: diagrams/*.png + CHANGELOG.md bug-reports: https://github.com/well-typed/optics/issues source-repository head @@ -36,9 +42,9 @@ , array >= 0.5.1.1 && <0.6 , containers >= 0.5.7.1 && <0.7 , mtl >= 2.2.2 && <2.3 - , optics-core >= 0.1 && <1 - , optics-extra >= 0.1 && <1 - , optics-th >= 0.1 && <1 + , optics-core >= 0.2 && <0.2.1 + , optics-extra >= 0.2 && <0.2.1 + , optics-th >= 0.2 && <0.2.1 , transformers >= 0.5 && <0.6 -- main module to land with repl @@ -119,8 +125,13 @@ hs-source-dirs: tests ghc-options: -Wall + -- inspection-testing doesn't compile with GHCJS + if impl(ghcjs) + buildable: False + build-depends: base , containers + , indexed-profunctors >= 0.1 && <0.2 , inspection-testing >= 0.4.1.1 && <0.5 , mtl , optics @@ -146,6 +157,10 @@ hs-source-dirs: benchmarks ghc-options: -Wall -threaded + -- GHCJS takes forever to compile dependencies + if impl(ghcjs) + buildable: False + build-depends: base , bytestring , containers @@ -163,6 +178,10 @@ default-language: Haskell2010 hs-source-dirs: benchmarks ghc-options: -Wall -threaded + + -- GHCJS takes forever to compile dependencies + if impl(ghcjs) + buildable: False build-depends: base , bytestring diff --git a/src/Optics.hs b/src/Optics.hs --- a/src/Optics.hs +++ b/src/Optics.hs @@ -166,6 +166,9 @@ -- * Optics for concrete base types , module P + + -- * Cheat sheet + -- $cheatsheet ) where @@ -343,7 +346,7 @@ -- constructors, respectively). Any lens is a traversal (where the list of -- elements is always a singleton list), and any prism is also a traversal -- (where there will be zero or one element depending on whether the --- constructor matches). This was implicit in the fact that we used that we +-- constructor matches). This was implicit in the fact that we -- used the same operators in multiple cases: 'view' gives the projection -- function of both an isomorphism and a lens, but cannot be applied to a -- traversal. @@ -517,7 +520,7 @@ -- 'Join' of a 'Lens' and a 'Prism' is an 'AffineTraversal'. -- -- >>> :kind! Join A_Lens A_Prism --- Join A_Lens A_Prism :: * +-- Join A_Lens A_Prism :: OpticKind -- = An_AffineTraversal -- -- The join does not exist for some pairs of optic kinds, which means that they @@ -525,7 +528,7 @@ -- and 'Fold': -- -- >>> :kind! Join A_Setter A_Fold --- Join A_Setter A_Fold :: * +-- Join A_Setter A_Fold :: OpticKind -- = (TypeError ...) -- -- >>> :t mapped % folded @@ -846,6 +849,94 @@ -- Optic A_Traversal '[i] (f a, c) (f b, c) a b -- -- <> + +-- $cheatsheet +-- +-- The following table summarizes the key optic kinds and their combinators. +-- It is based on a [similar table for the lens +-- package](https://github.com/ekmett/lens/wiki/operators). +-- +-- A 'Lens' can be used as a 'Getter', 'Setter', 'Fold' and 'Traversal'. +-- +-- +-------------------+---------------+---------------------------------------------------+ +-- |Combinator |Indexed |Notes | +-- +===================+===============+===================================================+ +-- |   | +-- +-------------------+---------------+---------------------------------------------------+ +-- |__Getters__ | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'to' |'ito' |Build a 'Getter' / 'IxGetter' from a plain | +-- | | |function. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'view' / '^.' |'iview' |View a single target. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'views' |'iviews' |View after applying a function. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |   | | +-- +-------------------+---------------+---------------------------------------------------+ +-- |__Setters__ | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'sets' |'isets' |Build a 'Setter' / 'IxSetter' from an update | +-- | | |function. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'mapped' |'imapped' |Build a 'Setter' from the 'Functor' class, or an | +-- | | |'IxSetter' from 'FunctorWithIndex'. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'set' / '.~' |'iset' |Replace target(s) with value. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'over' / '%~' |'iover' |Modify target(s) by applying a function. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |   | +-- +-------------------+---------------+---------------------------------------------------+ +-- |__Folds__ | | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'folded' | 'ifolded' |Build a 'Fold' from the 'Foldable' class, or an | +-- | | |'IxFold' from 'FoldableWithIndex'. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'toListOf' / '^..' |'itoListOf' |Return a list of the target(s). | +-- +-------------------+---------------+---------------------------------------------------+ +-- |   | +-- +-------------------+---------------+---------------------------------------------------+ +-- |__AffineFolds__ | +-- +-------------------+---------------+---------------------------------------------------+ +-- | 'afolding' |'iafolding' |Build an 'AffineFold' / 'IxAffineFold' from a | +-- | | |partial function. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'preview' / '^?' |'ipreview' |Match the target or return 'Nothing'. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'previews' |'ipreviews' |Preview after applying a function. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |   | +-- +-------------------+---------------+---------------------------------------------------+ +-- |__Traversals__ | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'traversed' |'itraversed' |Build a 'Traversal' from the 'Traversable' class, | +-- | | |or an 'IxTraversal' from 'TraversableWithIndex'. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'traverseOf' |'itraverseOf' |Update target(s) with an 'Applicative'. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |   | +-- +-------------------+---------------+---------------------------------------------------+ +-- |__Prisms__ | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'prism' | |Build a 'Prism' from a constructor and matcher. | +-- +-------------------+---------------+---------------------------------------------------+ +-- |'review' / '#' | |Use a 'Prism' to construct the sum type. | +-- +-------------------+---------------+---------------------------------------------------+ +-- +-- For setting/modifying using a 'Setter', a variety of combinators are available +-- in "Optics.State" and "Optics.State.Operators". The latter are not exported +-- by the main "Optics" module, so must be imported explicitly. +-- +-- +--------------+-----------------+-------------------------------------------+------------------------------+-------------------------------+-------------------------------------------+ +-- | Lazy | Strict | Stateful | Stateful returning new value | Stateful returning old value | Notes | +-- +==============+=================+===========================================+==============================+===============================+===========================================+ +-- |'set' / '.~' | 'set'' / '!~' | 'assign' / 'Optics.State.Operators..=' | 'Optics.State.Operators.<.=' | 'Optics.State.Operators.<<.=' | Replace target(s) with value. | +-- +--------------+-----------------+-------------------------------------------+------------------------------+-------------------------------+-------------------------------------------+ +-- |'over' / '%~' | 'over'' / '%!~' | 'modifying' / 'Optics.State.Operators.%=' | 'Optics.State.Operators.<%=' | 'Optics.State.Operators.<<%=' | Modify target(s) by applying a function. | +-- +--------------+-----------------+-------------------------------------------+------------------------------+-------------------------------+-------------------------------------------+ +-- | '?~' | '?!~' | 'Optics.State.Operators.?=' | 'Optics.State.Operators.>> import Control.Monad.Reader diff --git a/tests/Optics/Tests/Utils.hs b/tests/Optics/Tests/Utils.hs --- a/tests/Optics/Tests/Utils.hs +++ b/tests/Optics/Tests/Utils.hs @@ -6,7 +6,7 @@ import Test.Tasty.HUnit import Test.Inspection -import qualified Optics.Internal.Profunctor as P +import qualified Data.Profunctor.Indexed as P hasNoProfunctors :: Name -> Obligation hasNoProfunctors name = mkObligation name $ NoUseOf