Terminology

Even for those familiar with Haskell as a language, there can sometimes be some confusion about terminology. Let's establish some base terms that we can use throughout this book.

Data type

This is one of the core building blocks for a strongly typed language like Haskell. Some data types, like Int, can be treated as primitive values, while other data types will build on top of these to create more complicated values. For example, you might represent a person with:

data Person = Person Text Int

Here, the Text would give the person's name, and the Int would give the person's age. Due to its simplicity, this specific example type will recur throughout the book. There are essentially three ways you can create a new data type:

• A type declaration such as type GearCount = Int merely creates a synonym for an existing type. The type system will do nothing to prevent you from using an Int where you asked for a GearCount. Using this can make your code more self-documenting.

• A newtype declaration such as newtype Make = Make Text. In this case, you cannot accidently use a Text in place of a Make; the compiler will stop you. The newtype wrapper always disappears during compilation, and will introduce no overhead.

• A data declaration, such as Person above. You can also create Algebraic Data Types (ADTs), such as data Vehicle = Bicycle GearCount | Car Make Model.

Data constructor

In our examples above, Person, Make, Bicycle, and Car are all data constructors.

Type constructor

In our examples above, Person, Make, and Vehicle are all type constructors.

Type variables

Consider the data type data Maybe a = Just a | Nothing. In this case, a is a type variable.

Tools

There are two main tools you'll need to Haskell development. The Glasgow Haskell Compiler (GHC) is the standard Haskell compiler, and the only one officially supported by Yesod. You'll also need Cabal, which is the standard Haskell build tool. Not only do we use Cabal for building our local code, but it can automatically download and install dependencies from Hackage, the Haskell package repository.

If you're on Windows or Mac, it is strongly recommended to download the Haskell Platform. On Linux, many distributions include the Haskell Platform in their repositories. On Debian-based systems, for example, you can get started by running sudo apt-get install haskell-platform. If your distribution does not include the Haskell Platform, you can install it manually by following the instructions on the Haskell Platform's page.

One important tool you'll need to update is alex. The Haskell Platform includes version 2, while the Javascript minifier Yesod uses, hjsmin, requires version three. Be sure to cabal install alex after getting set up with the Haskell Platform, or you'll run into error messages about the language-javascript package.

Regardless of how you've installed your tools, you should sure to put cabal's bin folder in your PATH variable. On Mac and Linux, this will be $HOME/.cabal/bin and on Windows it will be %APPDATA%\cabal\bin.

cabal has lots of different options available, but for now, just try out two commands:

• cabal update will download the most recent list of packages from Hackage.

• cabal install yesod will install Yesod and all its dependencies.

Language Pragmas

GHC will run by default in something very close to Haskell98 mode. It also ships with a large number of language extensions, allowing more powerful type classes, syntax changes, and more. There are multiple ways to tell GHC to turn on these extensions. For most of the code snippets in this book, you'll see language pragmas, which look like this:

{-# LANGUAGE MyLanguageExtension #-}

These should always appear at the top of your source file. Additionally, there are two other common approaches:

• On the GHC command line, pass an extra argument -XMyLanguageExtension.

• In your cabal file, add an extensions block.

I personally never use the GHC command line argument approach. It's a personal preference, but I like to have my settings clearly stated in a file. In general it's recommended to avoid putting extensions in your cabal file; however, in the Yesod scaffolded site we specifically use this approach to avoid the boilerplate of specifying the same language pragmas in every source file.

We'll end up using quite a few language extensions in this book (the scaffolding uses 11). We will not cover the meaning of all of them. Instead, please see the GHC documentation.

Overloaded Strings

What's the type of "hello"? Traditionally, it's String, which is defined as type String = [Char]. Unfortunately, there are a number of limitations with this:

• It's a very inefficient implementation of textual data. We need to allocate extra memory for each cons cell, plus the characters themselves each take up a full machine word.

• Sometimes we have string-like data that's not actually text, such as ByteStrings and HTML.

To work around these limitations, GHC has a language extension called OverloadedStrings. When enabled, literal strings no longer have the monomorphic type String; instead, they have the type IsString a => a, where IsString is defined as:

class IsString a where
    fromString :: String -> a

There are IsString instances available for a number of types in Haskell, such as Text (a much more efficient packed String type), ByteString, and Html. Virtually every example in this book will assume that this language extension is turned on.

Unfortunately, there is one drawback to this extension: it can sometimes confuse GHC's type checker. Imagine we have:

{-# LANGUAGE OverloadedStrings, TypeSynonymInstances, FlexibleInstances #-}
import Data.Text (Text)

class DoSomething a where
    something :: a -> IO ()

instance DoSomething String where
    something _ = putStrLn "String"

instance DoSomething Text where
    something _ = putStrLn "Text"

myFunc :: IO ()
myFunc = something "hello"

Will the program print out String or Text? It's not clear. So instead, you'll need to give an explicit type annotation to specify whether "hello" should be treated as a String or Text.

Type Families

The basic idea of a type family is to state some association between two different types. Suppose we want to write a function that will safely take the first element of a list. But we don't want it to work just on lists; we'd like it to treat a ByteString like a list of Word8s. To do so, we need to introduce some associated type to specify what the contents of a certain type are.

{-# LANGUAGE TypeFamilies, OverloadedStrings #-}
import Data.Word (Word8)
import qualified Data.ByteString as S
import Data.ByteString.Char8 () -- get an orphan IsString instance

class SafeHead a where
    type Content a
    safeHead :: a -> Maybe (Content a)

instance SafeHead [a] where
    type Content [a] = a
    safeHead [] = Nothing
    safeHead (x:_) = Just x

instance SafeHead S.ByteString where
    type Content S.ByteString = Word8
    safeHead bs
        | S.null bs = Nothing
        | otherwise = Just $ S.head bs

main :: IO ()
main = do
    print $ safeHead ("" :: String)
    print $ safeHead ("hello" :: String)

    print $ safeHead ("" :: S.ByteString)
    print $ safeHead ("hello" :: S.ByteString)

The new syntax is the ability to place a type inside of a class and instance. We can also use data instead, which will create a new datatype instead of reference an existing one.

Template Haskell

Template Haskell (TH) is an approach to code generation. We use it in Yesod in a number of places to reduce boilerplate, and to ensure that the generated code is correct. Template Haskell is essentially Haskell which generates a Haskell Abstract Syntax Tree (AST).

Writing TH code can be tricky, and unfortunately there isn't very much type safety involved. You can easily write TH that will generate code that won't compile. This is only an issue for the developers of Yesod, not for its users. During development, we use a large collection of unit tests to ensure that the generated code is correct. As a user, all you need to do is call these already existing functions. For example, to include an externally defined Hamlet template, you can write:

$(hamletFile "myfile.hamlet")

(Hamlet is discussed in the Shakespeare chapter.) The dollar sign immediately followed by parantheses tell GHC that what follows is a Template Haskell function. The code inside is then run by the compiler and generates a Haskell AST, which is then compiled. And yes, it's even possible to go meta with this.

A nice trick is that TH code is allowed to perform arbitrary IO actions, and therefore we can place some input in external files and have it parsed at compile time. One example usage is to have compile-time checked HTML, CSS, and Javascript templates.

If your Template Haskell code is being used to generate declarations, and is being placed at the top level of our file, we can leave off the dollar sign and parentheses. In other words:

{-# LANGUAGE TemplateHaskell #-}

-- Normal function declaration, nothing special
myFunction = ...

-- Include some TH code
$(myThCode)

-- Or equivalently
myThCode

It can be useful to see what code is being generated by Template Haskell for you. To do so, you should use the -ddump-splices GHC option.

QuasiQuotes

QuasiQuotes (QQ) are a minor extension of Template Haskell that let us embed arbitrary content within our Haskell source files. For example, we mentioned previously the hamletFile TH function, which reads the template contents from an external file. We also have a quasi-quoter named hamlet that takes the content inline:

{-# LANGUAGE QuasiQuotes #-}

[hamlet|<p>This is quasi-quoted Hamlet.|]

The syntax is set off using square brackets and pipes. The name of the quasi-quoter is given between the opening bracket and the first pipe, and the content is given between the pipes.

Throughout the book, we will often times use the QQ-approach over a TH-powered external file since the former is simpler to copy-and-paste. However, in production, external files are recommended for all but the shortest of inputs as it gives a nice separation of the non-Haskell syntax from your Haskell code.

Summary

You don't need to be an expert in Haskell to use Yesod, a basic familiarity will suffice. This chapter hopefully gave you just enough extra information to feel more comfortable following the rest of the book.