Aside from installing the compiler (ghc), as well as a library for random number generation (MonadRandom), no setup is needed. We simply create a file to contain the code (named e.g. GuessingGame.hs), and then compile it (e.g. with ghc GuessingGame.hs). Once compiled, we run it with ./GuessingGame.1¹ That said, on some systems, it is a little tricky to get the compiler to use globally installed libraries – and we need the library for random number generation. Try using plain ghc first, and if that complains about hidden packages, it might be easier to use the Cabal build system. Cabal configures package visibility and manages a project-specific sandbox, like modern build tools for other languages. See the appendix for instructions if you need them.

To get going quickly, we’ll type in a hello, world program in our main module. It may look like this:

module Main where

main :: IO ()
main = do
  putStrLn "Hello, world!"

Compiling and running this, we get the expected output.

$ ghc GuessingGame.hs
Loaded package environment from ~/.ghc/x86_64-linux-9.4.5/environments/default
[1 of 2] Compiling Main             ( GuessingGame.hs, GuessingGame.o ) [Source file changed]
[2 of 2] Linking GuessingGame [Objects changed]

$ ./GuessingGame
Hello, world!

Walking through the code line by line, we start with a module declaration.

module Main where

All Haskell code lives in modules. The module named Main is treated specially by the compiler and is taken to be the module that contains the entrypoint. The entrypoint is further specified to be a constant named main in the module Main. The next line in our code declares this constant.

main :: IO ()

This declaration is called a type signature and it declares a constant named main, which contains a value of type IO (), indicating it is a computation that produces no value, but can perform i/o and other side effects.

The definition of this value is given on the next two lines.

main = do
  putStrLn "Hello, world!"

The do keyword opens up an indentation-sensitive block containing a sequence of side-effectful actions. In this case, we have just one action: the print statement.

As part of our soft start, we’ll read a guess from the user and print it back to them.

module Main where

main :: IO ()
main = do
  putStrLn "Guess the number!"
  putStrLn "Please input your guess."
  input <- getLine
  putStrLn ("You guessed: " <> input)

There’s not much new here.

input <- getLine

The getLine side effect action reads a string from the user. To extract the result of a side effect, we use the <- arrow in a do block. Then we present that guess back to the user.

putStrLn ("You guessed: " <> input)

The diamond operator <> is a generic concatenation operator that concatenates any sequences, including strings.

There’s still a problem though: we said the user was supposed to guess a value in the range 1–100, but we are not enforcing a particular range of numbers – worse, we are not even enforcing the input to be a number! The user can enter 9834 or hammock and the program will happily accept both. Let’s fix that.

First, we’ll create a new type representing small integers.2² This is some boilerplate code we got for free in Ada, since it has compiler support for range-limited integers. I’m sure there are third-party Haskell libraries for range-limited integers, but I want to show this pattern because it’s so common. To make it harder to write bugs, we will create a new module containing that type, and only export safe functions from it. This would be the contents of the file SmallInteger.hs.

module SmallInteger
  (SmallInteger, mkSmallInteger, unSmallInteger)
  where

import Control.Monad
import Data.Functor

newtype SmallInteger = SmallInteger { unSmallInteger :: Int }
  deriving (Eq, Ord)

mkSmallInteger :: Int -> Maybe SmallInteger
mkSmallInteger i =
  guard (i >= 1 && i <= 100) $> SmallInteger i

Some new things!

module SmallInteger
  (SmallInteger, mkSmallInteger, unSmallInteger)
  where

We are defining a module named SmallInteger, which exports three things:

1. The type SmallInteger which is like an integer except it holds only numbers in the range 1–100.
2. The function mkSmallInteger which takes a regular integer, verifies that it is within the expected range, and then constructs a SmallInteger value from it.
3. The function unSmallInteger which takes a SmallInteger and extracts the Int it was created from.

The SmallInteger type happens to have the same name as the SmallInteger module. This is no problem – the compiler knows if we are referring to a module or a type – but if it bothered us we could rename one of them.

import Control.Monad
import Data.Functor

This module imports some very common standard libraries, to get access to the guard function and $> operator, used in the module.

newtype SmallInteger = SmallInteger { unSmallInteger :: Int }

We define the data type SmallInteger as a newtype wrapper3³ A newtype wrapper is a kind of data type that exists only during type checking. In other words, it has no run-time performance cost, but prevents bugs by helping us not accidentally mix up our usages of Int and SmallInteger: if we try to assign an Int to a variable that holds a SmallInteger, or vice versa, the compiler will give us a type error. around Int. Since we export only the SmallInteger type name and not the SmallInteger data constructor, that constructor remains private to this module. This is a good thing: that constructor can be used to create a SmallInteger type of any size, but we want to ensure that they are only created in the right range. We will export another smart constructor for users of the module, that ensures all SmallInteger values that exist are created from integers in a limited range.

However, we do export the deconstructor function unSmallInteger, because that is always a safe operation.

deriving (Eq, Ord)

We know we will want to compare the relative size of SmallInteger values later on, so we make sure we ask ghc to generate implementations of the interfaces Eq and Ord. These define equality and ordering for a type, respectively. We could write these implementations manually, but it is far easier to ask the compiler to generate them for us.

mkSmallInteger :: Int -> Maybe SmallInteger
mkSmallInteger i =
  guard (i >= 1 && i <= 100) $> SmallInteger i

Finally, we have the smart constructor function mkSmallInteger which takes a plain Int, validates its range, and then returns a SmallInteger if it is valid, and nothing otherwise. It uses the guard–sequence idiom to perform that conditional return.

Perhaps of note is that this is the first function we have written that has not had a do block, because it is the first (and only) function we write that is pure! So much for the purity of Haskell being a problem …

Let’s use this new SmallInteger type in the guessing game. Going back to GuessingGame.hs4⁴ Which is where we will spend the rest of our time now that we have finished the SmallInteger module., it would now look like the following.

module Main where

import Text.Read (readMaybe)
import SmallInteger

main :: IO ()
main = do
  putStrLn "Guess the number!"
  putStrLn "Please input your guess."
  input <- getLine
  case readMaybe input >>= mkSmallInteger of
    Nothing ->
      putStrLn ("Guess must be a number within the range 1–100, not " <> input)
    Just guess ->
      putStrLn ("You guessed: " <> show (unSmallInteger guess))

We will want to import two things.

import Text.Read (readMaybe)
import SmallInteger

We import the readMaybe function from the standard library Text.Read. This function is used to parse simple values from strings – we will use it to get an Int out of the user input. We also import the module we just created for small integers.

case readMaybe input >>= mkSmallInteger of
  Nothing -> -- ...
  Just guess -> -- ...

Here’s a lot happining at once. We pass the input string into the readMaybe function, which will return Nothing if the user types something like hammock, and Just 5793 if the user types in 5793. The readMaybe function is generic, but the compiler knows to ask for the version of it that produces an Int, because the type system informs it that it is an Int we need.

We then chain this into the mkSmallInteger smart constructor with the bind operator >>=. The combination gives the following result:

1. If the user does not type in an integer at all, the code short-circuits to Nothing, bypassing the smart constructor entirely.
2. If the user types an integer but it is out of range, the smart constructor makes sure the whole expression still evaluates to Nothing.
3. However, if the user types in an integer in the right range, it evalutes to Just guess, where guess is the SmallInteger storing the user’s guess.

Then we show the user what guess they made.

putStrLn ("You guessed: " <> show (unSmallInteger guess))

Only strings can be concatenated with other strings, so we have to first unwrap the SmallInteger into a plain Int using its deconstructor function, and then we convert that Int to a string with the show function.

We also need a secret number for the user to try to guess. Random number generation is not part of the Haskell standard library, so we will use the MonadRandom library to get access to this.

module Main where

import Control.Monad.Random.Class (getRandomR)
import Data.Maybe (fromJust)
import Text.Read (readMaybe)
import SmallInteger

main :: IO ()
main = do
  secret <- fromJust . mkSmallInteger <$> getRandomR (1, 100)
  putStrLn "Guess the number!"
  putStrLn "Please input your guess."
  input <- getLine
  case readMaybe input >>= mkSmallInteger of
    Nothing ->
      putStrLn ("Guess must be a number within the range 1–100, not " <> input)
    Just guess -> do
      putStrLn ("You guessed: " <> show (unSmallInteger guess))
      putStrLn ("Secret number was: " <> show (unSmallInteger secret))

We have two new imports.

import Control.Monad.Random.Class (getRandomR)
import Data.Maybe (fromJust)

The getRandomR function takes a lower and upper bound, and then generates a random value between those bounds. The fromJust function asserts that a value exists: it returns the plain value if it exists, and throws an exception if it does not.

Then comes a line that can be a little confusing.

secret <- fromJust . mkSmallInteger <$> getRandomR (1, 100)

This is composed of two parts: to the left of the fmap operator <$> and to the right of it.

• To the right of <$>, we call the getRandomR function with the range 1–100. This returns a side effect object that will generate a random Int within that range.5⁵ How does it know to generate an Int rather than any other type of numeric value? Again, the type checker knows we expect an Int out of the process, and this informs the compiler to choose the implementation of random generation that produces Int values.
• To the left of <$>, we specify the transformation we want to apply to the result of the side effect before we extract its value. This transformation is composed from the two functions fromJust and mkSmallInteger. This composition will force the Int into a SmallInteger, throwing an exception if it is out of range – but we know it will never be out of range because we only generate values that are in range.

We could split this into two steps instead, by first generating a random Int, assigning it to a variable, and then creating another variable that contains the random value converted to a SmallInteger. The reason we don’t do that is it would make it possible to accidentally use the intermediate Int variable, which has the same numeric value as secret, but does not come with the same range guarantees. Thus we choose to perform the transformation directly on the result of getRandomR, before we even extract a value from it. The fmap operator <$> is what lets us specify such a transformation.

There’s not much that needs to change to tell the user whether they were too low or too high in their guess.

module Main where

import Control.Monad.Random.Class (getRandomR)
import Data.Maybe (fromJust)
import Text.Read (readMaybe)
import SmallInteger

main :: IO ()
main = do
  secret <- fromJust . mkSmallInteger <$> getRandomR (1, 100)
  putStrLn "Guess the number!"
  putStrLn "Please input your guess."
  input <- getLine
  case readMaybe input >>= mkSmallInteger of
    Nothing ->
      putStrLn ("Guess must be a number within the range 1–100, not " <> input)
    Just guess -> do
      putStrLn ("You guessed: " <> show (unSmallInteger guess))

      case compare guess secret of
        LT -> putStrLn "Your guess was too low."
        GT -> putStrLn "Your guess was too high."
        EQ -> putStrLn "Wow, you guessed right!"

      putStrLn ("Secret number was: " <> show (unSmallInteger secret))

The only difference is we’ve sandwhiched in a pattern match between the final two prints.

case compare guess secret of
  LT -> putStrLn "Your guess was too low."
  GT -> putStrLn "Your guess was too high."
  EQ -> putStrLn "Wow, you guessed right!"

We call the compare function which returns either LT, EQ, or GT depending on what the relative sizes of its two arguments are.

This is the execution of the program at the moment:

Guess the number!
Please input your guess.
57
You guessed: 57
Your guess was too low.
The secret number was: 63

Damn! I was close! Shame I didn’t get another go at it.

To give the user more chances to guess correctly, we’ll create a function of the game loop, such that we can jump back to the start of it after a failed guess.

module Main where

import Control.Monad.Random.Class (getRandomR)
import Data.Maybe (fromJust)
import Text.Read (readMaybe)
import SmallInteger

main :: IO ()
main = do
  secret <- fromJust . mkSmallInteger <$> getRandomR (1, 100)
  putStrLn "Guess the number!"
  gameLoop secret
  putStrLn ("Secret number was: " <> show (unSmallInteger secret))

gameLoop :: SmallInteger -> IO ()
gameLoop secret = do
    putStrLn "Please input your guess."
    input <- getLine
    case readMaybe input >>= mkSmallInteger of
      Nothing -> do
        putStrLn ("Guess must be a number within the range 1–100, not " <> input)
        gameLoop secret
      Just guess -> do
        putStrLn ("You guessed: " <> show (unSmallInteger guess))
        case compare guess secret of
          LT -> do
            PutStrLn "Your guess was too low."
            gameLoop secret
          GT -> do
            putStrLn "Your guess was too high."
            gameLoop secret
          EQ ->
            putStrLn "Wow, you guessed right!"

The main object is very short now, with only one new thing: after urging the user to guess the number, the main object calls the game loop function with the secret value.

gameLoop :: SmallInteger -> IO ()
gameLoop secret = do

The game loop itself is a function that takes the secret as a parameter, and produces a side effect object that does all of the user prompting. The only other difference is that the game loop function calls itself again when the user has failed to guess. This has the effect of giving the user another go.

In Ada, we then had to take care of the possibility of exceptions raised during input, e.g. because the user didn’t specify an integer, or an integer of the wrong size. With Haskell, these sorts of exceptions tend to be designed out of the software. So is true also with our program here. The language and library forced us to handle the exceptional cases up-front, and came with compile-time guarantees that we did.

There’s one thing that irks me about the above game loop: what if a sleepy programmer accidentally passes the wrong value for the secret when the function calls itself again? We can make this function run in an environment where it has implicit access to the secret as read-only data. Doing so is certainly overengineering for this particular problem, but helps show what production Haskell might look like.

module Main where

import Control.Monad.Random.Class (getRandomR)
import Control.Monad.Reader
import Data.Maybe (fromJust)
import Text.Read (readMaybe)
import SmallInteger

main :: IO ()
main = do
  secret <- fromJust . mkSmallInteger <$> getRandomR (1, 100)
  putStrLn "Guess the number!"
  runReaderT gameLoop secret
  putStrLn ("Secret number was: " <> show (unSmallInteger secret))

gameLoop :: ReaderT SmallInteger IO ()
gameLoop = do
  liftIO $ putStrLn "Please input your guess."
  input <- liftIO getLine
  case readMaybe input >>= mkSmallInteger of
    Nothing -> do
      liftIO $ putStrLn ("Guess must be a number within the range 1–100, not " <> input)
      gameLoop
    Just guess -> do
      liftIO $ putStrLn ("You guessed: " <> show (unSmallInteger guess))

      secret <- ask
      case compare guess secret of
        LT -> do
          liftIO $ putStrLn "Your guess was too low."
          gameLoop
        GT -> do
          liftIO $ putStrLn "Your guess was too high."
          gameLoop
        EQ ->
          liftIO $ putStrLn "Wow, you guessed right!"

This requires the mtl library for the Control.Monad.Reader module.

runReaderT gameLoop secret

Instead of giving the game loop the secret as an argument directly, it runs the gameLoop object in an environment where there is implicit access to the secret.

gameLoop :: ReaderT SmallInteger IO ()

The game loop is no longer a function, but a constant object of type ReaderT, which means it has implicit access to some value – in this case a SmallInteger. The IO indicates that it can also perform i/o, although now indirectly only.

liftIO $ putStrLn "Please input your guess."

Indeed, we now have to wrap any i/o effects in liftIO, to run them in this implicit-access environment.

gameLoop

When this object invokes itself, it no longer passes the secret explicitly. Great! Less room for passing it wrong.

secret <- ask

The value carried implicitly in this environment is accessed with the side-effectful action ask.

Again, this is overkill for a 20 line game loop where we can read all the code and make sure it never changes the secret between iterations. But if it was a more complicated, deeply nested loop, it is nice to have the compiler ensure that the value passed around is read only, across any number of iterations or cross-calls between functions.

In a very brief time, we have seen a lot of Haskell beyond the basics:

• How to create a module for a custom, limited type, with a public smart constructor that makes the type impossible to misuse.
• How to chain computations that might return nothing using the bind operator >>=.
• But also how to assert that there is a result from a computation when we know there must be, using the fromJust function.
• How to generate random values in a range using getRandomR.
• How to apply transformations on the results of side effects before we extract the result, using the fmap operator <$>.
• How to use recursion to iterate until a condition becomes true.
• That we can run side-effectful actions in an environment where they have implicit access to values by using ReaderT.

I don’t expect you to understand all of the above things. But I hope that they don’t look too crazy, all things considered. Haskell is a nice language to work with, especially when it comes to larger real-world applications with complicated maintenance histories.

As we have seen, purity is not a problem. Almost everything we wrote in this exercise was impure, i/o-laden code. The only pure code we wrote was the SmallInteger module – and boy would that be a useful module in a larger application, where we want to ensure no integers outside of the desired range sneak in.

If we run into problems with packages being hidden, we can build this project with Cabal. To do that, we need to create a file called guessinggame.cabal and put it in the same directory as GuessingGame.hs. It needs to contain something like

cabal-version: >= 1.2
name: guessinggame
version: 0.1.0.0
build-type: Simple

executable guessinggame
  main-is: GuessingGame.hs
  build-depends: base, MonadRandom

This is not the best practice in terms of Cabal files, but the absolute minimum we can proceed with. To build the program with cabal, run cabal build. Then to run the executable produced, run $(cabal list-bin guessinggame). A shortcut to perform both steps at once is cabal run.