microlens 0.3.4.1 → 0.3.5.0

raw patch · 4 files changed

+105/−4 lines, 4 filesPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

API changes (from Hackage documentation)

Files

• CHANGELOG.md +4/−0
• microlens.cabal +2/−1
• src/Lens/Micro.hs +5/−3
• src/Lens/Micro/Extras.hs +94/−0

@@ -1,3 +1,7 @@+# 0.3.5.0++* Added `Lens.Micro.Extras` with `view`, `preview`, `Getter`, and `Fold`. Now you no longer need microlens-mtl if the only thing you need from it is `view`.+ # 0.3.4.1  * Changed the description of the package from “A tiny part of the lens library which you can depend upon” to “A tiny part of the lens library with no dependencies” because the previous one was ambiguous (I admit I kinda liked that ambiguity, tho).

@@ -1,5 +1,5 @@ name:                microlens-version:             0.3.4.1+version:             0.3.5.0 synopsis:            A tiny part of the lens library with no dependencies description:   This is an extract from <http://hackage.haskell.org/package/lens lens> (with no dependencies). It's not a toy lenses library, unsuitable for “real world”, but merely a small one. It is compatible with lens, and should have same performance. It also has better documentation.@@ -42,6 +42,7 @@  library   exposed-modules:     Lens.Micro+                       Lens.Micro.Extras                        Lens.Micro.Internal                        Lens.Micro.Type   -- other-modules:       

@@ -284,7 +284,7 @@  For details, see the documentation for 'Getting'. -Including @<http://hackage.haskell.org/package/lens/docs/Control-Lens-Getter.html#t:Getter Getter>@ is impossible, as then this package would have to depend on <http://hackage.haskell.org/package/contravariant contravariant> and it's a big dependency.+Including @Getter@ from lens is impossible, as then this package would have to depend on <http://hackage.haskell.org/package/contravariant contravariant> and it's a big dependency. If you absolutely need it, there's a slightly less polymorphic 'Lens.Micro.Extras.Getter' present in "Lens.Micro.Extras". -}  {- |@@ -304,7 +304,7 @@  The reason for this is that traversals use 'Applicative', and the 'Applicative' instance for 'Const' uses monoid concatenation to combine “effects” of 'Const'. -A non-operator version of ('^.') is called @view@, and it's not included in this package because it is a bit more general (it works in @MonadReader@ and thus requires a <http://hackage.haskell.org/package/mtl mtl> dependency). You can get it from <http://hackage.haskell.org/package/microlens-mtl microlens-mtl>.+A non-operator version of ('^.') is called @view@, and it's a bit more general than ('^.') (it works in @MonadReader@). If you need the general version, you can get it from <http://hackage.haskell.org/package/microlens-mtl microlens-mtl>; otherwise there's 'Lens.Micro.Extras.view' available in "Lens.Micro.Extras". -} (^.) :: s -> Getting a s a -> a s ^. l = getConst (l Const s)@@ -372,6 +372,8 @@ Nothing  (Unfortunately, this trick won't help you with setting or modifying.)++Just like with @Getter@, including @Fold@ from lens in this module is impossible. If you absolutely need it, there's a slightly less polymorphic 'Lens.Micro.Extras.Fold' present in "Lens.Micro.Extras". -}  {- |@@ -419,7 +421,7 @@ >>> Right 1 ^? _Right Just 1 -A non-operator version of ('^?') is called @preview@, and – like @view@ – it's not included in this package because it's more general and requires a <http://hackage.haskell.org/package/mtl mtl> dependency). As with @view@, you can get it from <http://hackage.haskell.org/package/microlens-mtl microlens-mtl>.+A non-operator version of ('^?') is called @preview@, and – like @view@ – it's a bit more general than ('^?') (it works in @MonadReader@). If you need the general version, you can get it from <http://hackage.haskell.org/package/microlens-mtl microlens-mtl>; otherwise there's 'Lens.Micro.Extras.preview' available in "Lens.Micro.Extras". -} (^?) :: s -> Getting (First a) s a -> Maybe a s ^? l = getFirst (foldMapOf l (First #. Just) s)

@@ -0,0 +1,94 @@+{-# LANGUAGE+RankNTypes,+FlexibleContexts,+Trustworthy+  #-}+++{- |+This module provides functions and types that are inferior to their lens counterparts.+-}+module Lens.Micro.Extras+(+  view,+  preview,+  Getter,+  Fold,+)+where+++import Lens.Micro+import Lens.Micro.Internal++import Control.Applicative+import Data.Monoid+++{- |+'view' is a synonym for ('^.'):++>>> view _1 (1, 2)+1++The reason it's in this module is that @view@ in lens has a more general signature:++@+view :: MonadReader s m => Getting a s a -> m a+@++So, you would be able to use this 'view' with functions, but not in various reader monads. For most people this shouldn't be an issue.+-}+view :: Getting a s a -> s -> a+view l = getConst #. l Const+{-# INLINE view #-}++{- |+'preview' is a synonym for ('^?'):++>>> preview _head [1,2,3]+Just 1++The reason it's in this module is that @preview@ in lens has a more general signature:++@+preview :: MonadReader s m => Getting (First a) s a -> m (Maybe a)+@++So, just like with 'view', you would be able to use this 'preview' with functions, but not in reader monads.+-}+preview :: Getting (First a) s a -> s -> Maybe a+preview l = getFirst #. foldMapOf l (First #. Just)+{-# INLINE preview #-}++{- |+A @Getter s a@ extracts @a@ from @s@; so, it's the same thing as @(s -> a)@, but you can use it in lens chains. For details, see 'Getting'.++The reason it's in this module is that the actual @Getter@ from lens is more general:++@+type Getter s a =+  forall f. (Contravariant f, Functor f) => (a -> f a) -> s -> f s+@++I'm not currently aware of any functions that take lens's @Getter@ but won't accept this @Getter@, but you should try to avoid exporting 'Getter's anyway to minimise confusion.++Lens users: you can convert fake getters to real getters by applying @to . view@ to them.+-}+type Getter s a = forall r. Getting r s a++{- |+A @Fold s a@ extracts several @a@s from @s@; so, it's pretty much the same thing as @(s -> [a])@, but you can use it with lens operators.++The reason it's in this module is that the actual @Fold@ from lens is more general:++@+type Fold s a =+  forall f. (Contravariant f, Applicative f) => (a -> f a) -> s -> f s+@++I'm only aware of 2 functions that accept lens's @Fold@ but won't accept this @Fold@ – they are @<http://hackage.haskell.org/package/lens/docs/Control-Lens-Fold.html#v:foldByOf foldByOf>@ and @<http://hackage.haskell.org/package/lens-4.13/docs/Control-Lens-Fold.html#v:foldMapByOf foldMapByOf>@. They aren't used often, but you should try to avoid exporting 'Fold's anyway to minimise confusion (and to prevent people cursing you when they want to use @foldByOf@ with your fold).++Lens users: you can convert fake folds to real folds by applying @folded . toListOf@ to them.+-}+type Fold s a = forall r. Applicative (Const r) => Getting r s a