Name:            fclabels
Version:         0.11.1.1
Author:          Sebastiaan Visser, Erik Hesselink, Chris Eidhof, Sjoerd Visscher.
Synopsis:        First class accessor labels implemented as lenses.

Description:     First class labels that act as bidirectional record fields.
                 .
                 The labels are implemented as lenses and are fully composable
                 and can be used to get, set and modify parts of a datatype in
                 a consistent way. The lens datatype, conveniently called
                 `:->', is an instance of the `Category' type class: meaning it
                 has a proper identity and composition. The library has support
                 for automatically deriving labels from record selectors that
                 start with an underscore. Labels can be used in a purely
                 functional setting or be applied to mutable state in some
                 state monad.
                 .
                 To illustrate this package, let's take the following two example
                 datatypes (somehow Haddock removes the curly braces):
                 .
                 > data Person = Person {
                 >     _name   :: String
                 >   , _age    :: Int
                 >   , _isMale :: Bool
                 >   , _place  :: Place
                 >   }
                 .
                 > data Place = Place {
                 >     _city
                 >   , _country
                 >   , _continent :: String
                 >   }
                 .
                 Both are record datatypes with all record labels prefixed by
                 an underscore.  This underscore is an indication for our
                 Template Haskell code to derive lenses for these fields.
                 Deriving lenses can be done with this simple one-liner:
                 .
                 > $(mkLabels [''Person, ''Place])
                 .
                 These lenses can be used to get, set and modify the value and
                 are fully composable.
                 .
                 Now let's look at this example. This 71 year old fellow, called Jan,
                 is my neighbour and didn't mind using him as an example:
                 .
                 > jan :: Person
                 > jan = Person "Jan" 71 True (Place "Utrecht" "The Netherlands" "Europe")
                 .
                 When we want to be sure Jan is really as old as he claims we
                 can use the @getL@ function to get the age out as an integer:
                 .
                 > hisAge :: Int
                 > hisAge = getL age jan
                 .
                 Consider he now wants to move to Amsterdam: what better place
                 to spend your old days. Using composition we can change the
                 city value deep inside the structure:
                 .
                 > moveToAmsterdam :: Person -> Person
                 > moveToAmsterdam = setL (city . place) "Amsterdam"
                 .
                 > moveToAmsterdam jan ==
                 >  Person "Jan" 71 True (Place "Amsterdam" "The Netherlands" "Europe")
                 .
                 Composition is done using the dot operator which is part of
                 the @Control.Category@ module. Make sure to import this module
                 and hide the default @(.)@, @id@ and @modL@ function from the
                 Prelude.
                 .
                 Now, because Jan is an old guy, moving to another city is not a
                 very easy task, this really takes a while. It will probably
                 take no less than two years before he will actually be
                 settled. To reflect this change it might be useful to have a
                 first class view on the @Person@ data type that only reveals
                 the age and city.  This can be done by using a neat
                 @Applicative@ functor instance:
                 .
                 > ageAndCity :: Person :-> (Int, String)
                 > ageAndCity = Lens $ (,) <$> fst `for` age <*> snd `for` (city . place)
                 .
                 Because the applicative type class on its own is not very
                 capable of expressing bidirectional relations, which we need
                 for our lenses, the actual instance is defined for an internal
                 helper structure called @Point@. Points are a bit more general
                 than lenses. As you can see above, the @Label@ constructor has
                 to be used to convert a @Point@ back into a @Label@. The @for@
                 function must be used to indicate which partial destructor to
                 use for which lens in the applicative composition.
                 .
                 Now that we have an appropriate age+city view on the @Person@
                 data type (which is itself a lens again), we can use the
                 @modL@ function to make Jan move to Amsterdam over exactly two
                 years:
                 .
                 > moveToAmsterdamOverTwoYears :: Person -> Person
                 > moveToAmsterdamOverTwoYears = modL ageAndCity (\(a, b) -> (a+2, "Amsterdam"))
                 .
                 > moveToAmsterdamOverTwoYears jan ==
                 >  Person "Jan" 73 True (Place "Amsterdam" "The Netherlands" "Europe")
                 .
                 This package also contains a lens data type that encodes
                 bidirectional functions. Just like lenses, lenses can be
                 composed with other lenses using the @Control.Category@ type
                 class. Lenses can be used to change the type of a lens. The
                 @Iso@ type class, which can be seen as a bidirectional
                 functor, can be used to apply lenses to lenses. For example,
                 when we want to treat the age of a person as a string we can
                 do the following:
                 .
                 > ageAsString :: Person :-> String
                 > ageAsString :: (show :<->: read) % age
                 .
                 A final note: this library might look cryptic at first sight, but give it a
                 try, it is not that hard.
                 .
                 .
                 > CHANGELOG
                 >   0.11.1 -> 0.11.1.1
                 >   - Improved TH support for multiple constructor datatypes.

Maintainer:      Sebastiaan Visser <haskell@fvisser.nl>
License:         BSD3
License-File:    LICENCE
Category:        Data
Cabal-Version:   >= 1.6
Build-Type:      Simple

Library
  HS-Source-Dirs:  src
  Exposed-Modules: Data.Record.Label
                   Data.Record.Label.Core
                   Data.Record.Label.Monadic
  Other-Modules:   Data.Record.Label.TH
  Build-Depends:   base >= 3 && < 5
                 , template-haskell >= 2.2 && < 2.6
                 , mtl >= 1.1 && <= 2.1
  GHC-Options:     -Wall