Learn Haskell Types and Records with XMonad's XConfig example

Small changes to XMonad like changing keyboard shortcuts require little Haskell knowledge. However, bigger customizations, especially adapting other people’s configurations, are easier when you understand Haskell types and records.

The so-called “record notation” is a convenient and concise notation to create, read, write and update a special kind of Haskell value, called a record, that is a tightly-related bundle of data. A record combines related values into a single “thing” like a row in an Excel spreedsheet or like a struct in C, C++, Java or C# programming languages. The main record that you will find in every XMonad configuration file is called XConfig which bundles all settings that you can set up in XMonad.

Actually, XConfig is not a value but a type. Our goal is to present you the difference between the two, types and values, as well as record notation. This will allow you to understand the type XConfig on its documentation page, understand its source code, as well as to read and modify XConfig record values for your XMonad configuration.

Briefly, the following Haskell source code introduces the XConfig type to define which settings are available and configurable in XMonad.

data XConfig l = XConfig
  { normalBorderColor  :: String
  , focusedBorderColor :: String
  , terminal           :: String
  -- ...
  }

The following Haskell code uses an existing XConfig record value called def and modifies it slightly:

myTerminal :: String
myTerminal = "gnome-terminal"

myConfig = def {
  { terminal = myTerminal
  }

The notation in this code with the curly braces {...} is called record syntax and constructs a (new) concrete value to configure concrete settings You will find code like this in other people’s configuration code and write code like this in your own.

Type

Understanding the difference between types and values is important to understand Haskell code and XMonad configuration files. If you have programmed in languages like Java, C++ or Python, you were already exposed to these concepts but may have used the words “class” instead of “type” and “object” instead of “value”.

Briefly, a type is a collection of related values. Intuitively, you put items, which you think are related, into a bag and give that bag a name. Then the items are called values and the name of that bag is called the type. For example, three widespread types, that intelligent people put together, are the Booleans, Integers and Strings, which are available in every programming language. In Haskell these types are concisely named Bool, Int and String:

myConfig = def
  { terminal = 2 -- error, terminal is a String, but is given a number
  }

myConfig = def
  { terminal = "gnome-tarminal"
  }

Create a new type for a record

The authors of XMonad introduced the XConfig type as the name for the collection of all possible XMonad configurations. This type is introduced with the data keyword using the following notation:

data <name of new type> = <name of new value constructor>
  { <name of setting 1> :: <type of setting 1>
  , <name of setting 2> :: <type of setting 2>
    ...
  }

Since the XConfig type is complicated, we will explain this notation with a contrived example of a Person type:

-- Person.hs file
data Person = PersonValueConstructor { name :: String, height :: Int, isAdult :: Bool }
-- or
data Person = PersonValueConstructor
  { name :: String
  , height :: Int
  , isAdult :: Bool
  }

This data keyword introduces a new type called Person, whose values will be records containing a name, a height and information about whether this person is an adult. The words name, height and isAdult are called fields and are slots for information values that will be part of a concrete Person value. In that sense records are built like Lego bricks: from smaller, existing pieces.

Fields are annotated with :: <type for slot> to define what values are allowed in each slot. For example

name :: String

tells you that the name field only accepts and contains a string like "Jane". You can read this double colon :: as “has type” and the type after that must already exist.

Finally, this PersonValueConstructor as its name suggest will be an indicator that your are creating a Person value. In Haskell Types and value constructors always begin with an uppercase letter. Thus, when you see Person in Haskell code, you will know that it refers to the type, and when you see PersonValueConstructor you will know that you are creating a concrete value.

Create a record value

Having introduced a Person type there are two styles to create a concrete Person value:

-- Person.hs file continued
myConcretePerson1 :: Person -- optional
myConcretePerson1 = PersonValueConstructor "John" 180 True -- first style

myConcretePerson2 = PersonValueConstructor -- second style
  { name = "Jane"
  , height = 134,
  , isAdult = False
  }

You create a Person value by using its PersonValueConstructor followed by concrete values to fill the required Person fields. Normally, the second way is easier to read and recommended. This myConcretePerson2 is a variable/name for the concrete Person value you create on the right-hand side of =. You can optionally annotate a variable like myConcretePerson1 with a type by using :: Person. XMonad’s type checker then will check that the value you assign to this myConcretePerson1 variable is indeed a Person value. Roughly, everything that is not a type or value constructor, for example a variable name, begins with a lowercase letter.

In Haskell it is possible and recommended to give a type and its value constructor an identical name in order avoid having to invent another name, because naming is hard.

--- BetterPerson.hs file
data Person = Person
  { name :: String
  , height :: Int
  , isAdult :: Bool
  }

Here, the left occurence of Person is the type and the right occurence is its value constructor. With practice you won’t be confused about whether you mean the type or the value, because they are used in separated places.

-- BetterPerson.hs file continued
myConcretePerson :: Person -- Person type
myConcretePerson = Person  -- Person value constructor
  { name = "Jane"
  , height = 134,
  , isAdult = False
  }

In fact XConfig also uses the same name for the type and its value constructor. Furthermore, just as we defined myConcretePerson a concrete Person value, the authors of XMonad defined a concrete, built-in XConfig value called def, which represents a full configuration.

Modify a record value

Because an XConfig value needs a lot of settings to be set up, it is a lot faster to use an existing XMonad configuration like def and only tweak a few settings rather than to build it from the ground up. In the Person example, we can modify a concrete value as follows:

-- BetterPerson.hs file continued
myConcreteModifiedPerson = myConcretePerson
  { name = "Lisa"
  }

Here we take the myConcretePerson value from before and create a copy named myConcreteModifiedPerson with all the same fields except the name set to "Lisa" instead of "Jane".

One drawback of Haskell is that all variables like myConcretePerson can only be assigned once and contain the same value forever. Thus we can never modify an existing variable but only make a copy with our desired changes. Actually, this is one of Haskell’s strengths.

Now you should roughly be able to understand XConfig code in example configurations on the web, that usually look as follows:

windowsKey = mod4Mask
-- ...

myConfig = def
  { modMask = windowsKey
  , terminal = "gnome-terminal"
  -- ...
  }

Here, people use XMonad’s default XConfig value def and tweak a few settings they aren’t happy with.

Access fields of a record value

As your XMonad configuration becomes more and more complicated or you start to set up settings like keyboard shortcut in the keys field/setting of XConfig, you need to write functions that need to access some field of a record value. Especially for the keys field you may need access to some other fields of XConfig. This field has this weird-looking type:

data XConfig l = XConfig
    { ...
    , keys :: XConfig ... -> M.Map ...
    , ...
    }

Briefly, this type tells us that keys is not just an ordinary setting. Instead the -> symbol tells us that it’s a function that expects a value of type XConfig and, given such an XConfig value, returns a value of type M.Map.
[How to set up keys.]
[How to write functions.]

Since XConfig is complicated, let us get back to Person example to learn how to access fields of a record value.

-- BetterPerson.hs file
data Person = Person
  { name :: String
  , height :: Int
  , isAdult :: Bool
  }

myConcretePerson :: Person -- Person type, optional
myConcretePerson = Person  -- Person value constructor
  { name = "Jane"
  , height = 134,
  , isAdult = False
  }

myGreetText :: String -- optional
myGreetText = "Hello " ++ (name myConcretePerson) -- result: "Hello Jane"

When you define the Person type as above, the field names also become so-called “accessor functions”. For example, field name name also becomes an (accessor) function of type Person -> String, meaning that, given a Person value, it returns its name string. This is why name myConcretePerson computes "Jane". This string by the way then is combined with "Hello " using the ++ operator to build a new string "Hello Jane".

So now when you see code like

... (terminal def)...

and you remember that terminal is a string field of XConfig, you know that the string value of the terminal setting of the def value is computed.

Furthermore, you can use accessor functions on functions arguments as follows:

myGreetFunc :: Person -> String -- optional
myGreetFunc p = "Hello " ++ (name p)

Here, by the type of myGreetFunc you know that this argument variable p is a Person value, so that you can use the name accessor function.
[How to read and write functions.]

For the keys setting of XConfig, for example, you also can access other XConfig settings in the same style:

-- myKeysFunc :: XConfig ... -> M.Map ...
myKeysFunc baseConfig = M.fromList $
 [ (((modKey baseConfig), xK_Return), spawn  (terminal baseConfig))
 , (((modKey baseConfig), xK_q),      restart "xmonad" True)
 ]

myConfig = def
  { keys = myKeysFun -- override previous keymaps
  }

Here myKeysFunc is a function that gets an XConfig value, which it uses locally (inside this function) under the name baseConfig. With terminal baseConfig it extracts the terminal string value from this given baseConfig record value, and with modKey baseConfig it extracts the modKey value.

Pattern matching to access a field from a record value

There is another style called “Pattern Matching” to extract a value from a record.

myConcretePerson :: Person -- Person type, optional
myConcretePerson = Person  -- Person value constructor
  { name = "Jane"
  , height = 134,
  , isAdult = False
  }

myGreetFunc2 :: Person -> String
myGreetFunc2 (Person { name = localName }) = "Hello " ++ localName

Here in the myGreetFunc2 function we match a given Person value structurally against the pattern Person { name = ... }, where Person in front of { name ...} is the value constructor for the Person type. Here we match the person’s field name and use its value locally under the name localName in "Hello o" ++ localName.

In many XMonad configurations you will finde code that use pattern matching mixed with accesor functions as follows:

-- myKeysFunc :: XConfig ... -> M.Map ...
myKeysFunc baseConfig@(XConfig {modMask = modKey}) = M.fromList $
 [ ((modKey, xK_Return), spawn (terminal baseConfig))
 , ((modKey, xK_q),      restart "xmonad" True)
 ]

myConfig = def
  { keys = myKeysFun -- override previous keymaps
  }

Here in the myKeysFunc function we match a given XConfig value structurally against (XConfig {modMask...}) to extract the modMask field and use it locally under the name modKey. This baseConfig@(...) notation with the @ symbol is called “As-pattern” and is used to give a name, namely baseConfig, to the whole given XConfig value. This allows us to use accesor functions like terminal on it as in (terminal baseConfig) while using pattern matching at the same time.

More on data structures

data <new type name> = <new value 1> | <new value 2> | ...

data Bool = True | False

data Box = EmptyBoxConstructor | NonEmptyBoxConstructor Bool

data Box = Empty | Box Bool

data XConfig l = XConfig
     { ...
     }

data Box payload = Empty | Box payload

---equivalent notation
data BoxBool = Empty | Box Bool
data BoxInt = Empty | Box Int
...

data Box a = Empty | Box a

data NonEmptyBox p = NonEmptyBox p

data XConfig l = XConfig {... l ...}

data Map k a = ...