Haskell, explained by the code you already write

-- Three type signatures, three promises the compiler enforces.

-- Same name in, same greeting out, every single time. This function cannot
-- print, cannot read a file and cannot throw a surprise exception, because
-- none of that appears in its type.
greet :: String -> String
greet name = "Hello, " ++ name ++ "!"

-- The answer might be missing, and Maybe says so out loud. Every caller has
-- to decide what happens when the name is not there.
lookupAge :: String -> [(String, Int)] -> Maybe Int
lookupAge = lookup

-- IO in the type is the compiler's way of saying "this one touches the
-- outside world". Nothing without IO in its type is allowed to call it.
main :: IO ()
main = putStrLn (greet "world")

# One installer for the whole toolchain, on macOS, Linux and WSL.
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh

# It sets up four things:
#   ghc     the compiler
#   cabal   the build tool and package manager
#   hls     the language server, for editor support
#   stack   an alternative build tool, optional

ghcup tui          # pick and switch versions from a menu
ghc --version
cabal --version

-- Every runnable program exports main, and main has type IO ().
-- The () is the empty tuple, Haskell's "nothing useful to return".
module Main (main) where

main :: IO ()
main = do
  putStrLn "Hello from GHC."
  putStrLn (unwords (replicate 3 "lambda"))

# Start the interactive prompt. It is a calculator, a type inspector and a
# scratchpad, and it is where most Haskell learning actually happens.
ghci

# Run a single file without building a project.
runghc hello.hs

# Compile it to a binary instead.
ghc -O2 hello.hs -o hello
./hello

ghci> 2 + 2 * 10
22
ghci> :type "hello"
"hello" :: String
ghci> :type (++)
(++) :: [a] -> [a] -> [a]
ghci> let name = "ada"
ghci> "hi " ++ name
"hi ada"
ghci> :type map
map :: (a -> b) -> [a] -> [b]
ghci> map (* 2) [1, 2, 3]
[2,4,6]
ghci> :info Bool
type Bool :: *
data Bool = False | True
ghci> :load Lists.hs
[1 of 1] Compiling Lists
Ok, one module loaded.
ghci> :reload
ghci> :quit

-- Every declaration in the comparison table, in one compilable file.
module Rosetta where

import qualified Data.Map.Strict as Map

count :: Int
count = 42

ratio :: Double
ratio = 3.14

flag :: Bool
flag = True

label :: String
label = "hi"

primes :: [Int]
primes = [2, 3, 5, 7]

point :: (Int, String)
point = (1, "one")

ages :: Map.Map String Int
ages = Map.fromList [("ada", 36), ("grace", 45)]

-- No null and no undefined. A missing value has its own type.
middleName :: Maybe String
middleName = Nothing

-- No exceptions for expected failures. The error type is in the signature.
parsed :: Either String Int
parsed = Right 5

-- Functions are values, and their type is written with arrows.
add :: Int -> Int -> Int
add x y = x + y

-- A type synonym is a nickname, not a new type.
type Name = String

-- A newtype is a new type with no runtime cost, so Name and Email cannot
-- be swapped by accident.
newtype Email = Email String

ghci> :type 42
42 :: Num a => a
ghci> :type (42 :: Int)
(42 :: Int) :: Int
ghci> :type words
words :: String -> [String]
ghci> :type filter even
filter even :: Integral a => [a] -> [a]
ghci> :type lookup "ada"
lookup "ada" :: [(String, b)] -> Maybe b
ghci> "one" + 1
error: No instance for (Num String) arising from a use of '+'
ghci> :type foldr
foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b

module Functions where

-- A signature, then an equation. No return keyword: the body is the result.
double :: Int -> Int
double x = x * 2

-- Arguments are separated by arrows, not commas, and applied with spaces.
area :: Double -> Double -> Double
area width height = width * height

-- Guards test conditions in order and pick the first that holds.
-- `otherwise` is not a keyword, it is just a name for True.
classify :: Int -> String
classify n
  | n < 0     = "negative"
  | n == 0    = "zero"
  | n < 10    = "small"
  | otherwise = "large"

-- `where` names intermediate values for the whole definition.
bmiTell :: Double -> Double -> String
bmiTell weight height
  | bmi <= 18.5 = "underweight, bmi " ++ show bmi
  | bmi <= 25.0 = "normal, bmi " ++ show bmi
  | otherwise   = "overweight, bmi " ++ show bmi
  where
    bmi = weight / height ^ (2 :: Int)

-- `let ... in` is an expression, so it can appear anywhere a value can.
cylinderArea :: Double -> Double -> Double
cylinderArea radius height =
  let side = 2 * pi * radius * height
      cap  = pi * radius ^ (2 :: Int)
  in side + 2 * cap

-- Any two argument function can be written between its arguments.
remainder :: Int -> Int -> Int
remainder a b = a `mod` b

-- Any operator can be written in front of them.
plus :: Int -> Int -> Int
plus = (+)

-- Anonymous functions start with a backslash, which is meant to look like
-- the lambda it stands for.
addOneToAll :: [Int] -> [Int]
addOneToAll = map (\n -> n + 1)

ghci> :type 42
42 :: Num a => a
ghci> :type (42 :: Int)
(42 :: Int) :: Int
ghci> :type words
words :: String -> [String]
ghci> :type filter even
filter even :: Integral a => [a] -> [a]
ghci> :type lookup "ada"
lookup "ada" :: [(String, b)] -> Maybe b
ghci> "one" + 1
error: No instance for (Num String) arising from a use of '+'
ghci> :type foldr
foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b

module Patterns where

-- One definition per shape of input. GHC warns when a case is missing.
describe :: [String] -> String
describe []          = "nothing"
describe [x]         = "just " ++ x
describe [x, y]      = x ++ " and " ++ y
describe (x : rest)  = x ++ " and " ++ show (length rest) ++ " more"

-- `case` is the same idea written as an expression.
httpMessage :: Int -> String
httpMessage code = case code of
  200 -> "OK"
  404 -> "Not Found"
  500 -> "Server Error"
  _   -> "Status " ++ show code

-- Tuples come apart exactly the way Python unpacks them.
distance :: (Double, Double) -> (Double, Double) -> Double
distance (x1, y1) (x2, y2) = sqrt ((x2 - x1) ** 2 + (y2 - y1) ** 2)

-- An as-pattern keeps the whole value while still matching its shape.
stutter :: String -> String
stutter whole@(c : _) = c : whole
stutter []            = []

-- Guards can be attached to any pattern.
grade :: Int -> Char
grade score
  | score >= 90 = 'A'
  | score >= 80 = 'B'
  | score >= 70 = 'C'
  | otherwise   = 'F'

-- Comparing returns one of three constructors instead of an integer, so
-- there is no "what does -1 mean again" moment.
signOf :: Int -> String
signOf n = case compare n 0 of
  LT -> "negative"
  EQ -> "zero"
  GT -> "positive"

module Lists where

import Data.Char (toUpper)

-- A list holds one type of thing, and the type says which.
primes :: [Int]
primes = [2, 3, 5, 7, 11]

-- (:) puts one element on the front. Lists are linked lists, so this is
-- cheap while appending to the end is not.
withOne :: [Int]
withOne = 1 : primes

-- Ranges. Two starting elements set the step.
countdown :: [Int]
countdown = [10, 9 .. 1]

evens :: [Int]
evens = [0, 2 .. 20]

letters :: String
letters = ['a' .. 'e']

-- Laziness makes an endless list an ordinary value, as long as something
-- eventually stops taking from it.
squares :: [Int]
squares = take 10 [n * n | n <- [1 ..]]

-- A comprehension reads like the set builder notation from a maths class:
-- outputs on the left, generators and filters on the right.
pythagorean :: [(Int, Int, Int)]
pythagorean =
  [ (a, b, c)
  | c <- [1 .. 20]
  , b <- [1 .. c]
  , a <- [1 .. b]
  , a * a + b * b == c * c
  ]

-- A pattern in a generator quietly skips anything that does not match,
-- which is a safe way to take the first letter of each word.
initials :: String -> String
initials sentence = [c | (c : _) <- words sentence]

shout :: String -> String
shout = map toUpper

-- The list functions you will reach for daily. All of them return new
-- lists; none of them change the one you passed in.
summary :: [Int] -> (Int, Int, Int, [Int], [Int])
summary xs =
  ( length xs
  , sum xs
  , product xs
  , take 3 xs
  , reverse xs
  )

ghci> take 5 [1 ..]
[1,2,3,4,5]
ghci> [x * x | x <- [1 .. 10], even x]
[4,16,36,64,100]
ghci> zip "abc" [1, 2, 3]
[('a',1),('b',2),('c',3)]
ghci> words "the quick brown fox"
["the","quick","brown","fox"]
ghci> unwords (reverse (words "the quick brown fox"))
"fox brown quick the"
ghci> splitAt 3 [1 .. 6]
([1,2,3],[4,5,6])
ghci> takeWhile (< 20) (map (* 3) [1 ..])
[3,6,9,12,15,18]

module Recursion where

-- The base case first, then the case that shrinks the problem.
factorial :: Integer -> Integer
factorial 0 = 1
factorial n = n * factorial (n - 1)

-- Adding up a list, spelled out. `sum` does this for you.
mySum :: Num a => [a] -> a
mySum []       = 0
mySum (x : xs) = x + mySum xs

-- An accumulator argument replaces the variable you would have mutated.
-- This one is tail recursive, so GHC turns it into a loop.
myReverse :: [a] -> [a]
myReverse = go []
  where
    go acc []       = acc
    go acc (x : xs) = go (x : acc) xs

-- Quicksort, the example every Haskell book opens with, and fairly so:
-- it is the definition of the algorithm rather than an implementation.
quickSort :: Ord a => [a] -> [a]
quickSort []              = []
quickSort (pivot : rest)  = quickSort smaller ++ [pivot] ++ quickSort larger
  where
    smaller = [x | x <- rest, x <= pivot]
    larger  = [x | x <- rest, x > pivot]

-- A list that refers to itself. Laziness means only the part you look at
-- is ever built.
fibs :: [Integer]
fibs = 0 : rest
  where
    rest = 1 : zipWith (+) fibs rest

collatz :: Int -> [Int]
collatz 1 = [1]
collatz n
  | even n    = n : collatz (n `div` 2)
  | otherwise = n : collatz (3 * n + 1)

-- Mutual recursion is allowed, and order of definition never matters.
isEven :: Int -> Bool
isEven 0 = True
isEven n = isOdd (n - 1)

isOdd :: Int -> Bool
isOdd 0 = False
isOdd n = isEven (n - 1)

module HigherOrder where

import Data.Char (toLower, toUpper)
import Data.List (foldl', sortOn)

names :: [String]
names = ["ada", "grace", "alan", "barbara"]

-- Functions are ordinary values, so they can be passed in like any other.
shouted :: [String]
shouted = map (map toUpper) names

shortNames :: [String]
shortNames = filter ((<= 4) . length) names

-- foldr rebuilds a list with your own operator in place of (:) and your own
-- value in place of []. sum is foldr (+) 0, and so is almost everything else.
total :: [Int] -> Int
total = foldr (+) 0

longest :: [String] -> String
longest = foldr keepLonger ""
  where
    keepLonger candidate best
      | length candidate > length best = candidate
      | otherwise                      = best

-- foldl' is the strict left fold. Reach for it when folding a long list of
-- numbers, because it does not build a tower of pending additions.
average :: [Double] -> Double
average xs = added / count
  where
    (added, count) = foldl' step (0, 0) xs
    step (runningTotal, seen) x = (runningTotal + x, seen + 1)

-- Every function of two arguments is a function returning a function, so
-- supplying one argument early is normal rather than clever.
addTen :: Int -> Int
addTen = (+ 10)

tenPercentOff :: [Double] -> [Double]
tenPercentOff = map (* 0.9)

-- Composition builds a pipeline that runs right to left.
slug :: String -> String
slug = map dashSpaces . map toLower
  where
    dashSpaces ' ' = '-'
    dashSpaces c   = c

-- ($) applies a function to everything on its right, which removes the
-- pile of closing parentheses.
loudLengths :: [String] -> String
loudLengths xs = unwords $ map show $ map length xs

byLength :: [String] -> [String]
byLength = sortOn length

-- zipWith walks two lists together and stops at the shorter one.
runningPairs :: [Int] -> [Int]
runningPairs xs = zipWith (+) xs (drop 1 xs)

ghci> foldr (+) 0 [1, 2, 3, 4]
10
ghci> foldr (:) [] [1, 2, 3]
[1,2,3]
ghci> foldr (\x acc -> show x ++ "," ++ acc) "" [1, 2, 3]
"1,2,3,"
ghci> foldl (-) 0 [1, 2, 3]
-6
ghci> foldr (-) 0 [1, 2, 3]
2
ghci> :type foldMap
foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m
ghci> sum [1 .. 100]
5050

module SafeValues where

import Data.Maybe (fromMaybe, mapMaybe)
import Text.Read (readMaybe)

people :: [(String, Int)]
people = [("ada", 36), ("grace", 45)]

-- lookup cannot find every key, so its type admits that.
ageOf :: String -> Maybe Int
ageOf name = lookup name people

-- Pattern matching forces both cases into the open. There is no way to
-- forget the missing one, because the code will not compile.
describeAge :: String -> String
describeAge name = case ageOf name of
  Nothing  -> name ++ " is not on the list"
  Just age -> name ++ " is " ++ show age

-- fromMaybe supplies a fallback in one expression.
ageOrZero :: String -> Int
ageOrZero name = fromMaybe 0 (ageOf name)

-- Maybe is a Functor, so a pure function can be applied inside it.
nextBirthday :: String -> Maybe Int
nextBirthday name = fmap (+ 1) (ageOf name)

-- mapMaybe keeps the successes and drops the failures in one pass.
knownAges :: [String] -> [Int]
knownAges = mapMaybe ageOf

-- Either carries a reason for the failure instead of just its fact.
data AgeError
  = NotANumber String
  | OutOfRange Int
  deriving (Show, Eq)

parseAge :: String -> Either AgeError Int
parseAge raw = case readMaybe raw of
  Nothing -> Left (NotANumber raw)
  Just n
    | n < 0 || n > 130 -> Left (OutOfRange n)
    | otherwise        -> Right n

-- In a do block over Either, the first Left stops everything after it and
-- becomes the result. This is early return without the return statement.
parseCouple :: String -> String -> Either AgeError (Int, Int)
parseCouple first second = do
  a <- parseAge first
  b <- parseAge second
  pure (a, b)

-- Turning one into the other is a normal function call.
toMaybe :: Either AgeError Int -> Maybe Int
toMaybe = either (const Nothing) Just

ghci> lookup "ada" [("ada", 36), ("grace", 45)]
Just 36
ghci> lookup "alan" [("ada", 36), ("grace", 45)]
Nothing
ghci> fmap (+ 1) (Just 36)
Just 37
ghci> fmap (+ 1) Nothing
Nothing
ghci> (+) <$> Just 1 <*> Just 2
Just 3
ghci> (+) <$> Just 1 <*> Nothing
Nothing
ghci> Just 36 >>= \age -> if age > 18 then Just "adult" else Nothing
Just "adult"
ghci> sequence [Just 1, Just 2, Just 3]
Just [1,2,3]
ghci> sequence [Just 1, Nothing, Just 3]
Nothing

module Shapes where

-- An enumeration is a type whose values are listed by hand.
data Direction = North | South | East | West
  deriving (Show, Eq, Enum, Bounded)

allDirections :: [Direction]
allDirections = [minBound .. maxBound]

-- Constructors can carry values. Read the | as "or".
data Shape
  = Circle Double
  | Rectangle Double Double
  | Triangle Double Double Double
  deriving (Show, Eq)

-- One equation per constructor, and GHC checks none are missing.
area :: Shape -> Double
area (Circle r)       = pi * r * r
area (Rectangle w h)  = w * h
area (Triangle a b c) = sqrt (s * (s - a) * (s - b) * (s - c))
  where
    s = (a + b + c) / 2

-- Record syntax names the fields and defines the accessors for you.
data Employee = Employee
  { employeeName   :: String
  , employeeEmail  :: String
  , employeeSalary :: Int
  }
  deriving (Show, Eq)

ada :: Employee
ada = Employee
  { employeeName   = "Ada"
  , employeeEmail  = "ada@example.com"
  , employeeSalary = 100000
  }

-- Record update makes a copy with some fields changed. The original value
-- is untouched, so nothing else in the program can be surprised by it.
raise :: Int -> Employee -> Employee
raise amount employee =
  employee { employeeSalary = employeeSalary employee + amount }

-- A type parameter makes the container work for any element type, the same
-- way list[T] does in Python.
data Tree a
  = Leaf
  | Node (Tree a) a (Tree a)

insert :: Ord a => a -> Tree a -> Tree a
insert x Leaf = Node Leaf x Leaf
insert x node@(Node left value right)
  | x < value = Node (insert x left) value right
  | x > value = Node left value (insert x right)
  | otherwise = node

toList :: Tree a -> [a]
toList Leaf               = []
toList (Node left x right) = toList left ++ [x] ++ toList right

fromList :: Ord a => [a] -> Tree a
fromList = foldr insert Leaf

module Classes where

import Data.Char (toUpper)
import Data.List (sort)

data Animal = Dog | Cat | Parrot
  deriving (Show, Eq, Ord, Enum, Bounded)

-- A class lists operations a type may support. It is closer to a Python
-- protocol than to a class, because it defines no data of its own.
class Describable a where
  describe :: a -> String

  -- A default lets an instance override only what it cares about.
  loud :: a -> String
  loud x = map toUpper (describe x) ++ "!"

instance Describable Animal where
  describe Dog    = "a dog"
  describe Cat    = "a cat"
  describe Parrot = "a parrot"

instance Describable Bool where
  describe True  = "yes"
  describe False = "no"
  loud b = describe b ++ ", definitely"

-- A constraint before => reads "for any type a that is Describable".
introduce :: Describable a => [a] -> String
introduce = unwords . map describe

-- Deriving Eq and Ord writes the obvious instances, and every function in
-- the library that needs them starts working.
sorted :: [Animal]
sorted = sort [Parrot, Dog, Cat]

-- A newtype with hand written instances, for the cases where the obvious
-- rules are the wrong ones.
newtype CaseInsensitive = CaseInsensitive String

instance Eq CaseInsensitive where
  CaseInsensitive a == CaseInsensitive b =
    map toUpper a == map toUpper b

instance Show CaseInsensitive where
  show (CaseInsensitive original) = original

sameName :: Bool
sameName = CaseInsensitive "Ada" == CaseInsensitive "ADA"

-- Semigroup and Monoid describe "combinable" and "combinable with an
-- identity". Strings, lists and maps are all instances.
newtype Score = Score Int
  deriving (Show, Eq)

instance Semigroup Score where
  Score a <> Score b = Score (a + b)

instance Monoid Score where
  mempty = Score 0

totalScore :: [Score] -> Score
totalScore = mconcat

ghci> :info Eq
type Eq :: * -> Constraint
class Eq a where
  (==) :: a -> a -> Bool
  (/=) :: a -> a -> Bool
ghci> :type (==)
(==) :: Eq a => a -> a -> Bool
ghci> maximum "haskell"
's'
ghci> compare 3 5
LT
ghci> succ 'a'
'b'
ghci> [minBound .. maxBound] :: [Bool]
[False,True]
ghci> show (Just [1, 2, 3])
"Just [1,2,3]"
ghci> read "42" :: Int
42

module Effects where

import Data.Char (toUpper)

-- Functor: apply a pure function inside a structure, leaving the structure
-- alone. fmap over Maybe skips Nothing; fmap over a list is map.
upperMaybe :: Maybe String -> Maybe String
upperMaybe = fmap (map toUpper)

doubled :: [Int]
doubled = fmap (* 2) [1, 2, 3]

-- <$> is fmap spelled as an operator.
lengths :: Maybe String -> Maybe Int
lengths name = length <$> name

data User = User
  { userName :: String
  , userAge  :: Int
  }
  deriving (Show, Eq)

-- Applicative: the function itself is inside the structure too, so several
-- independent values can be combined. If any of them is Nothing, so is the
-- result, and no case analysis is written by hand.
makeUser :: Maybe String -> Maybe Int -> Maybe User
makeUser name age = User <$> name <*> age

-- Monad: each step depends on the result of the one before it.
half :: Int -> Maybe Int
half n
  | even n    = Just (n `div` 2)
  | otherwise = Nothing

quarter :: Int -> Maybe Int
quarter n = half n >>= half

-- do notation is exactly the same chain with names for the intermediates.
eighth :: Int -> Maybe Int
eighth n = do
  a <- half n
  b <- half a
  half b

-- The list monad means "every combination", which is the comprehension you
-- already know wearing different clothes.
pairs :: [(Int, Char)]
pairs = do
  n <- [1, 2, 3]
  c <- "ab"
  pure (n, c)

-- traverse runs an action for every element and turns a list of results
-- inside out: [Maybe a] becomes Maybe [a], all or nothing.
allHalves :: [Int] -> Maybe [Int]
allHalves = traverse half

ghci> lookup "ada" [("ada", 36), ("grace", 45)]
Just 36
ghci> lookup "alan" [("ada", 36), ("grace", 45)]
Nothing
ghci> fmap (+ 1) (Just 36)
Just 37
ghci> fmap (+ 1) Nothing
Nothing
ghci> (+) <$> Just 1 <*> Just 2
Just 3
ghci> (+) <$> Just 1 <*> Nothing
Nothing
ghci> Just 36 >>= \age -> if age > 18 then Just "adult" else Nothing
Just "adult"
ghci> sequence [Just 1, Just 2, Just 3]
Just [1,2,3]
ghci> sequence [Just 1, Nothing, Just 3]
Nothing

module Main (main) where

import Data.Char (toUpper)
import System.IO (hFlush, stdout)

-- IO String is a description of an effect that yields a String when run.
-- Building one runs nothing; only main is ever run.
prompt :: String -> IO String
prompt question = do
  putStr question
  hFlush stdout   -- putStr does not flush, so ask for it before reading
  getLine

main :: IO ()
main = do
  -- <- runs an action and names its result.
  name <- prompt "What is your name? "

  -- let names a pure value. No arrow, because nothing is being run.
  let greeting = "Hello, " ++ map toUpper name

  putStrLn greeting
  writeFile "greeting.txt" (greeting ++ "\n")

  saved <- readFile "greeting.txt"
  putStr ("greeting.txt now holds: " ++ saved)

  -- mapM_ is the for loop: an action for each element, results discarded.
  mapM_ print [1 .. 3 :: Int]

module Main (main) where

import System.IO (hFlush, stdout)
import System.Random (randomRIO)
import Text.Read (readMaybe)

main :: IO ()
main = do
  secret <- randomRIO (1, 100 :: Int)
  putStrLn "I picked a number between 1 and 100."
  attempts <- play secret 1
  putStrLn ("Solved it in " ++ show attempts ++ " guesses.")

-- There is no while loop. The loop is a function that calls itself, and the
-- guess counter is an argument rather than a variable being reassigned.
play :: Int -> Int -> IO Int
play secret attempt = do
  putStr "> "
  hFlush stdout
  entered <- getLine

  -- readMaybe parses without throwing: Nothing means it was not a number.
  case readMaybe entered of
    Nothing -> do
      putStrLn "That is not a number."
      play secret attempt
    Just guess -> case compare guess secret of
      LT -> do
        putStrLn "Higher."
        play secret (attempt + 1)
      GT -> do
        putStrLn "Lower."
        play secret (attempt + 1)
      EQ -> pure attempt

# Snippets that use a package outside GHC's own libraries need it installed
# first. Inside a cabal project, add it to build-depends instead.
cabal install --lib random
runghc guess.hs