You’re here to learn (or learn about) Haskell. Before getting into the nitty-gritty details of syntax and semantics, let’s briefly go over who you are and what Haskell is.

Haskell is a general-purpose statically-typed pure functional programming language. Let’s break that down:

Haskell is a fairly unusual language. Many people liken learning Haskell to learning to program all over again; do not be discouraged if it takes a long time and a lot of effort. For many programmers, picking up a new language is a matter of finding an interesting project and implementing it in their new language of choice; while this is possible with Haskell, many aspects of the language require a more dedicated sort of study.

Now that we’re acquainted with Haskell, who are you? For the purposes of this guide, you are a somewhat experienced programmer who has worked with static type systems and functional languages and has a few years of general programming experience under their belt. Knowing languages such as Scheme, ML, OCaml may be helpful. If you don’t quite fit this bill, you may find parts of this guide to be very difficult. In this case, books on Haskell such as Learn You a Haskell and Real World Haskell may be useful to supplementing your understanding.

The Haskell language has gone through several revisions. It was initially designed to be a standard for researchers exploring new programming language features. The first few iterations were the realm solely of researchers; modern Haskell really began with the Haskell 98 language standard. Several extensions were integrated into the standard later, leading to the Haskell 2010 language standard.

Although there are several Haskell compilers, GHC (the Glasgow Haskell Compiler) is by far the most commonly used and most featureful. Many extensions to the Haskell language are implemented only in GHC, so for the rest of this guide, you can assume that "Haskell" really means "Haskell with all the extensions and libraries that GHC offers".

With that in mind, let’s get started! Install GHC, open a text file in your favorite editor, and enter the following program in a file called Test.hs (or another with the same extension):

Next, compile this with GHC by entering the following command into your shell:

Note that the precise command may differ depending on your operating system and environment. The commands presented here should work under most Unix-like operating systems (Linux and Mac OS X), and serve as a good template for commands for other systems.

If you run this, you should see your program printing "Hello", as expected:

Congratulations! You’ve written your first Haskell program. This program is deceptively simple, and in the next few sections we’ll explore what exactly this program does and how it does it, as well as look at many other features of the Haskell language.

Let’s take a look at another small Haskell program:

In this program, we declare four values: an integer, a string, a character, and a tuple containing three of these. Each of these has a different type. Note that all values in Haskell have some sort of type; there cannot be a value without a type. We don’t always have to write what the types are, though, because the compiler can look at how a value is used and guess what type it must have. Although the compiler is smart enough to infer the types for this simple program, we can explicitly annotate each top-level declaration with a type signature as well.

More likely than not, when you start programming Haskell, you will find that the type system gets in your way. However, as you get used to Haskell and its type system, you will find that the type system and the compiler is a huge resource. You will be able rely on the type system to catch many common programming errors - in some ways, it will be like you have a friend watching over your shoulder as you write code, pointing out mistakes that are obvious in retrospect.

In order to use the type system, you can annotate values with types and write type declarations. In the example program above, we wrote a type declaration for every top-level value declaration we had. However, we could also have annotated every value:

We’ve already seen top-level value declarations along the following lines:

However, there’s no reason that these values must be expressed using just literals, even if they aren’t functions. For example, we can use a where clause to use some local variable bindings:

Computing the values of one and two cannot have side effects, so it is unimportant what order they are declared in. In other languages, you might say that the variable two is created after the variable one, but in Haskell that is irrelevant — the two variables are not ordered in any way, and are just evaluated when their values are needed.

In addition to providing where blocks which can be attached to declarations, Haskell provides let .. in blocks that together form an expression. For example, we could rewrite the example above as follows:

let is used when you are creating an expression, and where is used when you have a declaration you can attach the where to; other than that, the meaning of these two blocks is almost identical.

Both let and where blocks allow for type declarations, so the following code would also be valid:

In Haskell, functions are defined exactly like the numbers and strings we’ve already seen, with a few bits of syntactic sugar to make it easier. For instance, a function that adds one to an integer can be written as follows:

However, writing all functions as anonymous functions would be very tedious. To avoid this, you can simply put the argument to the function on the left hand side of the equal sign, yielding the following cleaner code:

A complete program using function declarations of this style follows:

In Haskell, all functions are single-argument functions. Every function takes one argument and returns one value. However, we can still emulate multi-argument functions! For example, consider the following function, which adds two numbers:

When we pass an Int to add, we get back another function. If we pass another Int to that function, we get the sum of the two integers as a result:

In this regard, Haskell’s single-argument functions allow us to easily emulate multi-argument functions. In order to make this easier, Haskell provides us with syntactic sugar for these anonymous function declarations, just like it does for single-argument functions. Thus, we can write the function and it’s use as follows:

Using simple operators such as + and * is all well and good, but most real-world functions involve a lot of decision-making and branching based on the values they are passed as arguments. In Haskell, this decision-making can take a number of forms.

The most common form is known as pattern matching. Pattern matching allows you to test whether your data conforms to some sort of fixed pattern in its values or structure, and execute different code depending on the pattern it matches. For example, in the following classic example, we pattern match on the argument to determine what to do:

Pattern matching works on things besides numeric literals as well, such as strings, characters, and tuples, as demonstrated by the following ridiculous function:

In addition to pattern matching in the function declaration, Haskell provides the case .. of statement for pattern matching:

In addition to pattern matching (which tests for structure equality), Haskell provides function guards for deciding between different pieces of a function declaration. For example, a comparison function could be written like this:

Finally, if none of these styles match what you want to do, Haskell provides a conventional if .. then .. else statement. Since the result of this statement is an expression, the then and else must both be present, and the results must have the same type (otherwise the entire if would not be well-typed). Thus, the comparison function could also be written using if statements:

The Haskell if statement is much closer to the ternary ?: operator from C-style languages than it is to the traditional if statements found in most languages.

You’ve now been introduced to most of the various control structures that Haskell provides. The control structures provided are fairly simple; there is no looping or object-orientation. There are a few more advanced language features we will look at in the future (type-classes, list comprehensions), but the ones here are more than enough to get you started. In the next section, we’ll take a break from control structures and look at creating and using our own custom data types.

The data keyword is quite versatile. For example, constructors can have multiple arguments. Like before, the types of the arguments are spelled out in the data declaration:

In this declaration, we’ve created a type called SecondType. It has one constructor, also called SecondType, which takes an integer, a string, and a character. The use of this multi-argument constructor and type is very similar to the single-argument case:

The data keyword also allows you to create types with multiple constructors. Each constructor requires its own set of constituent types. If you’ve worked with C or C++, you can think of multi-constructor types as a sort of well-typed union. In order to create multiple constructors, you delimit the constructors with a vertical bar |:

This type (called Third) has three constructors, Third1, Third2, and Third3. They take an integer, a string, and two characters, respectively.

We can create values of type Third in three different ways, and we can pattern match on multi-constructor data types to find out which constructor was used:

Some types, such as our hypothetical Letter or Digit types, store a fixed type and amount of data (in this case, one letter and one digit). However, sometimes we need to store different types of data, or different amounts of data.

In order to store different types of data, Haskell’s types are allowed to be parametric. Parametric types are similar to various generic programming systems in imperative languages (generics in Java, some uses of templates in C++, and so on). For example, the following type represents a "nullable" value of some type a:

This type has one type parameter, a. The parameter is a type variable and comes after the type name, just like an argument to a function. Like normal variables, type variables must start with a lowercase letter or underscore.

This type also has two constructors. The first, Nothing, is similar to null, nil, or None from other languages, and represents the absence of a value. The second constructor is just a wrapper around a value of type a, and represents the fact that a value does exist.

We can make values of this type like this:

Using type parameters, we can create types that represent abstract ideas and data structures, such as nullable values, lists, or trees.

Note that in order to make the most of these data structures, you will sometimes need to create recursive data structures. For example, a binary tree can be represented as follows:

This tree has a value of type a at every node. Each node is either a Leaf (in which case it is a terminal node) or a Branch (in which case it has two subtrees). However, note that the subtrees are also of type BinaryTree a. This type is recursive, as each binary tree can store yet another binary tree, which allows for trees of arbitrary depth. We will deal with a similar data structure extensively towards the end of this guide.

In a typical Haskell application, some types will be large, with multiple branches separated by | and multiple constituents in each branch. However, many types will be small wrappers around existing types, just meant to be used for type safety. For example, in order to prevent someone from adding together an age and a weight, you might want to create separate data types for each:

If we write 1.0 + 2.0, the compiler will produce 3.0, regardless of what the 1.0 and 2.0 were meant to represent. However, if we try to write Age 1.0 + Weight 2.0, we will get a type error, because the operation we are trying to do is meaningless. In order to facilitate simple wrapper types like Age and Weight, Haskell provides the newtype keyword:

A newtype declaration is identical to a simple data declaration. However, there can only be one constructor with one constituent type in it, which enforces the fact that newtype types are just wrappers. In exchange for this restriction, the compiler guarantees that there will be no runtime cost associated with using a newtype — unlike data, the constructors and de-constructors are guaranteed to be optimized away by the compiler.

Now that you’ve familiarized yourself with data types in Haskell, read through the following short application that deals with managing a list of people:

This small program does a lot! However, we can shorten it and make it a bit clearer using record types. Take a look at getWeight in the program above: this is effectively boilerplate. We extract the same field from each constructor, causing us to duplicate code for every constructor we have. Also, if we wanted to manipulate age and address, we’d have to write a function that looked more or less identical for each of those fields. Instead of writing these ourselves, we can give the constituent types of each constructor a name, and let Haskell generate these functions for us. Using record notation, we could rewrite the data declaration as follows:

To use our new functionality, we can simply get rid of getWeight and replace with just weight:

We can still pattern match on records and create new values in the same way we did before. However, we can also pattern match on fields themselves. We could write the following function to retrieve a person’s location:

We can use a similar syntax for creating new records. For example, we could define charlie as follows:

This is a little bit more verbose, but can be clearer for complex data types and will not break if you add more data types somewhere in the middle of the product type.

A linked list is a list in which each element is stored in its own node. Each node also has a pointer or reference to the next node in the list.

The diagram above shows a linked list with three nodes. The first node contains a one and a link to the second node. The second node contains a two, and a link to the third node. The third node contains a three, and a link to the fourth and last node. The fourth node is a special symbol "Nil" indicating the end of the list. (An empty list would be represented as just the symbol "Nil").

We could encode a recursive data structure like this one in Haskell as follows:

We could then create the list containing 1, 2, and 3 as follows:

However, because linked lists are so common in functional programming, Haskell has special syntax for lists. Instead of Nil, you write [] (the empty list). Instead of Node value next, you write value : next, with : acting as an infix data constructor. In addition, lists of known elements can be written naturally with the elements inside square brackets, separated by commas. The list of the numbers 1, 2, 3 would just be written [1, 2, 3]. Instead of List a, the type of a list of a values is [a]. All of the following options are valid and semantically identical:

For the case of numbers, you can also write [x..y] to create a list of integers from x going to y. For example, the list of all integers between one and ten can be written as [1..10]. The notation [x, x'..y] indicates a list of values starting at x, incrementing by x' - x, and going until y. For example, all even numbers up to 10 can be written as [0, 2..10]:

In order to work with lists, we use pattern matching, like with most data structures. For example, we can use pattern matching to extract the head and tail of a list:

We can also do somewhat more advanced pattern matching. For example, suppose we have a two-element list [1, 2] and we want to compute the sum of the two elements. Here are two ways we could do that:

Next, we’ll take a look at some of the fundamental operations available on lists. These are the bread and butter of functional programming; as you continue with Haskell, you’ll encounter these functions on a daily basis.

Suppose you declare a list of integers:

We’d like to perform two steps:

We’ll handle each of these steps in order.

In a lazy language, expressions are not evaluated until their value is needed. For example, consider the following code:

In an eager language, the expression y + z will be evaluated first. All variables already store fully evaluated values, so nothing needs to be done for f or x (besides fetching their values). Then, f will be called with the values of x and y + z as arguments. f will compute some result, which is then passed to the print function to be written to the screen.

Most eager languages will have some sort of consistent ordering strategy; in Python, for example, arguments to a function are evaluated from left to right. In a lazy language, we have no guarantees about what order things will be evaluated in. Instead, the order of evaluation depends on when and if the value of an expression is needed.

Consider once more our example:

This example is a single expression which calls the print function with some argument. The entire expression will be unevaluated until execution of the program reaches the print function. Since the print function requires its argument’s value to format its output, the argument will be evaluated.

Before the expression f x (y + z) can be evaluated, the value of f must be known. Unlike an eager language, where you know every variable stores a fully computed value, a variable in a lazy language may store a value that has yet to be computed. (These unevaluated values are often known as thunks.)

For example, suppose that f and x were defined like this:

To evaluate f x (y + z) we must first evaluate f. In evaluating f, we see that the value of f depends on a condition in an if statement which depends on the value of x. Once we see that we need to evaluate x, we pause evaluating f and take a detour to find the value of x. Once x is evaluated (to a value of 300), the if statement can be evaluated, and f will be evaluated to \a b -> a + b.

This value is then effectively substituted into our original expression, turning f x (y + z) into (\a b -> a + b) x (y + z). We then simplify this by applying the anonymous function to its arguments, yielding x + (y + z). In order to compute this final result, we must go back and make sure that x, y, and z are evaluated. We know that x has already been evaluated, since we needed it to evaluate f. Thus, y and z are evaluated next, and finally the entire expression is evaluated. Once the value of the expression is known, the print function can use the value to format its output and write it to the screen.

This cartoon is of course not exactly what happens when Haskell code is run; however, it is fairly close. In an eager language, all expressions are evaluated as soon as they are encountered. In a lazy language, expressions are only evaluated when their results are needed.

Lazy evaluation can be quite confusing to work with and reason about, especially for programmers who are used to eagerly-evaluated languages. However, lazy languages permit some very elegant algorithms, abstractions, and data structures, which truly make laziness worthwhile. (Haskell is lazy by default; there are ways to enforce order of evaluation and use eager evaluation. These are often useful for optimization of memory usage or runtime. We’ll talk more about these functionalities later.)

In order to build some intuition about laziness and lazy data structures, let’s fire up GHCi. GHCi is a Haskell interpreter which lets you enter expressions and let statements in an interactive REPL. Enter the following code into GHCi:

You may notice that when you enter this line, it evaluates instantaneously, with practically no delay. This is because nothing has been evaluated yet — as far as Haskell is concerned, it knows that total means sum [1..1000000], but it has not actually evaluated that sum yet.

We can force Haskell to evaluate total by doing something with it:

You’ll notice that it took quite a while for it to evaluate that statement. Before being able to print the value, it had to sum up a list of a million numbers. Try entering print total again — you’ll notice that it runs much faster, now that total has been evaluated.

You can inspect the underlying structure of a variable using the GHCi :sprint directive. For example, if you run

you should see that total has been evaluated to a large integer value. However, you can see unevaluated expressions as well:

This should output

which simply means that the value of ints has not been evaluated yet.

Try showing the first element of ints by typing head ints into GHCi. Once you do this, the first value will be evaluated. You can examine which bits of ints have been evaluated:

This should yield the string ints = 1 : _. This means that ints is a list — recall that the : is an infix data constructor that takes a value on the left and a list on the right, and is used for constructing linked lists. In this case, the first value is 1, but the rest of the list is unevaluated. In order to evaluate a few more elements, you can use the take function, which takes elements from the front of a list:

Now, :sprint should yield

which again means that the first three elements are 1, 2, and 3, and the rest of the list hasn’t been evaluated.

Finally, if we print ints, using :sprint should show you that the entire list has been evaluated:

One of the strangest consequences of laziness is that our data structures are no longer restricted by the amount of memory we have, as long as we never evaluate and hold in memory the entire data structure! In fact, we can very easily have infinite lists:

When encountering expressions like these, think about what would happen if they were evaluated. In this case, consider the expression take 3 integers, which gets the first three elements of this list. First, you would compute head integers to get the very first element. According to our definition 1 : map (+1) integers, the first element is just 1. Next, we would get the second element. The second element is the head of the tail. Since the tail is map (+1) integers, the second element is head (map (+1) integers). As we saw before, map applies the function (+1) to every element of integers. We have already computed that the first element of integers is 1, so the first element of map (+1) integers must be 2. We can compute the third element of integers in exactly the same way, and find that take 3 integers is just [1, 2, 3].

You can use :sprint along the way to look at how much of integers has actually been evaluated. Finally, try evaluating the following code:

You should find that GHCi tries to print an infinite list, dumping output to the screen until you interrupt it (which you can do with Ctrl-C).