Que? The fclabels package is a haskell library providing “first class labels” for haskell data types and some Template Haskell code for automatically generating said labels. This makes for a more composable and much more powerful alternative to haskell’s built-in record syntactic sugar. Here is a good introductory tutorial.

The new version features (besides some better names) a type for lenses that can fail. S.V. et al. added this functionality in a brilliant and mostly (except for the name changes) backwards compatible way. We’ll see how it all works now.

We’ll prepare a module for fclabels in the usual way:

1 {-# LANGUAGE TemplateHaskell, TypeOperators #-}
2 import Control.Category
3 import Data.Label
4 import qualified Data.Label.Maybe as M
5 import Prelude hiding ((.), id)

The only odd thing above is our qualified import of Data.Label.Maybe which provides getters, setters etc. that can fail.

We want to generate lenses for the following type, so we do the underdash thing:

36 data Example = X { _int :: Int , _char :: Char}
37              | Y { _int :: Int , _example :: Example }

Notice how _int is a valid record for both constructors X and Y, where the other two are partial functions.

Lastly, the usual splice for generating labels:

39 $(mkLabels[''Example])

Let’s load our file into GHCi and play a little:

Prelude> :l test.hs
[1 of 1] Compiling Main             ( test.hs, interpreted )
Ok, modules loaded: Main.
*Main> get int $ X 1 'a'
1
*Main> M.get int $ X 1 'a'
Just 1
*Main> M.get char $ X 1 'a'
Just 'a'
*Main> M.get example $ X 1 'a'
Nothing
*Main> get example $ X 1 'a'

:1:5:
    No instance for (Control.Arrow.ArrowZero (->))
      arising from a use of `example'
    Possible fix:
      add an instance declaration for (Control.Arrow.ArrowZero (->))
    In the first argument of `get', namely `example'
    In the expression: get example
    In the expression: get example $ X 1 'a'

Above we saw that:

• the total int label could be used in both get and Data.Label.Maybe.get
• M.get on our “partial lenses” (example and char) safely returned a Maybe value.
• pure get used with partial lenses doesn’t type check

We need to look at some types (note I’ve cleaned up some of these type signatures, yours may look uglier):

*Main> :t get
get :: (f :-> a) -> f -> a
*Main> :t M.get
M.get :: (f M.:~> a) -> f -> Maybe a
*Main> :info (:->)
type (:->) f a = Data.Label.Pure.PureLens f a
  	-- Defined in Data.Label.Pure
*Main> :info (M.:~>)
type (M.:~>) f a = Data.Label.Maybe.MaybeLens f a
  	-- Defined in Data.Label.Maybe

You can see above that setters and getters are monomorphic. But how then were we able to use int in both get and M.get? Time to look at the types of our TH-generated lenses:

*Main> :t int
int
  :: Control.Arrow.Arrow (~>) => Lens (~>) Example Int
*Main> :t char
char
  :: (Control.Arrow.ArrowZero (~>),
      Control.Arrow.ArrowChoice (~>)) =>
     Lens (~>) Example Char
*Main> :t example
example
  :: (Control.Arrow.ArrowZero (~>),
      Control.Arrow.ArrowChoice (~>)) =>
     Lens (~>) Example Example

Whoah! Lenses themselves are polymorphic in the Arrow class; partial lenses have additional restrictions of ArrowZero and ArrowChoice allowing for failure and choice.

This is wizardry of the highest order.

Notice how we can still compose lenses freely, whether partial or total:

*Main> :t (.)
(.) :: Category cat => cat b c -> cat a b -> cat a c
*Main> M.get (int . example) (Y 1 (X 2 ‘a’))
Just 2

A note on mkLabelsNoTypes

I had been using the noTypes variation to generate lenses that I was exporting in a module, because the TH-assigned type sigs looked pretty nasty. If you do this with >1.0 you will run into the monomorphism restriction and ambiguous type variables.

Instead I would suggest defining exported lables by hand and giving them a nicer looking (or monomorphic if you prefer) type sig.

You can even let fclabels generate the code and just paste it in, e.g.:

Prelude> :set -ddump-splices
Prelude> :l test.hs
[1 of 1] Compiling Main             ( test.hs, interpreted )
test.hs:1:1: Splicing declarations
    mkLabels ['Example]
  ======>
    test.hs:40:3-21
    char ::
      forall ~>[a1kk]. (Control.Arrow.ArrowChoice ~>[a1kk],
                        Control.Arrow.ArrowZero ~>[a1kk]) =>
      Lens ~>[a1kk] Example Char
    {-# INLINE[0] CONLIKE char #-}
    char
      = let
          c[a1kl]
            = (Control.Arrow.zeroArrow Control.Arrow.||| Control.Arrow.returnA)
        in
          Data.Label.Abstract.lens
            (c[a1kl]
           . Control.Arrow.arr
               (\ p[a1km]
                  -> case p[a1km] of {
                       X {} -> Right (_char p[a1km])
                       _ -> Left GHC.Unit.() }))
            (c[a1kl]
           . Control.Arrow.arr
               (\ (v[a1kn], p[a1ko])
                  -> case p[a1ko] of {
                       X {} -> Right (p[a1ko] {_char = v[a1kn]})
                       _ -> Left GHC.Unit.() }))
...

The Data Declaration:

To understand a monad you look at it’s datatype and then at the definition for bind (>>=). Most monad tutorials start by showing you the data declaration of a State s a in passing, as if it needed no explanation:

newtype State s a = State { runState :: s -> (a, s) }

But this does need explanation! This is crazy stuff and nothing like what we’ve seen before in the list monad or the Maybe monad:

1. The constructor State holds a function, not just a simple value like Maybe’s Just. This looks weird.
2. Furthermore there is an accessor function runState with a weirdly imperative-sounding name.
3. Finally, there are two free variables on the left side, not just one.

Yikes! Let’s try to get our head on straight and figure this out:

First of all the State monad is just an abstraction for a function that takes a state and returns an intermediate value and some new state value. To formalize this abstraction in haskell, we wrap the function in the newtype State allowing us to define a Monad instance.

Stepping back from the abstract and conceptual, what we have is the State constructor acting as a container for a function :: s -> (a,s), while the definition for bind just provides a mechanism for “composing” a function state -> (val,state) within the State wrapper.

Just as you can chain together functions using (.) as in (+1) . (*3) . head :: (Num a) => [a] -> a, the state monad gives you (>>=) to chain together functions that look essentially like :: a -> s -> (a,s) into a single function :: s -> (a,s).

Let’s bring the discussion back to actual code and try to make sure we understand those three points of weirdness outlined above. Here’s a stupid example of a function that can be “contained” in our state type:

-- look at our counter and return "foo" or "bar"
-- along with the incremented counter:
fromStoAandS :: Int -> (String,Int)
fromStoAandS c | c `mod` 5 == 0 = ("foo",c+1)
               | otherwise      = ("bar",c+1)

If we just wrap that in a State constructor, we’re in the State monad:

stateIntString :: State Int String
stateIntString = State fromStoAandS

But what about runState? All that does of course is give us the “contents” of our State constructor: i.e. a single function :: s -> (a,s). It could have been named stateFunction but someone thought it would be really clever to be able to write things like:

runState stateIntString 1

See, all we’ve done there is used runState to take our function (fromStoAandS) out of the State wrapper; it is then applied it to it’s initial state (1). We would do this runState business after building up our composed function with (>>=), mapM, etc.

That leaves point 3 unanswered. Let’s start exploring the instance declaration for State.

The Instance Declaration

We’ll start with the first line:

instance Monad (State s) where

We create a Monad instance for (State s) not State. You can think of this as a partially-applied type, which is equivalent to a partially applied function:

(State) < ==> (+)
(State s) < ==> (1+)
(State s a) < == (1+2)

So (State s) is the m in our m a. This means the type of our state will remain the same as we compose our function with (>>=), whereas the intermediate values (the as) may well change type as they move through the chain.

Before we move on to the meat of the instance declaration, I’d like to get your mind calibrated to look at the definitions for return and (>>=):

Whenever you see m a, as in

return :: (Monad m) => a -> m a

…remember that m a is actually

State s a

…and when you remember (State s a), think

(s -> (s,a)).

So in your mind, m a becomes function :: s -> (a,s) everywhere you see it. Just forget about the silly State wrapper (the compiler does)!

The definition of return and Bind

Let’s wet our feet with the definition for return:

    return a = State $ \s -> (a, s)

All return does is take some value a and make a function that takes a state value and returns (value, state value). If we ignore the whole State wrapping business, then return is just (,) :: a -> b -> (a, b)

Now recall the definition of bind:

(>>=) :: (Monad m) => m a -> (a -> m b) -> m b

Which in our case is:

(>>=) ::  State s a        -> 
          (a -> State s b) -> 
          State s b

And which is just a silly abstraction for the super special function composition that’s going on, which looks like:

(>>=) ::  (s -> (a,s))       -> 
          (a -> s -> (b,s))  -> 
          (s -> (b,s))

So on the left hand side of (>>=) is a function that takes some initial state and produces a (value,new_state). On the right hand side is a function that takes that value and that new_state and generates it’s own (new_value, newer_state). The job of bind is simply to combine those two functions into one bigger function from the initial state to (new_value,newer_state), just like the simple function composition operator (.) :: (b -> c) -> (a -> b) -> a -> c

At this point, we can show you bind’s definition:

    m >>= k  = State $ \s -> let
        (a, s') = runState m s
        in runState (k a) s'

You can work through that on your own, keeping in mind that we’re doing function composition here. The main thing to remember is that the s at the top, right after State, won’t actually be bound to a value until we unwrap the function with runState and pass it the initial state value, at which point we can evaluate the entire chain.

A Final Note About The State Monad with do Notation

State is often used like this:

stateFunction :: State [a] ()
stateFunction = do x <- pop
                   pop
                   push x

Remember that the functions above are desugaring to m >>= \a-> f... or if there is no left arrow on the previous line: m >>= \_-> f... That a in there is an intermediate value, the fst in the tuple. The push function might look like:

push :: State [a] ()
push a = State $ \as -> (() , a:as)

The function doesn’t return any meaningful a value, so we don’t bind it by using the < -. For more work with do notation and some fine pictures, see Bonus's post on something awful.