HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

  • Packageoptics-th-0.4.1
  • Exports58
  • LanguageHaskell2010
  • LicenceBSD-3-Clause
  • SourceTH.hs

Generation of field optics

0 declarations

Labels

valuemakeFieldLabels :: Name -> DecsQ
#

Build field optics as instances of the LabelOptic class for use with overloaded labels. See Optics.Label for how to use this pattern.

e.g.

data Animal
  = Cat { animalAge  :: Int
        , animalName :: String
        }
  | Dog { animalAge    :: Int
        , animalAbsurd :: forall a b. a -> b
        }
makeFieldLabels ''Animal

will create

instance
  (k ~ A_Lens, a ~ Int, b ~ Int
  ) => LabelOptic "age" k Animal Animal a b where
  labelOptic = lensVL $ \f s -> case s of
    Cat x1 x2 -> fmap (\y -> Cat y x2) (f x1)
    Dog x1 x2 -> fmap (\y -> Dog y x2) (f x1)

instance
  (k ~ An_AffineTraversal, a ~ String, b ~ String
  ) => LabelOptic "name" k Animal Animal a b where
  labelOptic = atraversalVL $ \point f s -> case s of
    Cat x1 x2 -> fmap (\y -> Cat x1 y) (f x2)
    Dog x1 x2 -> point (Dog x1 x2)

instance
  ( Dysfunctional "absurd" k Animal Animal a b
  , k ~ An_AffineFold, a ~ (x -> y), b ~ (x -> y)
  ) => LabelOptic "absurd" k Animal Animal a b where
  labelOptic = afolding $ \s -> case s of
    Cat _ _  -> Nothing
    Dog _ f  -> Just f

which can be used as #age, #name and #absurd with the OverloadedLabels language extension.

Note: if you wonder about the structure of instances, see Optics.Label#structure.

makeFieldOptics = makeFieldLabelsWith fieldLabelsRules

Make field optics as labels for all records in the given declaration quote. All record syntax in the input will be stripped off.

e.g.

declareLenses [d|
  data Dog = Dog { name :: String, age :: Int }
    deriving Show
  |]

will create

data Dog = Dog String Int
  deriving Show
instance (k ~ A_Lens, ...) => LabelOptic "name" k Dog Dog ...
instance (k ~ A_Lens, ...) => LabelOptic "age" k Dog Dog ...

Functions

valuemakeLenses :: Name -> DecsQ
#

Build field optics as top level functions with a sensible default configuration.

e.g.

data Animal
  = Cat { _age  :: Int
        , _name :: String
        }
  | Dog { _age    :: Int
        , _absurd :: forall a b. a -> b
        }
makeLenses ''Animal

will create

absurd :: forall a b. AffineFold Animal (a -> b)
absurd = afolding $ \s -> case s of
  Cat _ _ -> Nothing
  Dog _ x -> Just x

age :: Lens' Animal Int
age = lensVL $ \f s -> case s of
  Cat x1 x2 -> fmap (\y -> Cat y x2) (f x1)
  Dog x1 x2 -> fmap (\y -> Dog y x2) (f x1)

name :: AffineTraversal' Animal String
name = atraversalVL $ \point f s -> case s of
  Cat x1 x2 -> fmap (\y -> Cat x1 y) (f x2)
  Dog x1 x2 -> point (Dog x1 x2)
makeLenses = makeLensesWith lensRules
valuemakeLensesFor :: [(String, String)] -> Name -> DecsQ
#

Derive field optics, specifying explicit pairings of (fieldName, opticName).

If you map multiple fields to the same optic and it is present in the same constructor, Traversal (or Fold for a read only version) will be generated.

e.g.

makeLensesFor [("_foo", "fooLens"), ("baz", "lbaz")] ''Foo
makeLensesFor [("_barX", "bar"), ("_barY", "bar")] ''Bar
valuedeclareLenses :: DecsQ -> DecsQ
#

Make field optics for all records in the given declaration quote. All record syntax in the input will be stripped off.

e.g.

declareLenses [d|
  data Foo = Foo { fooX, fooY :: Int }
    deriving Show
  |]

will create

data Foo = Foo Int Int deriving Show
fooX, fooY :: Lens' Foo Int

Single class per data type

This method of optics generation should only be used when migrating an existing codebase from the lens library to optics as it:

  • Doesn't support prefixless fields.

  • Doesn't support type changing updates.

See Optics.Label for our recommended pattern.

valuemakeClassy :: Name -> DecsQ
#

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 c where
  foo  :: Lens' c Foo
  fooX :: Lens' c Int
  fooY :: Lens' c Int
  fooX = foo % fooX
  fooY = foo % fooY

instance HasFoo Foo where
  foo  = lensVL id
  fooX = lensVL $ \f s -> case s of
    Foo x1 x2 -> fmap (\y -> Foo y x2) (f x1)
  fooY = lensVL $ \f s -> case s of
    Foo x1 x2 -> fmap (\y -> Foo x1 y) (f x2)
makeClassy = makeLensesWith classyRules
valuemakeClassy_ :: Name -> DecsQ
#

Make lenses and traversals for a type, and create a class when the type has no arguments. Works the same as makeClassy except that (a) it expects that record field names do not begin with an underscore, (b) all record fields are made into lenses, and (c) the resulting lens is prefixed with an underscore.

valuedeclareClassy :: DecsQ -> DecsQ
#

For each record in the declaration quote, make lenses and traversals for it, and create a class when the type has no arguments. All record syntax in the input will be stripped off.

e.g.

declareClassy [d|
  data Foo = Foo { fooX, fooY :: Int }
    deriving Show
  |]

will create

data Foo = Foo Int Int deriving Show
class HasFoo t where
  foo :: Lens' t Foo
instance HasFoo Foo where foo = id
fooX, fooY :: HasFoo t => Lens' t Int
valueclassyRulesFor
  1. :: (String -> Maybe (String, String))

    Type Name -> Maybe (Class Name, Method Name)

  2. -> [(String, String)]
    (Field Name, Method Name)
  3. -> LensRules
#

Rules for making lenses and traversals that precompose another Lens using a custom function for naming the class, main class method, and a mapping from field names to definition names.

Multiple classes per data type

This method of optics generation should only be used when migrating an existing codebase from the lens library to optics as it:

  • Doesn't support type changing updates.

  • Introduces tight coupling between types in your application as either all types need to be put in a single module (for HasX class generation to work properly) or there needs to be a single, written by hand module with all the HasX classes the application will use. Both approaches don't scale.

  • Can't be leveraged by libraries because of the above problem lifted to the library level: there would have to exist a library with all possible HasX classes written by hand that is imported by all the other libraries. Otherwise for a given field independent libraries would provide multiple HasField classes incompatible with each other.

See Optics.Label for our recommended pattern.

valuemakeFields :: Name -> DecsQ
#

Generate overloaded field accessors.

e.g

data Foo a = Foo { _fooX :: Int, _fooY :: a }
newtype Bar = Bar { _barX :: Char }
makeFields ''Foo
makeFields ''Bar

will create

class HasX s a | s -> a where
  x :: Lens' s a

instance HasX (Foo a) Int where
  x = lensVL $ \f s -> case s of
    Foo x1 x2 -> fmap (\y -> Foo y x2) (f x1)

class HasY s a | s -> a where
  y :: Lens' s a

instance HasY (Foo a) a where
  y = lensVL $ \f s -> case s of
    Foo x1 x2 -> fmap (\y -> Foo x1 y) (f x2)

instance HasX Bar Char where
  x = lensVL $ \f s -> case s of
    Bar x1 -> fmap (\y -> Bar y) (f x1)

For details, see camelCaseFields.

makeFields = makeLensesWith defaultFieldRules

Generate overloaded field accessors based on field names which are only prefixed with an underscore (e.g. _name), not additionally with the type name (e.g. _fooName).

This might be the desired behaviour in case the DuplicateRecordFields language extension is used in order to get rid of the necessity to prefix each field name with the type name.

As an example:

data Foo a  = Foo { _x :: Int, _y :: a }
newtype Bar = Bar { _x :: Char }
makeFieldsNoPrefix ''Foo
makeFieldsNoPrefix ''Bar

will create classes

class HasX s a | s -> a where
  x :: Lens' s a
class HasY s a | s -> a where
  y :: Lens' s a

together with instances

instance HasX (Foo a) Int
instance HasY (Foo a) a where
instance HasX Bar Char where

For details, see classUnderscoreNoPrefixFields.

makeFieldsNoPrefix = makeLensesWith classUnderscoreNoPrefixFields

Generation of constructor optics

0 declarations

Labels

Functions

valuemakePrisms
  1. :: Name

    Type constructor name

  2. -> DecsQ
#

Generate a Prism for each constructor of a data type. Isos generated when possible. Reviews are created for constructors with existentially quantified constructors and GADTs.

e.g.

data FooBarBaz a
  = Foo Int
  | Bar a
  | Baz Int Char
makePrisms ''FooBarBaz

will create

_Foo :: Prism' (FooBarBaz a) Int
_Bar :: Prism (FooBarBaz a) (FooBarBaz b) a b
_Baz :: Prism' (FooBarBaz a) (Int, Char)
valuedeclarePrisms :: DecsQ -> DecsQ
#

Generate a Prism for each constructor of each data type.

e.g.

declarePrisms [d|
  data Exp = Lit Int | Var String | Lambda{ bound::String, body::Exp }
  |]

will create

data Exp = Lit Int | Var String | Lambda { bound::String, body::Exp }
_Lit :: Prism' Exp Int
_Var :: Prism' Exp String
_Lambda :: Prism' Exp (String, Exp)

Single class per data type

valuemakeClassyPrisms
  1. :: Name

    Type constructor name

  2. -> DecsQ
#

Generate a Prism for each constructor of a data type and combine them into a single class. No Isos are created. Reviews are created for constructors with existentially quantified constructors and GADTs.

e.g.

data FooBarBaz a
  = Foo Int
  | Bar a
  | Baz Int Char
makeClassyPrisms ''FooBarBaz

will create

class AsFooBarBaz s a | s -> a where
  _FooBarBaz :: Prism' s (FooBarBaz a)
  _Foo :: Prism' s Int
  _Bar :: Prism' s a
  _Baz :: Prism' s (Int,Char)

  _Foo = _FooBarBaz % _Foo
  _Bar = _FooBarBaz % _Bar
  _Baz = _FooBarBaz % _Baz

instance AsFooBarBaz (FooBarBaz a) a

Generate an As class of prisms. Names are selected by prefixing the constructor name with an underscore. Constructors with multiple fields will construct Prisms to tuples of those fields.

Generation rules for field optics

8 declarations
datadata LensRules
#

Rules to construct lenses for data fields.

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.

Generate "updateable" optics when True. When False, (affine) folds will be generated instead of (affine) traversals and getters will be generated instead of lenses. This mode is intended to be used for types with invariants which must be maintained by "smart" constructors.

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}
  deriving Show

makeLensesWith (lensRules & generateLazyPatterns .~ True) ''Foo
> undefined & x .~ 8 & y .~ True
Foo {_x = 8, _y = True}

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 using lazy optics the strict optic can be recovered by composing with equality':

strictOptic = equality' % lazyOptic

Common rules

6 declarations

Field rules for fields without any prefix. Useful for generation of field labels when paired with DuplicateRecordFields language extension so that no prefixes for field names are necessary.

Field rules for fields in the form prefixFieldname or _prefixFieldname

If you want all fields to be lensed, then there is no reason to use an _ before the prefix. If any of the record fields leads with an _ then it is assume a field without an _ should not have a lens created.

Note: The prefix must be the same as the typename (with the first letter lowercased). This is a change from lens versions before lens 4.5. If you want the old behaviour, use makeLensesWith abbreviatedFields

Field rules for fields in the form _fieldname (the leading underscore is mandatory).

Note: The primary difference to camelCaseFields is that for classUnderscoreNoPrefixFields the field names are not expected to be prefixed with the type name. This might be the desired behaviour when the DuplicateRecordFields extension is enabled.

Field rules fields in the form prefixFieldname or _prefixFieldname If you want all fields to be lensed, then there is no reason to use an _ before the prefix. If any of the record fields leads with an _ then it is assume a field without an _ should not have a lens created.

Note that prefix may be any string of characters that are not uppercase letters. (In particular, it may be arbitrary string of lowercase letters and numbers) This is the behavior that defaultFieldRules had in lens 4.4 and earlier.

Field namers

11 declarations
typetype FieldNamer = Name -> [Name] -> Name -> [DefName]
#

The rule to create function names of lenses for data fields.

Although it's sometimes useful, you won't need the first two arguments most of the time.

typetype ClassyNamer = Name -> Maybe (Name, Name)
#

The optional rule to create a class and method around a monomorphic data type. If this naming convention is provided, it generates a "classy" lens.

datadata DefName
#

Name to give to generated field optics.

Constructors

Instances3Eq, Ord, Show
  • Eq DefNameDefined in optics-th-0.4.1 · Optics.TH.Internal.Product
  • Ord DefNameDefined in optics-th-0.4.1 · Optics.TH.Internal.Product
  • Show DefNameDefined in optics-th-0.4.1 · Optics.TH.Internal.Product

A FieldNamer that leaves the field name as-is. Useful for generation of field labels when paired with DuplicateRecordFields language extension so that no prefixes for field names are necessary.