diff --git a/Lens/Simple.hs b/Lens/Simple.hs --- a/Lens/Simple.hs +++ b/Lens/Simple.hs @@ -1,13 +1,20 @@ {-#LANGUAGE CPP, RankNTypes #-} module Lens.Simple ( - -- * Fundamental lens combinators: @view@, @set@ and @over@ \- also known as @(^.)@, @(.~)@ and @(%~)@ + -- * The fundamental lens operations: @view@, @set@ and @over@ view , set , over + + -- * Stock lenses (@_1@, @_2@) and mere traversals (@_Left@, @_Right@, @_Just@, etc.) for simple Prelude types + , _1 + , _2 + , _Left, _Right + , _Just, _Nothing + , both + -- * @LensLike@ and important strength-expressing synonyms, from the all-powerful @Lens@ downward - , LensLike , Lens , Traversal , Setter @@ -15,16 +22,16 @@ , Fold , FoldLike , SetterLike - + , LensLike - -- * Simple Prelude lenses (@_1@, @_2@) and traversals (@_Left@, @_Right@, @_Just@, etc.) - , _1 - , _2 - , _Left, _Right - , _Just, _Nothing - , both + -- * Support for defining lenses and weaker \'optics\' (see also the TH incantations below ) + , lens + , iso + , to + , setting + , folding - -- * Common lens-applying operators: particularly @view\/(^.)@, @set\/(.~)@, @over\/(%~)@ + -- * Operator equivalents for common lens-applying operators: particularly @(^.)@, @(.~)@ and @(%~)@ (i.e. @view@, @set@ and @over@) , (^.) , (%~) , (.~) @@ -34,21 +41,12 @@ , (^..) , (^?) - - -- * Lens forming support (see also the TH incantations below ) - , lens - , iso - , to - , setting - - - -- * Basic state related combinators: @zoom@, @use@, @assign\/(.=)@ etc. + -- * Basic state-related combinators: @zoom@, @use@, @assign\/(.=)@ etc. , zoom , zoom_ , use, uses , assign - -- * Convenient state-related operators , (%=) , (.=) @@ -74,7 +72,7 @@ , mapped -- * Other combinators - , folding, views + , views , toListOf, allOf, anyOf, firstOf, lastOf, sumOf, productOf , lengthOf, nullOf , backwards @@ -133,7 +131,7 @@ (??) :: Functor f => f (a -> b) -> a -> f b ff ?? a = fmap ($ a) ff {-# INLINE (??) #-} - + type SetterLike a a' b b' = LensLike Identity a a' b b' (?~) :: Setter a a' b (Maybe b') -> b' -> a -> a' diff --git a/lens-simple.cabal b/lens-simple.cabal --- a/lens-simple.cabal +++ b/lens-simple.cabal @@ -1,66 +1,60 @@ name: lens-simple -version: 0.1.0.6 +version: 0.1.0.7 synopsis: simplified import of elementary lens-family combinators description: This module, , - just re-exports the main modules from Russell O\'Connor's - - package, the original library. + just re-exports the main modules from Russell O\'Connor's + package. + @lens-family@ is particularly remarkable for its minute number of dependencies: + apart from + they are all ghc \'boot\' libraries. @Lens.Simple@ also re-exports @makeLenses@ and - other TH incantations from Dan Burton's associated + other convenient TH incantations from Dan Burton's associated . - The idea is just to make a sort of low-powered, minimal-dependency @lens-family@ equivalent of + . + The idea, then, is just to make a sort of low-powered, minimal-dependency, @lens-family@ equivalent of the 800 lb gorilla of lens library imports: . > import Control.Lens . - to wit, the elegant and spritely: + namely, the light-weight and elegant: . > import Lens.Simple . - Check it out, it's even one character shorter! - . - If you are unfamiliar with the use of what O'Connor calls van Laarhoven - lenses, you might take a - look at the excellent - for the - library. All of the tutorial material will compile if you replace - @import Control.Lens@ with the suave @import Lens.Simple@. - The error messages you get might be a little less opaque. But - the point is basically academic, of course: you have already weighed down your - sandbox with the @lens@ library by installing @wreq@ and if you get - any deeper into @wreq@ you will need it. + Check it out, it's even one character shorter! . - As another illustration of the simplicity of the - fundamental van Laarhoven lens combinators, note that the gloss + As an illustration of the simplicity of the + fundamental van Laarhoven lens combinators - and their homogeneity with + @Control.Lens@ - note that the gloss - from the @lens@ library examples directory requires only this - abbreviating change of imports. - If you care to make that program more complicated, - you might at some point need - the unfathomably more sophisticated material in @Control.Lens@. - Within its more limited sphere, @lens-family@ accords as + from the @lens@ library examples directory - which continues to be + the best introductory lens tutorial precisely by saying nothing - + requires /only/ this abbreviating change of imports. + If you make that program more complicated, + you might of course end up needing + the more sophisticated material in @Control.Lens@ and + its immense mass of dependencies. + Within its more limited sphere, though, @lens-family@ accords as far as possible with @lens@, so this switch - will often be all that is necessary to begin using them. + will often be all that is necessary to begin using them. . This module was originally intended to simplify the use of packages that - follow the original promise of the van Laarhoven lenses. Correct practice is - to export lenses without depending on a lens-library, where possible; - in basic cases these use just familiar @Prelude@ types. - Examples of best practices in this respect are + follow the original promise of the van Laarhoven lenses. + /Correct practice is to export lenses without depending on a lens-library, where possible./ + In basic cases these just use familiar @Prelude@ types, after all. + Examples of best practices in this respect are e.g. which + doesn't depend on @lens-family@ despite its name and pipes-related packages like and . - Because of the heavily monadic character of those libraries, the + Because of the heavily monadic character of the latter libraries, the extra material in @Control.Lens@ is rarely of use anyway; one sticks largely - to @view\/(^.)@, @set\/(.~)@, @over\/(%~)@ and @zoom@. + to @view@, @set@, @over@ and, for state operations, @zoom@. . - Note that many of the other lenses and combinators are a bit more + Note that lenses and other combinators are here frequently a bit more specialized than their @Control.Lens@ equivalents: for example, _1 and _2 are here familiarly specialized to act just on real Haskell - pairs. With the loss of abstraction we also of course - lose the concomitant opaque error messages - about @Field1 s t a b@ etc. + pairs. homepage: https://github.com/michaelt/lens-simple license: BSD3