microlens-th 0.1.1.0 → 0.1.2.0

raw patch · 3 files changed

+57/−68 lines, 3 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-th.cabal +15/−1
• src/Lens/Micro/TH.hs +38/−67

@@ -1,3 +1,7 @@+# 0.1.2.0++* Package now compiles with `-O2` and other optimisations by default.+ # 0.1.1.0  * Added `makeLensesFor` (and `lensRulesFor`).

@@ -1,5 +1,5 @@ name:                microlens-th-version:             0.1.1.0+version:             0.1.2.0 synopsis:            Automatic generation of record lenses for microlens description:   This package lets you automatically generate lenses for data types; code@@ -22,6 +22,11 @@   type:                git   location:            git://github.com/aelve/microlens.git +flag inlining+  description:         Generate inline pragmas+  manual:              True+  default:             True+ library   exposed-modules:     Lens.Micro.TH   -- other-modules:       @@ -30,5 +35,14 @@                      , microlens ==0.1.*                      , containers >=0.4                      , template-haskell >=2.7++  if flag(inlining)+    cpp-options: -DINLINING++  ghc-options:+    -Wall -fwarn-tabs+    -O2 -fdicts-cheap -funbox-strict-fields+    -fmax-simplifier-iterations=10+   hs-source-dirs:      src   default-language:    Haskell2010

@@ -53,18 +53,17 @@ import           Data.Set (Set) import           Data.List (nub, findIndices, stripPrefix, isPrefixOf) import           Data.Maybe-import           Data.Traversable (traverse, sequenceA) import           Lens.Micro import           Language.Haskell.TH +#if __GLASGOW_HASKELL__ < 710+import           Data.Traversable (traverse, sequenceA)+#endif++ {- $compatnote -When updates aren't allowed, or when a field simply can't be updated (for-instance, in the presence of @forall@), instead of 'Lens' and 'Traversal' we-generate 'Getter' and 'Fold'. These aren't true @Getter@ and @Fold@ from lens-– they're not sufficiently polymorphic. Beware. (Still, they're compatible,-it's just that you can't do some things with them that you can do with-original ones.)+When updates aren't allowed, or when a field simply can't be updated (for instance, in the presence of @forall@), instead of 'Lens' and 'Traversal' we generate 'Getter' and 'Fold'. These aren't true @Getter@ and @Fold@ from lens – they're not sufficiently polymorphic. Beware. (Still, they're compatible, it's just that you can't do some things with them that you can do with original ones.) -}  type Getter s a = forall r. Getting r s a@@ -128,8 +127,7 @@ {-# LANGUAGE TemplateHaskell #-} @ -Then, after declaring the datatype (let's say @Foo@), add @makeLenses ''Foo@-on a separate line:+Then, after declaring the datatype (let's say @Foo@), add @makeLenses ''Foo@ on a separate line:  @ data Foo = Foo {@@ -139,8 +137,7 @@ makeLenses ''Foo @ -This would generate the following lenses, which can be used to access the-fields of @Foo@:+This would generate the following lenses, which can be used to access the fields of @Foo@:  @ x :: 'Lens'' Foo Int@@ -150,14 +147,21 @@ y f foo = (\\y' -> f {_y = y'}) '<$>' f (_y foo) @ -If you don't want a lens to be generated for some field, don't prefix it with-an @_@.+(If you don't want a lens to be generated for some field, don't prefix it with an @_@.) -When the data type has type parameters, it's possible for a lens to do a-polymorphic update – i.e. change the type of the thing along with changing-the type of the field. For instance, with this type:+If you want to creat lenses for many types, you can do it all in one place like this (of course, instead you just can use 'makeLenses' several times if you feel it would be more readable):  @+data Foo = ...+data Bar = ...+data Quux = ...++'concat' '<$>' 'mapM' 'makeLenses' [''Foo, ''Bar, ''Quux]+@++When the data type has type parameters, it's possible for a lens to do a polymorphic update – i.e. change the type of the thing along with changing the type of the field. For instance, with this type:++@ data Foo a = Foo {   _x :: a,   _y :: Bool }@@ -170,8 +174,7 @@ y :: 'Lens'' (Foo a) Bool @ -However, when there are several fields using the same type parameter,-type-changing updates are no longer possible:+However, when there are several fields using the same type parameter, type-changing updates are no longer possible:  @ data Foo a = Foo {@@ -186,9 +189,7 @@ y :: 'Lens'' (Foo a) a @ -Next thing. When the type has several constructors, some of fields may not be-/always/ present – for those, a 'Traversal' is generated instead. For-instance, in this example @y@ can be present or absent:+Finally, when the type has several constructors, some of fields may not be /always/ present – for those, a 'Traversal' is generated instead. For instance, in this example @y@ can be present or absent:  @ data FooBar@@ -203,9 +204,7 @@ y :: 'Traversal'' FooBar Bool @ -So, to get @_y@, you'd have to either use ('^?') if you're not sure it's-there, or ('^?!') if you're absolutely sure (and if you're wrong, you'll get-an exception). Setting and updating @_y@ can be done as usual.+So, to get @_y@, you'd have to either use ('^?') if you're not sure it's there, or ('^?!') if you're absolutely sure (and if you're wrong, you'll get an exception). Setting and updating @_y@ can be done as usual. -} makeLenses :: Name -> DecsQ makeLenses = makeFieldOptics lensRules@@ -219,12 +218,9 @@ 'makeLensesFor' [(\"foo\", \"fooLens\"), (\"bar\", \"_bar\")] ''Foo @ -would create lenses called @fooLens@ and @_bar@. This is useful, for instance,-when you don't want to prefix your fields with underscores and want to prefix-/lenses/ with underscores instead.+would create lenses called @fooLens@ and @_bar@. This is useful, for instance, when you don't want to prefix your fields with underscores and want to prefix /lenses/ with underscores instead. -If you give the same name to different fields, it will generate a 'Traversal'-instead:+If you give the same name to different fields, it will generate a 'Traversal' instead:  @ data Foo = Foo {slot1, slot2, slot3 :: Int}@@ -240,10 +236,7 @@ {- | Generate lenses with custom parameters. -This function lets you customise generated lenses; to see what exactly can be-changed, look at 'LensRules'. 'makeLenses' is implemented with-'makeLensesWith' – it uses the 'lensRules' configuration (which you can build-upon – see the “Configuring lens rules” section).+This function lets you customise generated lenses; to see what exactly can be changed, look at 'LensRules'. 'makeLenses' is implemented with 'makeLensesWith' – it uses the 'lensRules' configuration (which you can build upon – see the “Configuring lens rules” section).  Here's an example of generating lenses that would use lazy patterns: @@ -253,8 +246,7 @@ 'makeLensesWith' ('lensRules' '&' 'generateLazyPatterns' '.~' True) ''Foo @ -When there are several modifications to the rules, the code looks nicer when-you use 'flip':+When there are several modifications to the rules, the code looks nicer when you use 'flip':  @ 'flip' 'makeLensesWith' ''Foo $@@ -269,9 +261,7 @@ {- | Generate overloaded lenses. -This lets you deal with several data types having same fields. For instance,-let's say you have @Foo@ and @Bar@, and both have a field named @x@. To-avoid those fields clashing, you would have to use prefixes:+This lets you deal with several data types having same fields. For instance, let's say you have @Foo@ and @Bar@, and both have a field named @x@. To avoid those fields clashing, you would have to use prefixes:  @ data Foo a = Foo {@@ -282,10 +272,7 @@   barX :: Char } @ -However, if you use 'makeFields' on both @Foo@ and @Bar@ now, it would-generate lenses called @x@ and @y@ – and @x@ would be able to access both-@fooX@ and @barX@! This is done by generating a separate class for each-field, and making relevant types instances of that class:+However, if you use 'makeFields' on both @Foo@ and @Bar@ now, it would generate lenses called @x@ and @y@ – and @x@ would be able to access both @fooX@ and @barX@! This is done by generating a separate class for each field, and making relevant types instances of that class:  @ class HasX s a | s -> a where@@ -308,25 +295,15 @@   y = ... @ -(There's a minor drawback, tho: you can't perform type-changing updates with-these lenses.)+(There's a minor drawback, tho: you can't perform type-changing updates with these lenses.) -If you only want to make lenses for some fields, you can prefix them with-underscores – the rest would be untouched. If no fields are prefixed with-underscores, lenses would be created for all fields.+If you only want to make lenses for some fields, you can prefix them with underscores – the rest would be untouched. If no fields are prefixed with underscores, lenses would be created for all fields. -The prefix must be the same as the name of the name of the data type (/not/-the constructor).+The prefix must be the same as the name of the name of the data type (/not/ the constructor). -If you want to use 'makeFields' on types declared in different modules, you-can do it, but then you would have to export the @Has*@ classes from one of-the modules – 'makeFields' creates a class if it's not in scope yet, so the-class must be in scope or else there would be duplicate classes and you would-get an “Ambiguous occurrence” error.+If you want to use 'makeFields' on types declared in different modules, you can do it, but then you would have to export the @Has*@ classes from one of the modules – 'makeFields' creates a class if it's not in scope yet, so the class must be in scope or else there would be duplicate classes and you would get an “Ambiguous occurrence” error. -Finally, 'makeFields' is implemented as @'makeLenses' 'camelCaseFields'@, so-you can build on 'camelCaseFields' if you want to customise behavior of-'makeFields'.+Finally, 'makeFields' is implemented as @'makeLenses' 'camelCaseFields'@, so you can build on 'camelCaseFields' if you want to customise behavior of 'makeFields'. -} makeFields :: Name -> DecsQ makeFields = makeFieldOptics camelCaseFields@@ -354,8 +331,7 @@   fmap (\x -> r { _allowUpdates = x}) (f (_allowUpdates r))  {- |-Generate optics using lazy pattern matches. This can allow fields of an-undefined value to be initialized with lenses:+Generate optics using lazy pattern matches. This can allow fields of an undefined value to be initialized with lenses:  @ data Foo = Foo {_x :: Int, _y :: Bool}@@ -371,12 +347,9 @@  (Without 'generateLazyPatterns', the result would be just 'undefined'.) -The downside of this flag is that it can lead to space-leaks and-code-size\/compile-time increases when generated for large records. By-default this flag is turned off, and strict optics are generated.+The downside of this flag is that it can lead to space-leaks and code-size\/compile-time increases when generated for large records. By default this flag is turned off, and strict optics are generated. -When you have a lazy optic, you can get a strict optic from it by composing-with ('$!'):+When you have a lazy optic, you can get a strict optic from it by composing with ('$!'):  @ strictOptic = ('$!') . lazyOptic@@ -948,9 +921,7 @@ ------------------------------------------------------------------------  {- |-Rules used to generate lenses. You can't create them from scratch, but you-can customise already existing ones with lenses in the “Configuring lens-rules” section.+Rules used to generate lenses. You can't create them from scratch, but you can customise already existing ones with lenses in the “Configuring lens rules” section.  For an example, see 'makeLensesWith'. -}