lens-3.8.7.3: Lenses, Folds and Traversals

Portability | non-portable
Stability | experimental
Maintainer | Edward Kmett <ekmett@gmail.com>
Safe Haskell | Trustworthy

Control.Lens.TH

Contents

- Constructing Lenses Automatically
- Configuring Lenses

Description

Synopsis

- makeLenses :: Name -> Q [Dec]
- makeLensesFor :: [(String, String)] -> Name -> Q [Dec]
- makeClassy :: Name -> Q [Dec]
- makeClassyFor :: String -> String -> [(String, String)] -> Name -> Q [Dec]
- makeIso :: Name -> Q [Dec]
- makePrisms :: Name -> Q [Dec]
- makeWrapped :: Name -> DecsQ
- makeFields :: Name -> Q [Dec]
- makeLensesWith :: LensRules -> Name -> Q [Dec]
- makeFieldsWith :: FieldRules -> Name -> Q [Dec]
- defaultRules :: LensRules
- defaultFieldRules :: FieldRules
- camelCaseFields :: FieldRules
- underscoreFields :: FieldRules
- data LensRules = LensRules (String -> Maybe String) (String -> Maybe String) (String -> Maybe (String, String)) (Set LensFlag)
- data FieldRules = FieldRules (String -> Maybe String) (String -> String) (String -> Maybe String) (String -> Maybe String)
- lensRules :: LensRules
- classyRules :: LensRules
- isoRules :: LensRules
- lensIso :: Lens' LensRules (String -> Maybe String)
- lensField :: Lens' LensRules (String -> Maybe String)
- lensClass :: Lens' LensRules (String -> Maybe (String, String))
- lensFlags :: Lens' LensRules (Set LensFlag)
- data LensFlag
  - = SimpleLenses
  - | PartialLenses
  - | BuildTraversals
  - | SingletonAndField
  - | SingletonIso
  - | HandleSingletons
  - | SingletonRequired
  - | CreateClass
  - | CreateInstance
  - | ClassRequired
  - | GenerateSignatures
- simpleLenses :: Lens' LensRules Bool
- partialLenses :: Lens' LensRules Bool
- buildTraversals :: Lens' LensRules Bool
- handleSingletons :: Lens' LensRules Bool
- singletonIso :: Lens' LensRules Bool
- singletonRequired :: Lens' LensRules Bool
- createClass :: Lens' LensRules Bool
- createInstance :: Lens' LensRules Bool
- classRequired :: Lens' LensRules Bool
- singletonAndField :: Lens' LensRules Bool
- generateSignatures :: Lens' LensRules Bool

# Constructing Lenses Automatically

makeLenses :: Name -> Q [Dec]

Build lenses (and traversals) with a sensible default configuration.

     makeLenses = makeLensesWith lensRules

makeLensesFor :: [(String, String)] -> Name -> Q [Dec]

Derive lenses and traversals, specifying explicit pairings of `(fieldName, lensName)`.

If you map multiple names to the same label, and it is present in the same constructor then this will generate a `Traversal`.

e.g.

     makeLensesFor [("_foo", "fooLens"), ("baz", "lbaz")] ''Foo
     makeLensesFor [("_barX", "bar"), ("_barY", "bar")] ''Bar

makeClassy :: Name -> Q [Dec]

Make lenses and traversals for a type, and create a class when the type has no arguments.

e.g.

     data Foo = Foo { _fooX, _fooY :: Int }
     makeClassy ''Foo

will create

     class HasFoo t where
       foo :: Simple Lens t Foo
     instance HasFoo Foo where foo = id
     fooX, fooY :: HasFoo t => Simple Lens t Int

     makeClassy = makeLensesWith classyRules

makeClassyFor :: String -> String -> [(String, String)] -> Name -> Q [Dec]

Derive lenses and traversals, using a named wrapper class, and specifying explicit pairings of `(fieldName, traversalName)`.

Example usage:

     makeClassyFor "HasFoo" "foo" [("_foo", "fooLens"), ("bar", "lbar")] ''Foo

makeIso :: Name -> Q [Dec]

Make a top level isomorphism injecting into the type.

The supplied name is required to be for a type with a single constructor that has a single argument.

e.g.

     newtype List a = List [a]
     makeIso ''List

will create

     list :: Iso [a] [b] (List a) (List b)

     makeIso = makeLensesWith isoRules

makePrisms :: Name -> Q [Dec]

Generate a `Prism` for each constructor of a data type.

makeWrapped :: Name -> DecsQ

Build `Wrapped` instance for a given newtype

makeFields :: Name -> Q [Dec]

     makeFields = makeFieldsWith defaultFieldRules

# Configuring Lenses

makeLensesWith :: LensRules -> Name -> Q [Dec]

Build lenses with a custom configuration.

makeFieldsWith :: FieldRules -> Name -> Q [Dec]

Make fields with the specified `FieldRules`.

defaultRules :: LensRules

Default `LensRules`.

defaultFieldRules :: FieldRules

     defaultFieldRules = camelCaseFields

camelCaseFields :: FieldRules

Field rules for fields in the form `prefixFieldname`

underscoreFields :: FieldRules

Field rules for fields in the form `_prefix_fieldname`

data LensRules

This configuration describes the options we'll be using to make isomorphisms or lenses.

Constructors

LensRules (String -> Maybe String) (String -> Maybe String) (String -> Maybe (String, String)) (Set LensFlag) |

data FieldRules

Constructors

FieldRules (String -> Maybe String) (String -> String) (String -> Maybe String) (String -> Maybe String) |

lensRules :: LensRules

Rules for making fairly simple partial lenses, ignoring the special cases for isomorphisms and traversals, and not making any classes.

classyRules :: LensRules

Rules for making lenses and traversals that precompose another `Lens`.

isoRules :: LensRules

Rules for making an isomorphism from a data type.

lensIso :: Lens' LensRules (String -> Maybe String)

`Lens'` to access the convention for naming top level isomorphisms in our `LensRules`.

Defaults to lowercasing the first letter of the constructor.

lensField :: Lens' LensRules (String -> Maybe String)

`Lens'` to access the convention for naming fields in our `LensRules`.

Defaults to stripping the _ off of the field name, lowercasing the name, and rejecting the field if it doesn't start with an '_'.

lensClass :: Lens' LensRules (String -> Maybe (String, String))

Retrieve options such as the name of the class and method to put in it to build a class around monomorphic data types.

lensFlags :: Lens' LensRules (Set LensFlag)

Retrieve options such as the name of the class and method to put in it to build a class around monomorphic data types.

data LensFlag

Flags for `Lens` construction

Constructors

SimpleLenses |
PartialLenses |
BuildTraversals |
SingletonAndField |
SingletonIso |
HandleSingletons |
SingletonRequired |
CreateClass |
CreateInstance |
ClassRequired |
GenerateSignatures |

Instances

Eq LensFlag |
Ord LensFlag |
Read LensFlag |
Show LensFlag |

simpleLenses :: Lens' LensRules Bool

Only Generate valid `Simple` lenses.

partialLenses :: Lens' LensRules Bool

Enables the generation of partial lenses, generating runtime errors for every constructor that does not have a valid definition for the `Lens`. This occurs when the constructor lacks the field, or has multiple fields mapped to the same `Lens`.

buildTraversals :: Lens' LensRules Bool

In the situations that a `Lens` would be partial, when `partialLenses` is used, this flag instead causes traversals to be generated. Only one can be used, and if neither are, then compile-time errors are generated.

handleSingletons :: Lens' LensRules Bool

Handle singleton constructors specially.

singletonIso :: Lens' LensRules Bool

Use `Iso` for singleton constructors.

singletonRequired :: Lens' LensRules Bool

Expect a single constructor, single field newtype or data type.

createClass :: Lens' LensRules Bool

Create the class if the constructor is `Simple` and the `lensClass` rule matches.

createInstance :: Lens' LensRules Bool

Create the instance if the constructor is `Simple` and the `lensClass` rule matches.

classRequired :: Lens' LensRules Bool

Die if the `lensClass` fails to match.

singletonAndField :: Lens' LensRules Bool

When building a singleton `Iso` (or `Lens`) for a record constructor, build both the `Iso` (or `Lens`) for the record and the one for the field.

generateSignatures :: Lens' LensRules Bool

Indicate whether or not to supply the signatures for the generated lenses.

Disabling this can be useful if you want to provide a more restricted type signature or if you want to supply hand-written haddocks.