The first decision to make when migrating a project is which Stackage snapshot to pick. It had been a while since I last updated my project, and building it with the latest versions of all its dependencies would require a few adjustments. That being so, I chose to migrate to stack before any further patches. Since one of the main dependencies was `diagrams`

1.2, I went for `lts-2.19`

, the most recent LTS snapshot with that version of `diagrams`

^{1}.

`$ stack init --resolver lts-2.19`

`stack init`

creates a `stack.yaml`

file based on an existing cabal file in the current directory. The `--resolver`

option can be used to pick a specific snapshot.

One complicating factor in the conversion to stack was that two of the extra dependencies, `threepenny-gui-0.5.0.0`

(one major version behind the current one) and `zip-conduit`

, wouldn’t build with the LTS snapshot plus current Hackage without version bumps in their cabal files. Fortunately, stack deals very well with situations like this, in which minor changes to some dependency are needed. I simply forked the dependencies on GitHub, pushed the version bumps to my forks and referenced the commits in the *remote* GitHub repository in `stack.yaml`

. A typical entry for a Git commit in the `packages`

section looks like this:

```
- location:
git: https://github.com/duplode/zip-conduit
commit: 1eefc8bd91d5f38b760bce1fb8dd16d6e05a671d
extra-dep: true
```

Keeping customised dependencies in public remote repositories is an excellent solution. It enables users to build the package without further intervention without requiring developers to clumsily bundle the source tree of the dependencies with the project, or waiting for a pull request to be accepted upstream and reach Hackage.

With the two tricky extra dependencies being offloaded to Git repositories, the next step was using `stack solver`

to figure out the rest of them:

```
$ stack solver --modify-stack-yaml
This command is not guaranteed to give you a perfect build plan
It's possible that even with the changes generated below, you will still
need to do some manual tweaking
Asking cabal to calculate a build plan, please wait
extra-deps:
- parsec-permutation-0.1.2.0
- websockets-snap-0.9.2.0
Updated /home/duplode/Development/stunts/diagrams/stack.yaml
```

Here is the final `stack.yaml`

:

```
flags:
stunts-cartography:
repldump2carto: true
packages:
- '.'
- location:
git: https://github.com/duplode/zip-conduit
commit: 1eefc8bd91d5f38b760bce1fb8dd16d6e05a671d
extra-dep: true
- location:
git: https://github.com/duplode/threepenny-gui
commit: 2dd88e893f09e8e31378f542a9cd253cc009a2c5
extra-dep: true
extra-deps:
- parsec-permutation-0.1.2.0
- websockets-snap-0.9.2.0
resolver: lts-2.19
```

`repldump2carto`

is a flag defined in the cabal file. It is used to build a secondary executable. Beyond demonstrating how the `flags`

section of `stack.yaml`

works, I added it because `stack ghci`

expects all possible build targets to have been built ^{2}.

As I have GHC 7.10.1 from my Linux distribution and the LTS 2.19 snapshot is made for GHC 7.8.4, I needed `stack setup`

as an additional step. That command locally installs (in `~/.stack`

) the GHC version required by the chosen snapshot.

That pretty much concludes the migration. All that is left is demonstrating: `stack build`

to compile the project…

```
$ stack build
JuicyPixels-3.2.5.2: configure
Boolean-0.2.3: download
# etc. (Note how deps from Git are handled seamlessly.)
threepenny-gui-0.5.0.0: configure
threepenny-gui-0.5.0.0: build
threepenny-gui-0.5.0.0: install
zip-conduit-0.2.2.2: configure
zip-conduit-0.2.2.2: build
zip-conduit-0.2.2.2: install
# etc.
stunts-cartography-0.4.0.3: configure
stunts-cartography-0.4.0.3: build
stunts-cartography-0.4.0.3: install
Completed all 64 actions.
```

… `stack ghci`

to play with it in GHCi…

```
$ stack ghci
Configuring GHCi with the following packages: stunts-cartography
GHCi, version 7.8.4: http://www.haskell.org/ghc/ :? for help
Loading package ghc-prim ... linking ... done.
Loading package integer-gmp ... linking ... done.
Loading package base ... linking ... done.
-- etc.
Ok, modules loaded: GameState, Annotation, Types.Diagrams, Pics,
Pics.MM, Annotation.Flipbook, Annotation.LapTrace,
Annotation.LapTrace.Vec, Annotation.LapTrace.Parser.Simple,
Annotation.Parser, Types.CartoM, Parameters, Composition, Track,
Util.Misc, Pics.Palette, Output, Util.ByteString, Util.ZipConduit,
Replay, Paths, Util.Reactive.Threepenny, Util.Threepenny.Alertify,
Widgets.BoundedInput.
*GameState> :l src/Viewer.hs -- The Main module.
-- etc.
*Main> :main
Welcome to Stunts Cartography.
Open your web browser and navigate to localhost:10000 to begin.
Listening on http://127.0.0.1:10000/
[27/Jul/2015:00:55:11 -0300] Server.httpServe: START, binding to
[http://127.0.0.1:10000/]
```

… and looking at the build output in the depths of `.stack-work`

:

```
$ .stack-work/dist/x86_64-linux/Cabal-1.18.1.5/build/sc-trk-viewer/sc-trk-viewer
Welcome to Stunts Cartography 0.4.0.3.
Open your web browser and navigate to localhost:10000 to begin.
Listening on http://127.0.0.1:10000/
[26/Jul/2015:20:02:54 -0300] Server.httpServe: START, binding to
[http://127.0.0.1:10000/]
```

With the upcoming stack 0.2 it will be possible to use `stack build --copy-bins --local-bin-path <path>`

to copy any executables built as part of the project to a path. If the `--local-bin-path`

option is omitted, the default is `~/.local/bin`

. (In fact, you can already copy executables to `~/.local/bin`

with stack 0.1.2 through `stack install`

. However, I don’t want to overemphasise that command, as `stack install`

not being equivalent to `cabal install`

can cause some confusion.)

Hopefully this report will give you an idea of what to expect when migrating your projects to stack. Some details may appear a little strange, given how familiar cabal-install workflows are, and some features are still being shaped. All in all, however, stack works very well already: it definitely makes setting up reliable builds easier. The stack repository at GitHub, and specially the wiki therein, offers lots of helpful information, in case you need further details and usage tips.

As a broader point, it just seems polite to, when possible, pick a LTS snapshot over than a nightly for a public project. It is more likely that those interested in building your project already have a specific LTS rather than an arbitrary nightly.↩

That being so, a more natural arrangement would be treating

`repldump2carto`

as a full-blown subproject by giving it its own cabal file and adding it to the`packages`

section. I would then be able to load only the main project in GHCi with`stack ghci stunts-cartography`

.↩

Post licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

I won’t dwell on the motivation and philosophy behind stack ^{1}. Suffice it to say that, at least in the less exotic workflows, there is a centralised package database somewhere in `~/.stack`

with packages pulled from a Stackage snapshot (and therefore known to be compatible with each other), which is supplemented by a per-project database (that is, just like cabal sandboxes) for packages not in Stackage (from Hackage or anywhere else). As that sounds like a great way to avoid headaches, we will stick to this arrangement, with only minor adjustments.

Once you have installed stack ^{2}, you can create a new environment for experiments with `stack new`

:

```
$ mkdir -p Development/haskell/playground
$ cd Development/haskell/playground
$ stack new --prefer-nightly
```

The `--prefer-nightly`

option makes stack use a nightly snapshot of Stackage, as opposed to a long term support one. As we are just playing around, it makes sense to pick as recent as possible packages from the nightly instead of the LTS. (Moreover, I use Arch Linux, which already has GHC 7.10 and `base`

4.8, while the current LTS snapshot assumes `base`

4.7.) If this is the first time you use stack, it will pick the latest nightly; otherwise it will default to whatever nightly you already have in `~/.stack`

.

`stack new`

creates a neat default project structure for you ^{3}:

```
$ ls -R
.:
app LICENSE new-template.cabal Setup.hs src stack.yaml test
./app:
Main.hs
./src:
Lib.hs
./test:
Spec.hs
```

Of particular interest is the `stack.yaml`

file, which holds the settings for the local stack environment. We will talk more about it soon.

```
flags: {}
packages:
- '.'
extra-deps: []
resolver: nightly-2015-07-19
```

As for the default `new-template.cabal`

file, you can use its `build-depends`

section to keep track of what you are installing. That will make `stack build`

(the command which builds the current project without installing it) to download and install any dependencies you add to the cabal file automatically. Besides that, having the installed packages noted down may prove useful in case you need to reproduce your configuration elsewhere ^{4}. If your experiments become a real project, you can clean up the `build-depends`

without losing track of the packages you installed for testing purposes by moving their entries to a second cabal file, kept in a subdirectory:

```
$ mkdir xp
$ cp new-template.cabal xp/xp.cabal
$ cp LICENSE xp # Too lazy to delete the lines from the cabal file.
$ cd xp
$ vi Dummy.hs # module Dummy where <END OF FILE>
$ vi xp.cabal # Adjust accordingly, and list your extra deps.
```

You also need to tell stack about this fake subproject. All it takes is adding an entry for the subdirectory in `stack.yaml`

:

```
packages:
- '.' # The default entry.
- 'xp'
```

With the initial setup done, we use `stack build`

to compile the projects:

```
$ stack build
new-template-0.1.0.0: configure
new-template-0.1.0.0: build
fmlist-0.9: download
fmlist-0.9: configure
fmlist-0.9: build
new-template-0.1.0.0: install
fmlist-0.9: install
xp-0.1.0.0: configure
xp-0.1.0.0: build
xp-0.1.0.0: install
Completed all 3 actions.
```

In this test run, I added `fmlist`

as a dependency of the fake package `xp`

, and so it was automatically installed by stack. The output of `stack build`

goes to a `.stack-work`

subdirectory.

With the packages built, we can use GHCi in the stack environment with `stack ghci`

. It loads the library source files of the current project by default:

```
$ stack ghci
Configuring GHCi with the following packages: new-template, xp
GHCi, version 7.10.1: http://www.haskell.org/ghc/ :? for help
[1 of 2] Compiling Lib (
/home/duplode/Development/haskell/playground/src/Lib.hs, interpreted )
[2 of 2] Compiling Dummy (
/home/duplode/Development/haskell/playground/xp/Dummy.hs, interpreted )
Ok, modules loaded: Dummy, Lib.
*Lib> import qualified Data.FMList as F -- Which we have just installed.
*Lib F> -- We can also load executables specified in the cabal file.
*Lib F> :l Main
[1 of 2] Compiling Lib (
/home/duplode/Development/haskell/playground/src/Lib.hs, interpreted )
[2 of 2] Compiling Main (
/home/duplode/Development/haskell/playground/app/Main.hs, interpreted )
Ok, modules loaded: Lib, Main.
*Main F>
```

Dependencies not in Stackage have to be specified in `stack.yaml`

as well as in the cabal files, so that stack can manage them too. Alternative sources of packages include source trees in subdirectories of the project, Hackage and remote Git repositories ^{5}:

```
flags: {}
packages:
- '.'
- 'xp'
- location: deps/acme-missiles-0.3 # Sources in a subdirectory.
extra-dep: true # Mark as dep, i.e. not part of the project proper.
extra-deps:
- acme-safe-0.1.0.0 # From Hackage.
- acme-dont-1.1 # Also from Hackage, dependency of acme-safe.
resolver: nightly-2015-07-19
```

`stack build`

will then install the extra dependencies to `.stack-work/install`

. You can use `stack solver`

to chase the indirect dependencies introduced by them. For instance, this is its output after commenting the `acme-dont`

line in the `stack.yaml`

just above:

```
$ stack solver --no-modify-stack-yaml
This command is not guaranteed to give you a perfect build plan
It's possible that even with the changes generated below, you will still
need to do some manual tweaking
Asking cabal to calculate a build plan, please wait
extra-deps:
- acme-dont-1.1
```

To conclude this tour, once you get bored of the initial Stackage snapshot all it takes to switch it is changing the `resolver`

field in `stack.yaml`

(with nightlies, that amounts to changing the date at the end of the snapshot name). That will cause all dependencies to be downloaded and built from the chosen snapshot when `stack build`

is next ran. As of now, the previous snapshot will remain in `~/.stack`

unless you go there and delete it manually; however, a command for removing unused snapshots is in the plans.

I have not tested the sketch of a workflow presented here extensively, yet what I have seen was enough to convince me stack can provide a pleasant experience for casual experiments as well as full-fledged projects. Happy hacking!

**Update:** There is now a follow-up post about the other side of the coin, Migrating a Project to stack.

For that, see Why is stack not cabal?, written by a member of its development team.↩

For installation guidance, see the GitHub project wiki. Installing stack is easy, and there are many ways to do it (I simply got it from Hackage with

`cabal install stack`

).↩To create an environment for an existing project, with its own structure and cabal file, you would use

`stack init`

instead.↩In any case, you can also use

`stack exec -- ghc-pkg list`

to see all packages installed from the snapshot you are currently using. That, however, will be far messier than the`build-depends`

list, as it will include indirect dependencies as well.↩For the latter, see the project wiki.↩

Post licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

`Applicative`

class are not pretty to look at.
```
pure id <*> v = v -- identity
pure f <*> pure x = pure (f x) -- homomorphism
u <*> pure y = pure ($ y) <*> u -- interchange
pure (.) <*> u <*> v <*> w = u <*> (v <*> w) -- composition
```

Monad laws, in comparison, not only look less odd to begin with but can also be stated in a much more elegant way in terms of Kleisli composition `(<=<)`

. Shouldn’t there be an analogous nice presentation for `Applicative`

as well? That became a static question in my mind while I was studying applicative functors many moons ago. After finding surprisingly little commentary on this issue, I decided to try figuring it out by myself. ^{1}

Let’s cast our eye over `Applicative`

:

```
class Functor t => Applicative t where
pure :: a -> t a
(<*>) :: t (a -> b) -> t a -> t b
```

If our inspiration for reformulating `Applicative`

is Kleisli composition, the only sensible plan is to look for a category in which the `t (a -> b)`

functions-in-a-context from the type of `(<*>)`

are the arrows, just like `a -> t b`

functions are arrows in a Kleisli category. Here is one way to state that plan in Haskell terms:

```
> class Applicative t => Starry t where
> idA :: t (a -> a)
> (.*) :: t (b -> c) -> t (a -> b) -> t (a -> c)
>
> infixl 4 .*
> -- The Applicative constraint is wishful thinking:
> -- When you wish upon a star...
```

The laws of `Starry`

are the category laws for the `t (a -> b)`

arrows:

```
idA .* v = v -- left identity
u .* idA = u -- right identity
u .* v .* w = u .* (v .* w) -- associativity
```

The question, then, is whether it is possible to reconstruct `Applicative`

and its laws from `Starry`

. The answer is a resounding yes! The proof is in this manuscript, which I have not transcribed here as it is a little too long for a leisurely post like this one ^{2}. The argument is set in motion by establishing that `pure`

is an arrow mapping of a functor from **Hask** to a `Starry`

category, and that both `(<*>)`

and `(.*)`

are arrow mappings of functors in the opposite direction. That leads to several naturality properties of those functors, from which the `Applicative`

laws can be obtained. Along the way, we also get definitions for the `Starry`

methods in terms of the `Applicative`

ones…

```
> idA = pure id
> u .* v = fmap (.) u <*> v
```

… and vice-versa:

```
pure x = fmap (const x) idA
u <*> v = fmap ($ ()) (u .* fmap const v)
```

Also interesting is how the property relating `fmap`

and `(<*>)`

…

`fmap f u = pure f <*> u`

… now tells us that a `Functor`

results from composing the `pure`

functor with the `(<*>)`

functor. That becomes more transparent if we write it point-free:

`fmap = (<*>) . pure`

In order to ensure `Starry`

is equivalent to `Applicative`

we still need to prove the converse, that is, obtain the `Starry`

laws from the `Applicative`

laws plus the definitions of `idA`

and `(.*)`

just above. That is not difficult; all it takes is substituting the definitions in the `Starry`

laws and:

For left identity, noticing that

`(id .) = id`

.For right identity, applying the interchange law and noticing that

`($ id) . (.)`

is`id`

in a better disguise.For associativity, using the laws to move all

`(.)`

to the left of the`(<*>)`

and then verifying that the resulting messes of dots in both sides are equivalent.

As a tiny example, here is the `Starry`

instance of `Maybe`

…

```
instance Starry Maybe where
idA = Just id
Just g .* Just f = Just (g . f)
_ .* _ = Nothing
```

… and the verification of the laws for it:

```
-- Left identity:
idA .* u = u
Just id .* u = u
-- u = Nothing
Just id .* Nothing = Nothing
Nothing = Nothing
-- u = Just f
Just id .* Just f = Just f
Just (id . f) = Just f
Just f = Just f
-- Right identity:
u .* idA = u
u .* Just id = u
-- u = Nothing
Nothing .* Just id = Nothing
Nothing = Nothing
-- u = Just g
Just g .* Just id = Just g
Just (g .* id) = Just g
Just g = Just g
-- Associativity:
u .* v .* w = u .* (v .* w)
-- If any of u, v and w are Nothing, both sides will be Nothing.
Just h .* Just g .* Just f = Just h .* (Just g .* Just f)
Just (h . g) .* Just f = Just h .* (Just (g . f))
Just (h . g . f) = Just (h . (g . f))
Just (h . g . f) = Just (h . g . f)
```

It works just as intended:

```
GHCi> Just (2*) .* Just (subtract 3) .* Just (*4) <*> Just 5
Just 34
GHCi> Just (2*) .* Nothing .* Just (*4) <*> Just 5
Nothing
```

I do not think there will be many opportunities to use the `Starry`

methods in practice. We are comfortable enough with applicative style, through which we see most `t (a -> b)`

arrows as intermediates generated on demand, rather than truly meaningful values. Furthermore, the `Starry`

laws are not really easier to prove (though they are certainly easier to remember!). Still, it was an interesting exercise to do, and it eases my mind to know that there is a neat presentation of the `Applicative`

laws that I can relate to.

This post is Literate Haskell, in case you wish to play with `Starry`

in GHCi (here is the raw .lhs file ).

```
> instance Starry Maybe where
> instance Starry [] where
> instance Starry ((->) a) where
> instance Starry IO where
```

As for proper implementations in libraries, the closest I found was `Data.Semigroupoid.Static`

, which lives in Edward Kmett’s `semigroupoids`

package. *“Static arrows”* is the actual technical term for the `t (a -> b)`

arrows. The module provides…

`newtype Static f a b = Static { runStatic :: f (a -> b) }`

… which uses the definitions shown here for `idA`

and `(.*)`

as `id`

and `(.)`

of its `Category`

instance.

There is a reasonably well-known alternative formulation of

`Applicative`

: the`Monoidal`

class as featured in this post by Edward Z. Yang. While the laws in this formulation are much easier to grasp,`Monoidal`

feels a little alien from the perspective of a Haskeller, as it shifts the focus from function shuffling to tuple shuffling.↩Please excuse some oddities in the manuscript, such as off-kilter terminology and weird conventions (e.g. consistently naming arguments in applicative style as

`w <*> v <*> u`

rather than`u <*> v <*> w`

in applicative style). The most baffling choice was using`id`

rather than`()`

as the throwaway argument to`const`

. I guess I did that because`($ ())`

looks bad in handwriting.↩

Post licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

`fmap`

is saying that it only changes the values in a container, and not its structure. Leaving behind the the functors-as-containers metaphor, we can convey the same idea by saying that `fmap`

leaves the context of the values in a `Functor`

unchanged. But what, exactly, is the “context” or “structure” being preserved? “It depends on the functor”, though correct, is not an entirely satisfactory answer. The functor laws, after all, are highly abstract, and make no mention of anything a programmer would be inclined to call “structure” (say, the skeleton of a list); and yet the preservation we alluded to follows from them. After struggling a bit with this question, I realised that the incompatibility is only apparent. This post shows how the tension can be resolved through the mediation of A correct, if rather cruel, answer to “Why does `fmap`

preserve structure?” would be “By definition, you silly!” To see what would be meant by that, let’s have a look at the functor laws.

```
fmap id = id -- 1st functor law
fmap (g . f) = fmap g . fmap f -- 2nd functor law
```

`fmap`

is a mapping of functions that takes identity to identity, and composed functions to the corresponding composed functions. Identity and composition make up the structure, in the mathematical sense, of a category. In category theory, a functor is a mapping between categories that preserves category structure. Therefore, the functor laws ensure that Haskell `Functor`

s are indeed functors; more precisely, functors from **Hask** to **Hask**, **Hask** being the category with Haskell types as objects and Haskell functions as arrows.^{1}

That functors preserve category structure is evident. However, our question is not directly about “structure” in the mathematical sense, but with the looser acception it has in programmer parlance. In what follows, our goal will be clarifying this casual meaning.

As an intial, fuzzy characterisation, we can say that, given a functorial value, the `Functor`

context is everything in it other than the wrapped values. Starting from that, a straightforward way of showing why `fmap`

preserves context involves *parametric polymorphism*; more specifically, the preservation is ensured by the wild generality of the types in the signature of `fmap`

.

`fmap :: (Functor t) => (a -> b) -> (t a -> t b)`

We will look at `fmap`

as a function of one argument which converts a plain `a -> b`

function into a function which operates on functorial values. The key fact is that there is very little we can do with the `a -> b`

function when defining `fmap`

. Composition is not an option, as choosing a function other than `id`

to compose it with would require knowledge about the `a`

and `b`

types. The only thing that can be done is applying the function to any `a`

values we can retrieve from the `t a`

functorial value. Since the context of a `t a`

value, whatever it is, does not include the `a`

values, it follows that changes to the context cannot depend on the `a -> b`

function. Given that `fmap`

takes no other arguments, any changes in the context must happen for any `a -> b`

arguments uniformly. The first functor law, however, says that `fmap id = id`

, and so there is one argument, `id`

, which leads to no changes in the context. Therefore, `fmap`

never changes the context.

The informal argument above can be made precise through a proper type theory treatment of parametricity. Philip Wadler’s *Theorems for free!* is a well-known example of such work. However, a type theory approach, while entirely appropriate, would have us taking concrete Haksell types for granted and only incidentally concluding they are functors; in contrast, our problem begins with functors. For that reason, we will follow a different path and look at the issue from a primarily categorical point of view.

In the spirit of category theory, we will now focus not on the types but on the functions between them. After all, given functional purity any interesting properties of a Haskell value can be verified with suitable functions. Let’s start with a few concrete examples of how the context of a `Functor`

can be probed with functions.

`length :: [a] -> Int`

The length of a list is perhaps the most obvious example of a structural property. It depends only on the list skeleton, and not at all on the values in it. The type of `length`

, with a fully polymorphic element type which is not mentioned by the result type, reflects such an independence. An obvious consequence is that `fmap`

, which only affects the list elements, cannot change the length of a list. We can state that like this:

`length xs = length (fmap f xs)`

Or, in a more categorical fashion:

`length = length . fmap f`

Our second example of a structure-probing function will be `reverse`

:

`reverse :: [a] -> [a]`

While the result value of `reverse`

obviously depends on the list elements, `reverse`

cannot actually modify the elements, given that the function is fully polymorphic on the element type. `fmap`

applied to a list after reversing it will thus affect the same element values there were before the reversal; they will only have been rearranged. In other words, `fmap`

*commutes* with `reverse`

:

`fmap f . reverse = reverse . fmap f`

Our final example will be `listToMaybe`

from `Data.Maybe`

:

`listToMaybe :: [a] -> Maybe a`

Operationally, `listToMaybe`

is a safe version of `head`

, which returns `Nothing`

when given an empty list. Again, the function is fully polymorphic in the element type, and so the value of the first element cannot be affected by it. The scenario is very similar to what we have seen for `reverse`

, and an analogous property holds, with the only difference being that `fmap`

is instantiated at a different `Functor`

at each side of the equation:

```
-- Maybe-fmap on the left, []-fmap on the right.
fmap f . listToMaybe = listToMaybe . fmap f
```

Earlier we said that the `Functor`

context consists of everything but the wrapped values. Our examples illustrate how parametric polymorphism makes it possible to keep that general idea while putting functions rather than values under the spotlight. The context is all that can be probed with functions fully polymorphic on the type parameter of the `Functor`

; or, taking the abstraction further, the context *is* the collection of functions fully polymorphic on the type parameter of the `Functor`

. We now have done away with the fuzziness of our preliminary, valure-centric definition. The next step is clarifying how that definition relates to `fmap`

.

By identifying the `Functor`

context with polymorphic functions, we can also state the context-preserving trait of `fmap`

through commutativity equations like those shown in the above examples. For an arbitrary context-probing function `r`

, the equation is:

```
-- f is arbitrary, and so are the involved functors.
fmap f . r = r . fmap f
```

The equations for `reverse`

and `listToMaybe`

clearly have that shape. `length`

does not seem to fit at first sight, but that can be easily solved by lifting it to a constant functor such as the one provided by `Control.Applicative`

.

```
lengthC :: [a] -> Const Int a
lengthC = Const . length
-- length = getConst . lengthC
-- For constant functors, fmap f = id regardless of f.
fmap f . lengthC = lengthC . fmap f
```

A similar trick can be done with the `Identity`

functor to make functions in which the type parameter of the `Functor`

appears bare, such as `Just :: a -> Maybe a`

, fit our scheme.

It turns out that there is a category theory concept that captures the commutativity property we are interested in. A *natural transformation* is a translation between functors which preserves arrows being mapped through them. For Haskell `Functor`

s, that amounts to preserving functions being mapped via `fmap`

. We can display the relation through a diagram:

The naturality condition matches our commuativity property. Indeed, *polymorphic functions are natural transformations between Haskell Functors*. The proof of this appealing result is not trivial, and requires some theoretical work, just like in the case of the closely related results about parametricity we alluded to earlier. In any case, all it takes to go from “natural transformations preserve

`fmap`

” to “`fmap`

preserves natural transformations” is tilting our heads while looking at the diagram above!Given how we identified `Functor`

contexts, polymorphic functions and natural transformations, we can finally give a precise answer to our question. The context consists of natural transformations between functors, and therefore `fmap`

preserves it.

Earlier on, we have said that we would not be directly concerned with structure in the sense mathematicians use the word, but only with the fuzzy Haskell concept that sometimes goes by the same name. To wrap things up, we will now illustrate the fact that both acceptions are not worlds apart. Let’s have another look at the second functor law, which states that `fmap`

preserves composition:

`fmap (g . f) = fmap g . fmap f`

Structure, in the mathematical sense, refers to some collection of interesting operations and distinguished elements. In this example, the relevant operation is function composition, which is part of the structure of the **Hask** category. Besides that, however, we are now able to note the uncanny resemblance between the shapes of the law, which says that it does not matter whether we compose `f`

and `g`

before applying `fmap`

, and of the commutativity properties we used to characterise functorial contexts. The upshot is that by identifying context and structure of a `Functor`

with polymorphic functions, we retain much of the spirit of the mathematical usage of structure. The interesting operations, in our case, are the polymorphic functions with which the context is probed. Perhaps it even makes sense to keep talking of structure of a `Functor`

even after dropping the container metaphor.

Speaking of the second law, we will, just for kicks, use it to show how to turn things around and look at `fmap`

as a natural transformation between `Functor`

s. In order to do so, we have to recall that `(.)`

is `fmap`

for the function functor:

```
-- First, we rewrite the second law in a more suggestive form:
fmap (g . f) = fmap g . fmap f
fmap (((.) g) f) = (.) (fmap g) (fmap f)
fmap . (.) g = ((.) . fmap) g . fmap
-- Next, some synonyms to indicate the Functors fmap leads to.
-- fmap from identity to t
fmap_t :: (Functor t) => (->) a b -> (->) (t a) (t b)
fmap_t = fmap
-- fmap from identity to ((->) a)
fmap_fun :: (b -> c) -> ((->) a b -> (->) a c)
fmap_fun = (.)
-- fmap from identity to the composite functor ((->) (t a)) . t
fmap_fun_t :: (Functor t)
=> (b -> c) -> ((->) (t a) (t b) -> (->) (t a) (t c))
fmap_fun_t = fmap_fun . fmap_t
-- The second law then becomes:
fmap_t . fmap_fun g = fmap_fun_t g . fmap_t
-- That, however, shows fmap_t is a natural transformation:
fmap . fmap g = fmap g . fmap
```

By fixing `t`

and `a`

in the signature of `fmap_t`

above, we get one functor on either side of the outer function arrow: `((->) a)`

on the left and `((->) (t a)) . t`

on the right. `fmap`

is a natural transformation between these two functors.

In

*The Holy Trinity*, Robert Harper comments on the deep connection between logic, type theory and category theory that allows us to shift seamlessly between the categorical and the type theoretical perspectives, as we have done here.*You Could Have Defined Natural Transformations*by Dan Piponi is a very clear introduction to natural transformations in a Haskell context.We have already mentioned Philip Wadler’s

*Theorems for free!*, which is a reasonably accessible introduction to the*free theorems*.*Free theorems*are results about functions that, thanks to parametric polymorphism, can be deduced from the type of the function alone. Given suitable generalisations, free theorems and naturality conditions provide two parallel ways of reaching the same results about Haskell functions.*Free Theorems Involving Type Constructor Classes*, a functional pearl by Janis Voigtländer illustrates how free theorem generation can be generalised to types parametric on type constructors and type classes.For an explicitly categorical perspective on parametricity, a good place to start if you are willing to dig into theory is the section on parametricity in

*Some Aspects of Categories in Computer Science*by Philip J. Scott.

A category theory primer would be too big a detour for this post. If the category theory concepts I just mentioned are new to you, I suggest the following gentle introductions for Haskellers, which have very different approaches: Haskell Wikibook chapter on category theory, and Gabriel Gonzalez’s posts The category design pattern and The functor design pattern.↩

Post licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

`lens`

library are its astonishing breadth and generality. And yet, the whole edifice is built around van Laarhoven lenses, which are a simple and elegant concept. In this hands-on exposition, I will show how the `Lens`

type can be understood without prerequisites other than a passing acquaintance with Haskell functors. Encouraging sound intuition in an accessible manner can go a long way towards making `lens`

and lenses less intimidating.
Dramatis personæ:

```
> import Data.Functor.Identity (Identity(..))
> import Control.Applicative (Const(..))
```

I will define a toy data type so that we have something concrete to play with, as well as a starting point for working out generalisations.

`> data Foo = Foo { bar :: Int } deriving (Show)`

The record definition gets us a function for accessing the `bar`

field.

```
GHCi> :t bar
bar :: Foo -> Int
```

As for the setter, we have to define it ourselves, unless we feel like mucking around with record update syntax.

```
> setBar :: Foo -> Int -> Foo
> setBar x y = x { bar = y }
```

Armed with a proper getter and setter pair, we can easily flip the sign of the `bar`

inside a `Foo`

.

```
GHCi> let x = Foo 3
GHCi> setBar x (negate $ bar x)
Foo {bar = -3}
```

We can make it even easier by defining a modifier function for `bar`

.

```
> modifyBar :: (Int -> Int) -> Foo -> Foo
> modifyBar k x = setBar x . k . bar $ x
```

```
GHCi> modifyBar negate x
Foo {bar = -3}
```

`setBar`

can be recovered from `modifyBar`

by using `const`

to discard the original value and put the new one in its place.

`const y = \_ -> y`

```
> setBar' :: Foo -> Int -> Foo
> setBar' x y = modifyBar (const y) x
```

If our data type had several fields, defining a modifier for each of them would amount to quite a lot of boilerplate. We could minimise it by, starting from our `modifyBar`

definition, abstracting from the specific getter and setter for `bar`

. Here, things begin to pick up steam. I will define a general `modify`

function, which, given an appropriate getter-setter pair, can deal with any field of any data type.

```
> modify :: (s -> a) -> (s -> a -> s) -> (a -> a) -> s -> s
> modify getter setter k x = setter x . k . getter $ x
```

It is trivial to recover `modifyBar`

; when we do so, `s`

becomes `Foo`

and `a`

becomes `Int`

.

```
> modifyBar' :: (Int -> Int) -> Foo -> Foo
> modifyBar' = modify bar setBar
```

The next step of generalisation is the one leap of faith I will ask of you in the way towards lenses. I will introduce a variant of `modify`

in which the modifying function, rather than being a plain `a -> a`

function, returns a functorial value. Defining it only takes an extra `fmap`

.

```
> modifyF :: Functor f => (s -> a) -> (s -> a -> s)
> -> (a -> f a) -> s -> f s
> modifyF getter setter k x = fmap (setter x) . k . getter $ x
```

And here is its specialisation for `bar`

.

```
> modifyBarF :: Functor f => (Int -> f Int) -> Foo -> f Foo
> modifyBarF = modifyF bar setBar
```

Why on Earth we would want to do that? For one, it allows for some nifty tricks depending on the functor we choose. Let’s try it with lists. Specialising the `modifyF`

type would give:

`modifyL :: (s -> a) -> (s -> a -> s) -> (a -> [a]) -> s -> [s]`

Providing the getter and the setter would result in a `(a -> [a]) -> s -> [s]`

function. Can you guess what it would do?

```
GHCi> modifyBarF (\y -> [0..y]) x
[Foo {bar = 0},Foo {bar = 1},Foo {bar = 2},Foo {bar = 3}]
```

As the types suggest, we get a function which modifies the field in multiple ways and collects the results.

I claimed that moving from `modify`

to `modifyF`

was a generalisation. Indeed, we can recover `modify`

by bringing `Identity`

, the dummy functor, into play.

```
newtype Identity a = Identity { runIdentity :: a }
instance Functor Identity where
fmap f (Identity x) = Identity (f x)
```

`modifyI :: (s -> a) -> (s -> a -> s) -> (a -> Identity a) -> s -> Identity s`

```
> modify' :: (s -> a) -> (s -> a -> s) -> (a -> a) -> s -> s
> modify' getter setter k =
> runIdentity . modifyF getter setter (Identity . k)
```

We wrap the field value with `Identity`

value after applying `k`

and unwrap the final result after applying the setter. Since `Identity`

does nothing interesting to the wrapped values, the overall result boils down to our original `modify`

. If you have found this definition confusing, I suggest that you, as an exercise, rewrite it in pointful style and substitute the definition of `modifyF`

.

We managed to get `modify`

back with little trouble, which is rather interesting. However, what is truly surprising is that we can reconstruct not only the modifier but also the getter! To pull that off, we will use `Const`

, which is a very quaint functor.

```
newtype Const a b = Const { getConst :: a }
instance Functor (Const a) where
fmap _ (Const y) = Const y
```

`modifyC :: (s -> a) -> (s -> a -> s) -> (a -> Const r a) -> s -> Const r s`

If functors were really containers, `Const`

would be an Acme product. A `Const a b`

value does not contain anything of type `b`

; what it does contain is an `a`

value that we cannot even modify, given that `fmap f`

is `id`

regardless of what `f`

is. As a consequence, if, given a field of type `a`

, we pick `Const a a`

as the functor to use with `modifyF`

, if our chosen modifying function wraps the field value with `Const`

then it will not be affected by the setter, and we will be able to recover it later. That suffices for recovering the getter.

```
> get :: (s -> a) -> (s -> a -> s) -> s -> a
> get getter setter = getConst . modifyF getter setter Const
>
> getBar :: Foo -> Int
> getBar = get bar setBar
```

Given a getter and a setter, `modifyF`

gets us a corresponding functorial modifier. From it, by choosing the appropriate functors, we can recover the getter and a plain modifier; the latter, in turn, allows us to recover the setter. We can highlight the correspondence by redefining once more the recovered getters and modifiers, this time in terms of the functorial modifier.

```
modifyF :: Functor f => (s -> a) -> (s -> a -> s)
-> ((a -> f a) -> s -> f s)
```

```
> modify'' :: ((a -> Identity a) -> s -> Identity s) -> (a -> a) -> s -> s
> modify'' modifier k = runIdentity . modifier (Identity . k)
>
> modifyBar'' :: (Int -> Int) -> Foo -> Foo
> modifyBar'' = modify'' modifyBarF
>
> set :: ((a -> Identity a) -> s -> Identity s) -> s -> a -> s
> set modifier x y = modify'' modifier (const y) x
>
> setBar'' :: Foo -> Int -> Foo
> setBar'' = set modifyBarF
>
> get' :: ((a -> Const a a) -> s -> Const a s) -> (s -> a)
> get' modifier = getConst . modifier Const
>
> getBar' :: Foo -> Int
> getBar' = get' modifyBarF
```

The bottom line is that given `modifyBarF`

we can get by without `modifyBar`

, `setBar`

and `bar`

, as `modify''`

, `set`

and `get'`

allow us to reconstruct them whenever necessary. While our first version of `get`

was, in effect, just a specialised `const`

with a wacky implementation, `get'`

is genuinely useful because it cuts the number of separate field manipulation functions we have to deal with by a third.

Even after all of the work so far we can still generalise further! Let’s have a second look at `modifyF`

.

```
modifyF :: Functor f => (s -> a) -> (s -> a -> s)
-> (a -> f a) -> s -> f s
modifyF getter setter k x = fmap (setter x) . k . getter $ x
```

The type of `setter`

is `(s -> a -> s)`

; however, nothing in the implementation forces the first argument and the result to have the same type. Furthermore, with a different signature `k`

could have a more general type, `(a -> f b)`

, as long as the type of `setter`

was adjusted accordingly. We can thus give `modifyF`

a more general type.

```
> modifyGenF :: Functor f => (s -> a) -> (s -> b -> t)
> -> (a -> f b) -> s -> f t
> modifyGenF getter setter k x = fmap (setter x) . k . getter $ x
```

For the sake of completeness, here are the generalised recovery functions. `get`

is not included because the generalisation does not affect it.

```
> modifyGen :: ((a -> Identity b) -> s -> Identity t) -> (a -> b) -> s -> t
> modifyGen modifier k = runIdentity . modifier (Identity . k)
>
> setGen :: ((a -> Identity b) -> s -> Identity t) -> s -> b -> t
> setGen modifier x y = modifyGen modifier (const y) x
```

By now, it is clear that our getters and setters need not be ways to manipulate fields in a record. In a broader sense, a getter is anything that produces a value from another; in other words, any function can be a getter. By the same token, any binary function can be a setter, as all that is required is that it combines one value with another producing a third; the initial and final values do not even need to have the same type.^{1} That is a long way from the toy data type we started with!

If we look at `modifyGenF`

as a function of two arguments, its result type becomes:

`Functor f => (a -> f b) -> s -> f t`

Now, let’s take a peek at Control.Lens.Lens:

`type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t`

It is the same type! We have reached our destination.^{2} A lens is what we might have called a generalised functorial modifier; furthermore, sans implementation details we have that:

- The
`lens`

function is`modifyGenF`

; `modifyF`

is`lens`

specialised to produce simple lenses;^{3}`modifyBarF`

is a lens with type`Lens Foo Foo Int Int`

;`(^.)`

is flipped`get'`

;`set`

is`setGen`

;`over`

is`modifyGen`

further generalised.^{4}

`lens`

uses type synonyms liberally, so those correspondences are not immediately obvious form the signatures in the documentation. Digging a little deeper, however, shows that in

`set :: ASetter s t a b -> b -> s -> t`

`ASetter`

is merely

`type ASetter s t a b = (a -> Identity b) -> s -> Identity t`

Analogously, we have

```
(^.) :: s -> Getting a s a -> a
type Getting r s a = (a -> Const r a) -> s -> Const r s
```

Behind the plethora of type synonyms - `ASetter`

, `Getting`

, `Fold`

, `Traversal`

, `Prism`

, `Iso`

and so forth - there are different choices of functors,^{5} which make it possible to capture many different concepts as variations on lenses. The variations may be more general or less general than lenses; occasionally they are neither, as the overlap is just partial. The fact that we can express so much through parametrization of functors is key to the extraordinary breadth of `lens`

.

This exposition is primarily concerned with building lenses, and so very little was said about how to use them. In any case, we have seen enough to understand why lenses are also known as functional references. By unifying getters and setters, lenses provide a completely general vocabulary to point at parts of a whole.

Finally, a few words about composition of lenses are unavoidable. One of the great things about lenses is that they are just functions; even better, they are functions with signatures tidy enough for them to compose cleanly with `(.)`

. That makes it possible to compose lenses independently of whether you intend to get, set or modify their targets. Here is a quick demonstration using the tuple lenses from `lens`

.

```
GHCi> :m
GHCi> :m +Control.Lens
GHCi> ((1,2),(3,4)) ^. _1 . _2
GHCi> 2
GHCi> set (_1 . _2) 0 ((1,2),(3,4))
GHCi> ((1,0),(3,4))
```

A perennial topic in discussions about `lens`

is the order of composition of lenses. They are often said to compose backwards; that is, backwards with respect to composition of record accessors and similar getters. For instance, the getter corresponding to the `_1 . _2`

lens is `snd . fst`

. The claim that lenses compose backwards, or in the “wrong order”, however, are only defensible when talking about style, and not about semantics. That becomes clear after placing the signatures of a getter and its corresponding lens side by side.

```
GHCi> :t fst
fst :: (a, b) -> a
GHCi> :t _1 :: Lens' (a, b) a
_1 :: Lens' (a, b) a
:: Functor f => (a -> f a) -> (a, b) -> f (a, b)
```

The getter takes a value of the source type and produces a value of the target type. The lens, however, takes a function from the target type and produces a function from the source type. Therefore, it is no surprise that the order of composition differs, and the order for lenses is entirely natural. That ties in closely to what we have seen while implementing lenses. While we can squeeze lenses until they give back getters, it is much easier to think of them as generalised modifiers.

We are not quite as free when it comes to pairing getters and setters. Beyond the obvious need for getter and setter to start from values of the same type, they should behave sanely when composed. In particular, the following should hold:

↩`get' modifier (setGen modifier y x) ≡ y setGen modifier (get' modifier x) x ≡ x setGen modifier z (setGen modifier y x) ≡ setGen modifier z x`

“What about the

`forall`

?” you might ask. Are we cheating? Not quite. The`forall`

is there to control how`f`

is specialised when lens combinators are used. The underlying issue does not affect our reasoning here. If you are into type system subtleties, there were a few interesting comments about it in the reddit thread for this post.↩`Lens' s a`

or`Lens s s a a`

, as opposed to`Lens s t a b`

.↩Yes, even further; from taking modifying functions to taking modifying profunctors. The difference need not worry us now.↩

And in some cases of profunctors to replace the function type constructor.↩

Post licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.