aez-notes

1. An opinionated guide to Haskell in 2018
2. Can you make heterogeneous lists in Haskell? Sure — as long your intent is clear and on the waybackmachine.
3. Two interesting posts on type safety by Matt Parsons
   • Keep your types small…
   • Type Safety Back and Forth
4. Foo to Bar: Naming Conventions in Haskell
5. Numbers of Every Shape and Size
6. The trick to avoid deeply-nested error-handling code
7. Haskell mini-patterns handbook
8. common stanzas to keep cabal files DRY
9. Discussion of totality of functions
10. Structure your Errors

• unread Fix(ity) me
• unread Introduction to singletons 1 (dependent types)
• unread Existential quantification
• unread basic syntax extensions from the School of Haskell (reference material)

• Haskell 2010 Language Report

• Learn You a Haskell for Great Good!
• Haskell (Almost) Standard Libraries I haven't read any of this but it sounds good.

The trace function provided by Debug.Trace from the standard library is a good way to inspect the values of variables from pure code while debugging. The following function is nifty way to get a print out of particular values through the computation.

import Debug.Trace (trace, traceShow)

-- | Helper function while debugging.
--
-- >>> showAndTell "foo: " 1
-- foo: 1
-- 1
--
showAndTell :: Show a => String -> a -> a
showAndTell msg x = trace (msg ++ show x) x

The GHC user guide has a section on the GHCI debugger.

There is a script from commercialhaskell which installs stack

curl -sSL https://get.haskellstack.org/ | sh

The executable is in /usr/local/bin by default. To upgrade stack there is the stack upgrade command. To uninstall, remove the stack executable and ~/.stack and the .stack-work from any projects using stack.

stack installs to /home/<username>/.local/bin by default, so you should add this to your path

export PATH=/home/<username>/.local/bin:$PATH

The current solution to this appears to be just deleting .stack once in a while. This is a little bit wasteful because you'll need to download a bunch of dependencies afterwards the next time you build a project, but this does remove what can otherwise be a huge directory of unneeded material.

stack new <project-name> <template-name>
cd my-project
stack setup
stack build
stack exec my-project-exe

Here <project-name> is the name of the directory that will be created to house the project and <template-name> is the template to use; I like the simple template because it uses cabal directly and is free from clutter. If there is only library code and no executables, then the simple-library might be a cleaner choice. Packages get added to package.yaml under dependencies: and you start the REPL with stack ghci. Projects are configured by the .cabal file, for simple and simple-library. stack can use hpack to convert a package.yaml file to a .cabal file.

I wrote white-chocolate-macadamia which defines a minimalist project template. It is hosted here. To start a new project with it use the following command

stack new my-project https://raw.githubusercontent.com/aezarebski/white-chocolate-macadamia/main/macadamia.hsfiles

If you are ever unsure about some aspect of stack, appending --help is usually pretty enlightening. There are few ways to initialise a project using some standard templates.

stack new <package-name>
stack new <package-name> <template-name>        # Use a particular template
stack new <package-name> --bare <template-name> # Without subdirectory

To build the targets described in the .cabal file there is stack build, but unless you need GHC to optimise the executable, adding the --fast flag will make it run faster. There is also the --file-watch flag which will cause it to recompile each time that files are edited. There are many commands within stack which are listed in the documentation. Run the executable with

stack exec -- <target> [arguments]

To run the tests there is stack test. To build the documentation there is stack haddock which if you only need the documentation of your dependencies, you can speed up with --haddock-deps. Once you have the documentation build, you can open the documentation for a particular package in the browser.

stack build --haddock-deps
stack haddock --open <package>

To make the documentation searchable like the online version (though noticibly more responsive) you can run a hoogle server. But first you must index the documentation, and this will need to be done every time your dependencies change.

stack hoogle -- generate --local
stack hoogle -- server --local --port=8080

When using stack and nix, the haskell dependencies are managed by stack and only the non-haskell dependencies are managed by nix. You need nix installed on your system for this to work, it will not be installed by stack. Adding the following to your stack.yaml file will tell stack that you want to build your package in a nix shell with these packages available.

# stack.yaml
nix:
  enable: true
  packages: [glpk, pcre]

You will need to double check that the resolver you have specified corresponds to one of the GHC versions that are available in your nix channel. To find out which versions of GHC are available to you, drop into a nix REPL with nix repl and then load the available packages with :l <nixpkgs> then ask for a list of the available compiler versions with lib.attrNames haskell.compiler.

Markup documentation

• /italics/
• __bold__
• 'hyperlink'
• @monospace@
• ![image description](pathtoimage.png)
• [some link](http://example.com)

Haddock supports LaTeX syntax for rendering mathematical notation. The delimiters are \[...\] for displayed mathematics and \(...\) for in-line mathematics.

-- | This is an enumerated list:
--
--     (1) first item
--     2. second item
--
-- This is a bulleted list:
--
--     * first item
--     * second item

Sometimes hindent will reformat record definitions in a way that does not appear to be compatible with haddock.

data R a b =
  C { -- | This is the documentation for the 'a' field
      a :: a,
      -- | This is the documentation for the 'b' field
      b :: b
    }

Build and open the documentation in the browser. This does not seem to work well from eshell but works fine from a bash shell.

stack haddock
stack haddock --open

But a much quicker way to is to not build the documentation for the dependencies by using the following command instead.

stack haddock --no-haddock-deps --open

The following assumes that the type Foo is an instance of Csv.ToRecord which can often be derived.

import qualified Data.ByteString.Lazy as L
import qualified Data.Csv as Csv

L.writeFile "output.csv" (Csv.encode (foos :: [Foo]))

AutoDeriveTypeable
BangPatterns
BinaryLiterals
ConstraintKinds
DataKinds
DefaultSignatures
DeriveDataTypeable
DeriveFoldable
DeriveFunctor
DeriveGeneric
DeriveTraversable
DoAndIfThenElse
EmptyDataDecls
ExistentialQuantification
FlexibleContexts
FlexibleInstances
FunctionalDependencies
GADTs
GeneralizedNewtypeDeriving
InstanceSigs
KindSignatures
LambdaCase
MonadFailDesugaring
MultiParamTypeClasses
MultiWayIf
NamedFieldPuns
NoImplicitPrelude
OverloadedStrings
PartialTypeSignatures
PatternGuards
PolyKinds
RankNTypes
RecordWildCards
ScopedTypeVariables
StandaloneDeriving
TupleSections
TypeFamilies
TypeSynonymInstances
ViewPatterns

Note that Alexis King thinks that PatternSynonyms are safe to enable by default.

-Wall
-Wcompat
-Widentities
-Wincomplete-record-updates
-Wincomplete-uni-patterns
-Wpartial-fields
-Wredundant-constraints

and -Werror for production.

Kowainik has an excellent summary of naming conventions in Haskell.

-- |wild card
f (_:xs) = xs

-- |as-pattern
f l@(x:xs) = x:l

-- |guards
f x
  | x < 0     = 0
  | x >= 0    = 1
  | otherwise = undefined

-- |case expression
f x = case x of
  pattern1 -> expression1
  pattern2 -> expression2
  _        -> undefined

-- |where clause
f x = g z
  where
    z = epxression

-- |let expression
f x = let z = expression
      in g z

If you have the MultiWayIf extension you can use guard style syntax in a conditional as demonstrated in the following example from the School of Haskell:

{-# LANGUAGE MultiWayIf #-}

fn :: Int -> Int -> String
fn x y = if | x == 1    -> "a"
            | y <  2    -> "b"
            | otherwise -> "c"

-- | should print:
--   @c@
main = putStrLn $ fn 3 4

There is "Record Update Syntax" to construct a new record with some of the fields taking different values.

data Foo = Foo {a :: Int, b :: Char} deriving (Show)

foo1 = Foo 1 'a'
-- Foo {a = 1, b = 'a'}
foo2 = foo1 {b = 'b'}
-- Foo {a = 1, b = 'b'}

The RecordWildcards extension provides some additional sugar for pattern working with records. It makes the fields available in the local scope under the name of their accessors. The same is true for record construction. For example

{-# LANGUAGE RecordWildCards #-}

data Person = Person { name :: String , admin :: Bool }

example :: Person
example = Person{..}
  where
    name = "John Doe"
    admin = True

The NamedFieldPuns extensions attempts to make it easier to construct and reference values in a record. With this extension enabled, this

data C = C {a :: Int}
f (C {a = a}) = a

can be written as this

f (C {a}) = a

It is possible to mix the effects of RecordWildCards and NamedFieldPuns, eg C {a = 1, b, ..}.

data Person = Person { personFirstName :: String
                     , personLastName :: String
                     , personAge :: Int
                     } deriving (Show, Eq)

It is considered decent to prefix the attributes with something that is unique to the record type to avoid name clashes.

If you have a wrapper type and want to access the data within but do not want to continually pattern match to get the value out you can use the coerce function from Data.Coerce (which is part of base). This functionality is encoded in the Coercible typeclass.

List comprehensions are a nice way to combine a map and a filter.

[sqrt x | x <- [1..9], x > 3]

You can use pattern matching to filter in a list comprehension as the following example demonstrates

data Foobar = Foo Int | Bar Char deriving (Show)
x = [Foo 1, Bar 'a', Foo 2, Bar 'b']
y = [n | (Foo n) <- x]

The variable y has the value [1,2].

The Haskell 98 Report says

Underscore, "_", is treated as a lower-case letter, and can occur wherever a lower-case letter can. However, "_" all by itself is a reserved identifier, used as wild card in patterns. Compilers that offer warnings for unused identifiers are encouraged to suppress such warnings for identifiers beginning with underscore. This allows programmers to use "_foo" for a parameter that they expect to be unused.

The Haskell 98 Report says

Module names are alphanumeric and must begin with an uppercase letter.

class Eq a where
    (==) :: a -> a -> Bool
    (/=) :: a -> a -> Bool
    x == y = not (x /= y)
    x /= y = not (x == y)

data Foobar = Foo | Bar

instance Eq Foobar where
    Foo == Foo = True
    Bar == Bar = True
    _ == _ = False

There are cases where a class will have multiple type parameters, e.g. a, b, and c, but one of them may be determined by the others, c is determined by a and b. One way to resolve this is by adding type annotations, but this is unpleasant. Functional dependencies are a way to tell the compiler that c is determined by a and b. The following snippet gives an example of the syntax (a vertical bar, |) used to acheive this

class Foo a b c | a b -> c where ...

As stated on the Haskell wiki page "Let vs. Where"

It is important to know that let ... in ... is an expression, that is, it can be written wherever expressions are allowed. In contrast, where is bound to a surrounding syntactic construct, like the pattern matching line of a function definition.

To avoid explicitly passing environment data around, one can use the ReaderT monad transformer to add read-only environment. The following example shows the reader monad transformer in action.

import Control.Monad.Reader (ReaderT, ask, liftIO, runReaderT)

data Env = Env { envInput :: FilePath }

step1 :: ReaderT Env IO Int
step1 = do
  liftIO $ putStrLn "Greetings from Step 1."
  return 0

step2 :: Int -> ReaderT Env IO ()
step2 n = do
  liftIO $ putStrLn (show n)
  fp <- envInput <$> ask
  line <- liftIO $ readFile fp
  liftIO $ putStr ("Autobots, " ++ line)

main :: IO ()
main = do
  runReaderT (step1 >>= step2) (Env "autobots.txt")

The main function sets up an environment which is passes to Step 1 which puts a value of 0 in the monad. Then in the second function the value is printed and the contents of the file referenced in the environment is printed out, i.e., the file autobots.txt which just contains a single line with "roll out". Running this in the REPL gives the following output.

λ> main
Greetings from Step 1.
0
Autobots, roll out

The example above using the reader monad transformer can be extended to improve the error handling in the case where the file path in the environment does not exist.

import Control.Monad.Except (ExceptT, runExceptT, throwError)
import Control.Monad.Reader (ReaderT, asks, liftIO, runReaderT)
import System.Directory (doesFileExist)

newtype Env = Env { envInput :: FilePath }

type Robot a = ReaderT Env (ExceptT String IO) a

runRobot :: Robot a -> Env -> IO (Either String a)
runRobot robot env = runExceptT (runReaderT robot env)

step1 :: Robot Int
step1 = do
  liftIO $ putStrLn "Greetings from Step 1."
  return 0

step2 :: Int -> Robot ()
step2 n = do
  liftIO $ print n
  fp <- asks envInput
  exists <- liftIO $ doesFileExist fp
  if exists
  then do line <- liftIO $ readFile fp
          liftIO $ putStr ("Autobots, " ++ line)
  else throwError "Could not find file in step 2"

The main function has been remove but there is not much added code here. Running the runRobot function in the REPL we get the following results which demonstrate how the failure path evaluates.

λ> runRobot (step1 >>= step2) (Env "autobots.txt")
Greetings from Step 1.
0
Autobots, roll out
Right ()
λ> runRobot (step1 >>= step2) (Env "autobats.txt")
Greetings from Step 1.
0
Left "Could not find file in step 2"

The package Data.Int provides signed integers and Data.Word provides unsigned integers. The latter may be useful to encode that the number has to be positive at the type level.

Strings are just lists of characters which can lead to poor preformance, which is why people warn that String should be avoided if you are doing anything serious with text. Still, for the cases where performance isn't going to be a problem strings are simple to work with. The printf function in base provides string interpolation.

import Text.Printf (printf)

a = printf "foo %d" 1 :: IO ()
b = printf "bar %d" 2 :: String

The variable a stores and action which prints "foo 1" and b is a string: "bar 2".

A semigroup is a set with an associative binary operation. In base this type class, Data.Semigroup, requires a function <>, and instances of this function must be associative.

A monoid is a semigroup which has an identity element. In base this type class, Data.Monoid, requires the function <>, as in semigroup, and mempty for the identity element. The mempty must be both a left and right identity.

• Data.List.NonEmpty (in base) for non-empty lists to avoid run time errors due to bad calls to head or tail.
• containers has several efficient data structures that can be used as an alternative to lists.
  • Data.Map for look-up tables
  • Data.Sequence if you finite lists you can access from both ends
  • Data.Set for sets of elements in Eq and Ord
• vector has vectors.

A data structure that reduced to a single summary value: foldr :: (a -> b -> b) -> b -> t a -> b. For example, you might add up all the values on a tree where each node has a value. When the data form a monoid foldMap can be implemented instead which just uses the monoid's addition.

Like a more powerful functor: traverse :: Applicative f => (a -> f b) -> t a -> f (t b)

Next time you have tricky fold, the following might be useful. Note that we use the modifySTRef' with the apostrophe, which is the strick version of the function to avoid the build up of thunks which might otherwise be a problem.

import Control.Monad (replicateM_,liftM)
import Control.Monad.ST (runST)
import Data.STRef

fib :: Int -> Int
fib n = runST $ do
  ref <- newSTRef (0,1)
  replicateM_ n $ modifySTRef' ref (\(a,b) -> (b,a+b))
  liftM snd $ readSTRef ref

Moreover, this appears to be faster than the following non-tail recursive implementation

fib2 :: Int -> Int
fib2 n
  | n < 2 = 1
  | otherwise = fib (n-1) + fib (n-2)

The source for the either monad in Haskell is here. Importantly, the instance of monad is

instance Monad (Either e) where
    Left  l >>= _ = Left l
    Right r >>= k = k r

Note that the left branch will short-circuit which is particularly useful! See this post by Gabriel Gonzalez for a worked example.

Described here

instance MonadFail (Either String) where
  fail = Left

This sort of thing was ultimately rejected to preserve a neutral interpretation of how the Either monad would should work.

There is the aeson-pretty package to pretty print JSON values. The following function might be useful as a quick toggle between the methods.

import qualified Data.Aeson                         as Json
import qualified Data.Aeson.Encode.Pretty           as Pretty

-- | Write the object to file as JSON with optional pretty printing.
encode2File :: Json.ToJSON a => Bool -> FilePath -> a -> IO ()
encode2File isPretty fp = L.writeFile fp . (if isPretty then Pretty.encodePretty else Json.encode)

Allows you to use string literals to mean other string-ey type things. For instance, this would be useful when working with Text.

This allows you to make use of Unicode characters in your code which is particularly nice if you are going a verbatim translation of some mathematics. Emacs provides a nice way to make it easy to input Unicode.

Although this does not appear in the Boring Haskell recommendations, I suspect it has sufficient utility in scientific programming to warrant an exception.

This desugars list syntax to make it easier to use list syntax to construct things.

{-# LANGUAGE OverloadedLists #-}

foo = [(1,2),(2,3)] :: Map Int Int

This will only work with the OverloadedLists extension.

The following example from Kowainik demonstrates nicely

mkUser :: Text -> Text -> User
mkUser (Text.toLower -> nickname) (Text.toLower -> name) = User
    { userNickname = nickname
    , userName = name
    }

One example of using cassava is to make the Chain type from mcmc-types an instance of ToRecord which makes it easier to write MCMC samples to a CSV. The following snippet demonstrates how you might do this with an orphan-instance.

import Data.Csv
import Data.Maybe (fromMaybe)
import qualified Data.Vector as V

instance (ToRecord a, ToRecord b) => ToRecord (Chain a b) where
  toRecord Chain {..} =
    V.concat
      [ (record [toField chainScore])
      , (toRecord chainPosition)
      , fromMaybe V.empty (toRecord <$> chainTunables)
      ]

Without knowing anything about how this works internally, the following functions should be sufficient for running a map type computation in parallel.

import Control.Monad.Par (runPar)
import Control.Monad.Par.Combinator (parMap)

data Par a

runPar :: Par a -> a
parMap :: Traversable t => (a -> b) -> t a -> p (t b)

• Data.List.sum and Data.List.product use foldl instead of foldl' so can have poor performance.
• Lots of the functions in Data.List are partial: head, init, last, tail and (!!) for example.

fromJust, always use ~fromMaybe

a -> Maybe a -> a~ instead.

There is a section on seq in Chapter 4 of Real World Haskell. In particular, the following snippet from that chapter provides insight.

 -- file: ch04/Fold.hs
-- incorrect: seq is hidden by the application of someFunc
-- since someFunc will be evaluated first, seq may occur too late
hiddenInside x y = someFunc (x `seq` y)

-- incorrect: a variation of the above mistake
hiddenByLet x y z = let a = x `seq` someFunc y
                    in anotherFunc a z

-- correct: seq will be evaluated first, forcing evaluation of x
onTheOutside x y = x `seq` someFunc y

Keep in mind that seq only evaluates up to the first constructor, and that there is an additional cost with forcing evaulation since the runtime needs to do a look up to determine if it has already been evaluated. Depending on what is being evaluated this can even introduce a space leak.

The very simple example given here demonstrates how to run code in parallel using only the parallel library (which is maintained by libraries@haskell.org so can be relied upon).

executable party
  hs-source-dirs:   src
  main-is:          Main.hs
  default-language: Haskell2010
  ghc-options:      -threaded -O2
  build-depends:
      base               >=4.7      && <5
    , mwc-random
    , parallel
    , primitive          >=0.7.1.0
    , vector             >=0.12.1.2

And the following Main.hs

module Main where

import Control.Monad.Primitive (PrimMonad, PrimState)
import Control.Monad.ST (runST)
import Data.Vector.Unboxed (singleton)
import Data.Word (Word32)
import System.Random.MWC (asGenST, initialize)
import Control.Parallel.Strategies
import System.Environment (getArgs)

main :: IO ()
main = do
  putStrLn "Hello"
  (inParallel:maxN:[]) <- getArgs
  let maxNInteger = read maxN :: Int
      ns = replicate maxNInteger 30
  print $ "running up to " ++ maxN
  if inParallel == "true"
    then let results = (fib <$> ns `using` parListChunk 4 rdeepseq) :: [Integer]
         in do print "running parallel"; print $ sum results
    else let results = (fib <$> ns) :: [Integer]
         in do print "running serial"; print $ sum results
  putStrLn "Goodbye"

fib :: Integer -> Integer
fib n
  | n < 2 = 1
  | otherwise = fib (n -1) + fib(n-2)

The following script is used to test out the performance of this code.

time stack exec party false 100 --rts-options -N1
time stack exec party false 100 --rts-options -N2
time stack exec party false 100 --rts-options -N4

time stack exec party true 100 --rts-options -N1
time stack exec party true 100 --rts-options -N2
time stack exec party true 100 --rts-options -N4

the results of this confirm that increasing the number of processors allowed to be used reduces the run time but there is a limit to how useful this will be.

• Natural for the natural numbers
• Word is unsigned integers of with a finite range
• Integer for arbitrary integers
  • not to be confused with the Integral typeclass
• Int for a finite range of integers
• Float for single precision floating point numbers
  • You should opt for Double whenever possible
• Double for double precision floating point numbers

Also the table here provides a description of how to map between the different numeric types.

This graph shows the hierarchy of numeric typeclasses

The most important one here is the Num typeclass which ensures you have basic arithmetic. Ord is also important but is a bit more general.