fclabels-0.4.2: fclabels.cabal
Name: fclabels
Version: 0.4.2
Author: Sebastiaan Visser, Erik Hesselink, Chris Eidhof, Sjoerd Visscher.
Synopsis: First class accessor labels.
Description: First class labels that act as bidirectional record fields.
The labels are fully composable and can be used to get, set
and modify parts of a datatype in a consistent way. The label
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 take the following two example
datatypes (somehow Haddock removes the 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 with
an underscore. This underscore is an indication for our
Template Haskell code to derive labels for these fields.
Deriving labels can be done with this simple one-liner:
.
> $(mkLabels [''Person, ''Place])
.
Label function will be generated, label type signatures will
not. This is actually not that bad, by writing the signatures
down yourself you will be able to give them documentation,
something that would be hard otherwise. So, lets give
functions a signature by hand:
.
> name :: Person :-> String
> age :: Person :-> Int
> isMale :: Person :-> Bool
> place :: Person :-> Place
> city :: Place :-> String
> country :: Place :-> String
> continent :: Place :-> String
.
These type signatures look very similar to the function types
for normal record labels, except that the additional colon
indicates a true first class label. These labels can be used
to get, set and modify the value and are fully composable.
.
Now let look at this example. This 71 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 @get@ function for labels to get the age out as an
integer:
.
> hisAge :: Int
> hisAge = get age jan
.
Consider he now wants to move to Amsterdam, what better place
to spend your old days. Using composition when can change the
city value deep inside the structure:
.
> moveToAmsterdam :: Person -> Person
> moveToAmsterdam = set (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 @mod@ 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. So 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 = Label $ (,) <$> 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 labels, the actual instance is defined for an internal
helper structure called @Point@. Points are a bit more general
than labels. 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 label in the applicative composition.
.
Now that we have an appropriate age+city view on the @Person@
data type (which is itself a label again), we can use the
@mod@ function to make Jan move to Amsterdam over exactly two
years:
.
> moveToAmsterdamOverTwoYears :: Person -> Person
> moveToAmsterdamOverTwoYears = mod 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 labels lenses can be
composed to other lenses using the @Control.Category@ type
class. Lenses can be used to change the type of a label. The
@Iso@ type class, which can be seen as a bidirectional
functor, can be used to apply lenses to labels. For example,
when we want to threat the age of a person as a string we can
do the following:
.
> ageAsString :: Person :-> String
> ageAsString :: (show <-> read) `iso` age
.
This library might look cryptic at first sight, but give it a
try it is not that hard.
Maintainer: Sebastiaan Visser <sfvisser@cs.uu.nl>
License: BSD3
License-File: LICENCE
Category: Data
Build-Type: Simple
Cabal-Version: >= 1.6
HS-Source-Dirs: src
Exposed-Modules: Data.Record.Label
Other-Modules: Data.Record.Label.TH
Build-Depends: base >= 3 && < 5, template-haskell >= 2.2 && < 2.5, monads-fd ==0.0.*