Forem: Ryan Frazier

What Is Functional Programming

Ryan Frazier — Tue, 20 Oct 2020 15:55:15 +0000

In my day to day work as a software engineer I do not have the luxury of using a functional language like Haskell or Elm, however I have learned a lot from Elm that has changed how I program in JavaScript or Python. Here is a run-down of some of the concepts I have learned from writing 3000+ lines of Elm code.

Here are some of my projects written entirely in Elm.

Know Your Theory - a music theory drill app
Elm Piano Teacher - a midi keyboard interactive tool
Music Scale Explorer - interactive graph of musical scales
Circle of 5ths Explorer - interactive circle of 5ths with key signatures and keyboard
Uke Chord Finder - interactive Ukulele chord finder

FP Vocabulary

Here is a list of common terms that come up when learning functional programming (FP). I will discuss many of them in this article.

Pure Function
Side Effect
Referential Transparency
Mutable/Immutable
Currying
Monad
Algebraic Data Types
Variant
Lambda Calculus

Pure Functions

What is a pure function?

A function is said to be pure if 1) given the same arguments it always returns the same result and 2) the function has no side effects.

function add(a,b) {
  return a + b;
}
function impureAdd(a,b) {
  return a + b + c;
}
console.log(add(1,2)) // 3
// console.log(impureAdd(1,2)) // EXPLOSION!!!
c = 1
console.log(impureAdd(1,2)) // 4
c = 2
console.log(impureAdd(1,2)) // 5

What is a side effect?

A side effect is something that occurs as a result of a function call that does not get returned from the function.

Referential Transparency

An expression is said to be referentially transparent if the evaluation of the function can be replaced with its return value and not effect the program's behavior.

result = add(2,3) + 5 // result == 10
result = 5 + 5 // result == 10

By contrast, if the function call cannot be replaced by the output then the function is said to be referentially opaque.

No For Loops?

In a pure functional language like Haskell or Elm, you will notice there are no for loops. You must process all lists with map, reduce, and filter (among others).

list = [1,2,3,4]
// Imperative
listTimesThree = []
for(i = 0; i < list.length; i++) {
  listTimesThree.push(list[i] * 3)
}
// Declarative
listTimesThree = list.map(x => x * 3)

What are all the things that could go wrong in a for loop?

mental burden of parsing a for loop (What does it do? Is it correct?)
thread mutate the processing list
mutate the iterator variable i
out of range list access

Currying

currying is the technique of converting a function that takes multiple arguments into a sequence of functions that each take a single argument.
Wikipedia Currying

add = a => b => a + b
addOne = add(1) // What does this return?

add(1)(2) // 3

list.map(x => addOne(x)) // [2,3,4,5]

How is currying useful?

How about providing different ways to render a list? Currying makes it easy to make functions from other functions.

list = ['Fries', 'Hamburger', 'Shake']

latexListHead = x => `\\begin\{itemize\}\n${x}\n\\end\{itemize\}`
latexItem = x => `\\item ${x}`

htmlListHead = x => `<ul>\n${x}\n</ul>`
htmlItem = x => `<li>${x}</li>`

mdListHead = x => x // The identity function
mdItem = x => `- ${x}`

renderList = headFn => itemFn => list => headFn(list.map(x => itemFn(x)).join('\n'))

latexList = renderList(latexListHead)(latexItem) // LaTeX render function
webList = renderList(htmlListHead)(htmlItem) // HTML render function
mdList = renderList(mdListHead)(mdItem) // Markdown render function

console.log(webList(list))
console.log(latexList(list))
console.log(mdList(list))

Now what if you wanted several styles of lists, like a fancy web list.

htmlListHead = classes => x => `<ul class='${classes.join(' ')}'>\n${x}\n</ul>`

bigBlueListHead = htmlListHead(['big', 'blue'])
smallRedListHead = htmlListHead(['small', 'red'])

webList = renderList(bigBlueListHead)(htmlItem)

console.log(webList(list))

There are other uses for currying like generating a range of math plots. See my post on creating beautiful math homework. And here is the python file

Exception Throwing is a Side Effect

The reasoning is that I consider exceptions to be no better than “goto’s”, considered harmful since the 1960s, in that they create an abrupt jump from one point of code to another. In fact they are significantly worse than goto’s

They are invisible in the source code.

They create too many possible exit points for a function.

Joel Spolsky at Joel on Software

I wrote about this topic in a previous blog post Exceptions Considered Harmful.

JavaScript helper libraries

JavaScript is notorious for an inconstant API. What functions are immutable? For example, map() creates a new array whereas sort() and reverse() mutate the array in place and returns the mutated array. This inconsistency is a mental burden. Therefore there is a need for libraries like Ramda.

list = [4,2,3,1]
sortedList = list.sort()
console.log(list) // [4,2,3,1] or [1,2,3,4]?

Compare with Ramda's sort.

JS Libraries

TypeScript Libraries

Other Resources

Introduction to Algebraic Data Types

Ryan Frazier — Tue, 14 Jul 2020 00:00:00 +0000

The demo code:

Elm on ellie-app
TypeScript on TypeScript playground

One of the concepts in functional programming that trips up beginners is Algebraic Data Types (ADT). I am going to go through some examples and relate it to some concepts that would be familiar to Object Oriented Programming (OOP).

For this introduction I will be using TypeScript for the OOP examples and Elm for the functional examples.

Let's start with an example.

type Animal = Cat | Dog

An Animal can be either a Cat or a Dog, but you can't just be an animal. You need to be a type of an animal, the classic "is a" relationship. This is a bit similar to abstract classes in OOP languages.

abstract class Animal {
    abstract speak(): string;
}

class Cat extends Animal {
    speak(): string {
        return "meow";
    }
}

class Dog extends Animal {
    speak(): string {
        return "bark";
    }
}

// can't make an abstract Animal
// const myAnimal = new Animal();
const myCat = new Cat();
console.log(myCat.speak());

Now you could make a function that generically takes any type of Animal as an argument.

function feedAnimal(animal: Animal): string {
    return "thanks for the food! " + animal.speak();
}

console.log(feedAnimal(myCat));

Similarly, let's translate this to Elm.

animalSpeak : Animal -> string
animalSpeak animal =
    case animal of
        Cat ->
            "meow"
        Dog ->
            "bark"

feedAnimal : Animal -> string
feedAnimal animal =
    "thanks for the food! " ++ animalSpeak(animal)

Why are they useful?

Easier refactors. You can catch problems at compile time.
Can constrain the problem domain by the type system. See Making Impossible States Impossible.

When working on a new feature or a refactor with a strongly typed language I will often start by changing the data structures and then let the compiler tell me where my code fails to compile. When my code compiles again my job is mostly done.

You can do this by leveraging classes and using them as types but it is a lot easier and compact to have a robust type system built into the language. There is usually a lot of boiler code needed to get some better type safety in languages like Java or TypeScript. See this stackoverflow question.

Animal Names

Since there are no classes or member variables in a language like Elm we use records instead.

type alias AnimalRecord =
    { type_ : Animal
    , name : String
    }

felix = AnimalRecord Cat "Felix"

When I write TypeScript I actually prefer using interfaces instead of defining classes. The reason for this preference is that I like to separate the structure of the data from the operations on that data.

I will, in fact, claim that the difference between a bad programmer and a good one is whether he considers his code or his data structures more important. Bad programmers worry about the code. Good programmers worry about data structures and their relationships.
Linux Torvalds, see https://lwn.net/Articles/193245/

So it would look like this:

interface AnimalRecord {
    type_ : Animal;
    name : string;
}

const felix : AnimalRecord = {
    type_: new Cat(),
    name : "Felix",
};

Immutability

One core idea of functional programming is immutability. You can get more immutability in TypeScript by declaring class members or interfaces as immutable.

for classes https://www.typescriptlang.org/docs/handbook/classes.html#readonly-modifier
for interfaces https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlyt

An example with error handling

I wrote about this in another post Exceptions considered harmful.

Let's use the Either type from purify-ts to deal with errors in our code. The TypeScript compiler can help us if we give it the right information.

Below is the type signature for Either (almost). See https://github.com/gigobyte/purify/blob/master/src/Either.ts#L3 Neverthrow's Result type signature is a bit easier to read but has less functionality.

type Either<E, T> = Left<E, T> | Right<T, E>

An Either can be one of Left which holds the error or it can be Right which holds the successful return value.

// might be one of an Error or a result string
function getUsernameFromDB(id : number) : Either<Error, string> {
    const username : string;
    const error : Error;
    try {
        username = DB.getUserById(id);
    } catch(e) {
        error = e;
    }

    if (error) {
        return Left(error); // error values are always Left
     } else {
        return Right(username); // Right is "right" or the correct value
     }

    // could use Either.encase instead
    // see https://gigobyte.github.io/purify/adts/Either#encase
    // return Either.encase(() => DB.getUserByID(id));
}

const result = getUsernameFromDB(1);

// now the compiler forces you to deal with the error
result.caseOf({
    Left: error => error.toString(),
    Right: value => value,
})

Here are the docs of caseOf statements for

When I first encountered ADT in Elm it looked so foreign. Once I got used to them I wished that every language I used had them. The compiler now becomes your best friend.

You can get fancier with TypeScript that I did in this post to get something closer to Elms ADTs using union types. See https://www.typescriptlang.org/docs/handbook/advanced-types.html#union-types TypeScript also has type guards that aid in handling these types.

Case Statement in Typescript

Ryan Frazier — Wed, 24 Jun 2020 18:33:03 +0000

One of my favorite features of functional languages like Elm is pattern matching. Here is an example:

type State
    = Loading
    | Error
    | Ok

stateToString : State -> String
stateToString state =
    case state of
        Loading ->
            "Loading ..."
        Error ->
            "Something went wrong."
        Ok ->
            "It's all good"

I found a simple way to provide an action for every case of a TypeScript enum.

enum State {
    Loading,
    Error,
    Ok,
}

const STATE_MAP = {
    [State.Loading] : () => "Loading ...",
    [State.Error] : () => "Something went wrong.",
    [State.Ok] : () => "It's all good",
}

function stateToString(state : State) : string {
    return STATE_MAP[state]();
}

Link to TypeScript playground

Usually TypeScript won't allow bracket notation to access properties of an object. In this case the compiler knows that all cases of State are accounted for and can thus be used to index into the object.

Try removing one of the states from STATE_MAP and the TypeScript compiler will yell at you.

Element implicitly has an 'any' type because expression of type 'State' can't be used to index type '{ 0: () => string; 1: () => string; }'.
Property '[State.Ok]' does not exist on type '{ 0: () => string; 1: () => string; }'.

Exceptions Considered Harmful

Ryan Frazier — Fri, 05 Jun 2020 19:32:21 +0000

The reasoning is that I consider exceptions to be no better than “goto’s”, considered harmful since the 1960s, in that they create an abrupt jump from one point of code to another. In fact they are significantly worse than goto’s

They are invisible in the source code.

They create too many possible exit points for a function.

Joel Spolsky at Joel on Software

How do we deal with uncertainty in our code?

If something goes wrong in our code we need to know about it, preferably without crashing our program. When I come back to the code months later or I am using someone elses code I want the compiler to help me handle errors gracefully.

Here are several patterns that I have seen, my own code included.

Pattern 1 - return true or false

function doWork() : boolean {
    // do some SIDE EFFECT
    let result = doWork();
    this.some_member_variable = result;

    let success = result !== null;
    if (success) {
        return true;
    } else {
        return false;
    }
}

Side effect's make it harder to reason about what your code does. Pure functions, side effect free functions, are also easier to test. Also if there was a failure you can't send a message to the function caller.

Pattern 2 - return null if failed

In the next examples, let's assume that our database stuff are synchronous to make things a bit simpler.

Instead of returning true or false we could return the value or a null value.

import DB from 'my-synchronous-database';

function getUser(id : UserID) : User | null {
    const user = DB.getUserById(id);
    if (user) {
        return user;
    } else {
        return null;
    }
}

This is slightly better, now that we don't have a side effect. However we still have no error message and we better make sure to handle that returned null value or our program will explode.

This eliminates the side effect but now creates a new problem.

I call it my billion-dollar mistake. It was the invention of the null reference in 1965. At that time, I was designing the first comprehensive type system for references in an object oriented language (ALGOL W). My goal was to ensure that all use of references should be absolutely safe, with checking performed automatically by the compiler. But I couldn't resist the temptation to put in a null reference, simply because it was so easy to implement. This has led to innumerable errors, vulnerabilities, and system crashes, which have probably caused a billion dollars of pain and damage in the last forty years.
Tony Hoare at QCon London 2009, see wikipedia

Pattern 3 - throw exception

Our other choice is to throw an exception.

import DB from 'my-synchronous-database';

function getUser(id : UserID) : User {
    const user = DB.getUserById(id);
    if (user) {
        return user;
    } else {
        throw new Error(`Cannot find the user by id ${id}`);
    }
}

Now we have an error message but now we introduced another side effect: the exception. If you don't catch the exception, in most cases, your program will crash.

In JavaScript there is no way I can tell by using a function if it will throw or not. Java helps because the tooling will warn you that you are using a throwable function. Still no one likes seeing a nullExceptionPointer in Java land. Not fun.

Pattern 4 - return a result type

What if we wanted to both return an error message if something goes wrong and also not introduce side effects.

This is the Result type.

This thing is baked into the standard library of newer programming languages like Rust and Elm. We have std::result in Rust and the Result Type in Elm. Some newer languages don't implement exceptions and treat errors as data like Go, Rust, and Elm.

Since this article is using TypeScript, I'm going to use the library neverthrow but there are others to choose from. This will also work in plain JavaScript too.

Let's look at neverthrow's Result type.

From the neverthrow docs:

type Result<T, E> = Ok<T, E> | Err<T, E>

Ok<T, E>: contains the success value of type T

Err<T, E>: contains the failure value of type E

And here it is in action.

import { Result, ok, err } from 'neverthrow';
import DB from 'my-synchronous-database';

type DBError = string; // type alias for error message

function getUser(id : UserID) : Result<User, DBError> {
    const user = DB.getUserById(id);
    if (user) {
        return ok(user); // return instance of OK
     } else {
        return err(`Cannot find the user by id ${id}`); // return instance of Err
     }
}

This is an improvement because there are now no side effects and we can return an error message if something goes wrong. I know that when I use this function I will always get a Result.

const userID = 1;
const userResult : Result<User, DBError> = getUser(userID);

if (userResult.isOK()) {
    console.log(userResult.value);
} else {
    console.log(userResult.error);
}

If you try to retrieve userResult.value before you have checked isOK() the TS compiler won't let you. Pretty awesome.

JavaScript tooling

tslint-immutable is a plugin for TSlint that has several options to prevent throwing exceptions. See this set of functional programming rules for TSlint here. Enable no-throw and no-try.

And here is a similar set of rules for eslint.

Other libraries and languages

These ideas are also being explored in other languages. Here are some libraries I found.

C++ std::optional, optional<T>, is a safer way than just returning null. The optional can be empty or it can hold a value of type T. It does not hold an error message. This type is also called Maybe in elm and elsewhere.

C++ Result is a header only library that implements Rust's Result<T, E> type. This type can hold the value or an error.

Python result another Rust inspired result type.

If you want to explore more typed functional programming in TypeScript, check out purify, true myth, or the full featured fp-ts.

Elm Calculator Part 11 - Netlify Deployment

Ryan Frazier — Fri, 22 May 2020 00:00:00 +0000

This post is part of a series. To see all published posts in the series see the tag "elm calculator book".If you wish to support my work you can purchase the book on gumroad.

This project uses Elm version 0.19

Part 1 - Introduction
Part 2 - Project Setup
Part 3 - Add CSS
Part 4 - Basic Operations
Part 5 - Adding Decimal Support
Part 6 - Supporting Negative Numbers
Part 7 - Add Dirty State
Part 8 - Support Keypad Input
Part 9 - Combination Key Input
Part 10 - Testing
Part 11 - Netlify Deployment (this post)

Netlify makes deploying web apps super easy. You point Netlify to a git repository hosted with GitHub, GitLab, or Bitbucket and netlify will build and deploy your project. We will need to add some things to our project so that Netlify will know how to build and deploy our project.

Add deploy script

The only change we need to add to our project for Netlify is to add a build script. We will add that to the package.json. Anything added to the scripts section in a package.json can be run with npm run <script name>. So in our case we can run npm run build and npm will build our project to a dist folder.

{
"name": "elm-calculator",
...
"scripts": {
"build": "<do build stuff here>"
},
...
}

Here is what we need to do to make a build.

mkdir -p dist # make a dist folder if not already there
elm make src/Main.elm --optimize --output=dist/elm.js # make optimized build and output to dist/elm.js
cp index.html dist # copy index.html to build directory
cp style.css dist # copy style.css to build directory

And then we add it to our package.json so we can run it with npm run build.

{
"name": "elm-calculator",
...
"scripts": {
"build": "mkdir -p dist && elm make src/Main.elm --optimize --output=dist/elm.js && cp index.html dist && cp style.css dist"
},
...
}

Configure Netlify

Now we need to point Netlify to our git repository.

First you need to register for an account on Netlify. After you can log in to your netlify account you need to go to the dashboard at https//app.netlify.com.

After you click on "New site from Git" you will need to choose you git hosting service. I am hosting this project on GitLab so I will choose that one.

Netlify will ask you to allow permission to access you repositories on the chosen git provider. After you login and give permission you will choose a repository.

Next is the most important step. We tell Netlify what command to run to build our project and with directory to deploy from. The build command needs to be set to npm run build and the publish directory needs to be set to dist. See

Click on "deploy site". If all goes well you should see that your build is in queue waiting to be built.

When it is ready you can click on the link provided and see you app live on the internet to share with the world.

If you want a custom Netlify sub-domain name click on "Site settings". Then click on "Change site name". You can then change the name to something like "elm-calculator". Your project would then be made available at https://elm-calculator.netlify.com.

We're done

Congratulations for making it to the end of this project. I learned a lot putting this together and I hope you learned a lot as well.

Together we build an Elm application from the ground up and deployed it to netlify for all the world to see.

Elm Calculator Part 10 - Testing

Ryan Frazier — Fri, 15 May 2020 00:00:00 +0000

This post is part of a series. To see all published posts in the series see the tag "elm calculator book".If you wish to support my work you can purchase the book on gumroad.

This project uses Elm version 0.19

Part 1 - Introduction
Part 2 - Project Setup
Part 3 - Add CSS
Part 4 - Basic Operations
Part 5 - Adding Decimal Support
Part 6 - Supporting Negative Numbers
Part 7 - Add Dirty State
Part 8 - Support Keypad Input
Part 9 - Combination Key Input
Part 10 - Testing (this post)
Part 11 - Netlify Deployment

Note: ellie-app does not support splitting out your code into modules and files. So there is no ellie link for this chapter.

We will be using a newer Elm package called elm-program-test. It allows us to test our application as a whole. It will stand up the application and allow us to test it as if a user were clicking through the application.

Some Refactoring

In order to test our program we need to expose some of our functions in Main.elm.

module Main exposing (Model, Msg, init, main, update, view)

We also need to make our elm program use Browser.document instead of Browser.element since we will be using ProgramTest.createDocument.

Elm has different ways to create a program. Browser.element is good for creating a small elm application that you embed into the page on a specific DOM node. What if you want Elm to take over the whole page? That is what Browser.document is for. See the elm-guide for more information about Browser.element and Browser.document.

Note: Since creating this book, I have since learned that you can use ProgramTest.createElement instead and we wouldn't need to do this refactor.

Refactoring is lovely in Elm. Our first step is to start at the highest level of our refactor and let the compiler tell us what to change. So start by changing the main function to return a Browser.document instead of a Browser.element.

The only thing we need to change for this refactor is the view function to return a Browser.Document instead of Html.

The difference with Browser.Document is that the view function now needs a record with a title and a body field. We can place our previous view html stuffs inside the body field.

view : Model -> Browser.Document Msg
view model =
    { title = "Elm Calculator"
    , body =
        [div []
            [h1 [ class "h1"] [text "RPN Calculator"]
    , ...

Write the test

First we need to install everything we need. We need the elm-test command line program because we need something to launch and execute our tests. This is our test runner if you have used something like pytest.

npm install --save-dev elm-test

We also need to install the corresponding elm packages as well.

elm install elm-explorations/test
elm install avh4/elm-program-test

To get a simple example test run elm-test init in your project folder.

npx elm-test init

Now run the test you just created.

npx elm-test

You should get a test report.

Create a new file in the tests directory called CalculatorTest.elm.

The test is short (less than 40 lines of code). I'll walk through the most interesting part.

all : Test
all =
    describe "basic arithmetic"
    [ test "20 × 3 = 60" <|
        \() ->
            start
                |> clickCalcBtn "2"
                |> clickCalcBtn "0"
                |> clickCalcBtn "←"
                |> clickCalcBtn "3"
                |> clickCalcBtn "×"
                |> expectViewHas
                    [ text "60"
                    ]
    ]

This simulates a user clicking on the number and operator buttons. It then checks that the number 60 is somewhere on the page. Try playing with this and adding another test.

The next and last chapter will cover deploying our Elm application to netlify. If you got this far, congratulations! We're almost finished. I get a lot of satisfaction with web projects because they are so easy to share with the world. I'll show you how in the next chapter.

Elm Calculator Part 9 - Combination Key Input

Ryan Frazier — Fri, 08 May 2020 00:00:00 +0000

This post is part of a series. To see all published posts in the series see the tag "elm calculator book".If you wish to support my work you can purchase the book on gumroad.

This project uses Elm version 0.19

Part 1 - Introduction
Part 2 - Project Setup
Part 3 - Add CSS
Part 4 - Basic Operations
Part 5 - Adding Decimal Support
Part 6 - Supporting Negative Numbers
Part 7 - Add Dirty State
Part 8 - Support Keypad Input
Part 9 - Combination Key Input (this post)
Part 10 - Testing
Part 11 - Netlify Deployment

browse: https://gitlab.com/pianomanfrazier/elm-calculator/-/tree/v0.9
diff: https://gitlab.com/pianomanfrazier/elm-calculator/-/compare/v0.9...v0.10
ellie: https://ellie-app.com/72nYc5Zj9Hma1

Users can press backspace to delete a single digit. How would we allow the user to clear the whole input area? Or clear the whole stack?

We'll provide a keyboard combination to support this. So we can allow users to press CTRL + BACKSPACE and it would clear the input box and CTRL + SHIFT + BACKSPACE would clear the whole stack.

We have already done the hard work in the previous chapter. We need to tweak our update function to check for CTRL + SHIFT or just CTRL before we check the other keys.

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        ...
        HandleKeyboardEvent event ->
            if event.ctrlKey && event.shiftKey then
                case event.keyCode of
                    KK.Backspace ->
                        update ClearAll model
                    _ ->
                        ( model, Cmd.none )
            else if event.ctrlKey then
                case event.keyCode of
                    KK.Backspace ->
                        update Clear model
                    _ ->
                    ( model, Cmd.none )
            else
                case event.keyCode of
                    KK.Multiply ->
                        ...

And that's it. We now have key combos.

The next chapter will cover testing. We will write a test using elm-test and elm-program-test to verify our calculator.

Elm Calculator Part 8 - Support Keypad Input

Ryan Frazier — Fri, 01 May 2020 00:00:00 +0000

This post is part of a series. To see all published posts in the series see the tag "elm calculator book".If you wish to support my work you can purchase the book on gumroad.

This project uses Elm version 0.19

Part 1 - Introduction
Part 2 - Project Setup
Part 3 - Add CSS
Part 4 - Basic Operations
Part 5 - Adding Decimal Support
Part 6 - Supporting Negative Numbers
Part 7 - Add Dirty State
Part 8 - Support Keypad Input (this post)
Part 9 - Combination Key Input
Part 10 - Testing
Part 11 - Netlify Deployment

browse: https://gitlab.com/pianomanfrazier/elm-calculator/-/tree/v0.8
diff: https://gitlab.com/pianomanfrazier/elm-calculator/-/compare/v0.7...v0.8
ellie: https://ellie-app.com/72nXvQqPq37a1

It would be nice if users could input numbers into our calculator using their number pad on their keyboard.

We need to tell our program what to do when a user presses these keys. So we need to add some more messages to our application.

We will be using the package Gizra/elm-keyboard-event.

First we need to install the package so we can import it into our code. The ellie-app version of this chapter has the package installed. Open the side menu and look at the installed packages. You should see I have added 3 new packages as dependencies.

To install a package in ellie-app use the search bar.

Or you can install a package locally on the command line.

elm install Gizra/elm-keyboard-event

We will also need to import SwiftsNamesake/proper-keyboard which is a dependency of elm-keyboard-event. We need this because we will be using these types directly in our application.

elm install SwiftsNamesake/proper-keyboard

And lastly we need elm/json to decode the JSON message coming from the browser for our events. Don't worry. This is not as scary as it sounds.

elm install elm/json

Refactor to use Elm subscriptions

Since these keyboard events are going to be coming from the browser, our Elm application needs to subscribe to these events. In order to do subscriptions we need to refactor our application.

Right now we have been using Browser.sandbox in our main function.

main : Program () Model Msg
main =
    Browser.sandbox
        { init = initialModel
        , view = view
        , update = update
        }

Change to `Browser.element`

We need to change it to Browser.element so that we can add subscriptions.

main : Program () Model Msg
main =
    Browser.element
        { view = view
        , init = \_ -> init
        , update = update
        , subscriptions = subscriptions
        }

This is going to impact our whole application. We'll let the compiler guide us through this refactor. The biggest change will be to our update function.

It will need to change from

update : Msg -> Model -> Model

update Msg -> Model -> ( Model, Cmd Msg )

We need to return the model and a command message. We won't be using command messages in this application so don't worry about it. We just need to fix the code so it will compile again.

Most of the time we can just return the tuple ( model, Cmd.none ).

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        SetDecimal ->
            if String.contains "." model.currentNum then
                ( model, Cmd.none )
            ...

The init also needs to return a command message.

init : ( Model, Cmd Msg )
init =
    ( { stack = []
        , ...
        }
    , Cmd.none
    )

Add subscriptions

Now we can work on adding the subscriptions. First we need to import some stuff.

import Browser.Events exposing (onKeyDown)
import Json.Decode as D
import Keyboard.Event as KE exposing (KeyboardEvent, decodeKeyboardEvent)
import Keyboard.Key as KK

We are now going to subscribe to the onKeyDown event in the browser. After our application gets the event we then need to decode the event into something Elm can deal with. Since events come in the from the browser as a JSON message we need to decode the JSON into an Elm type.

Luckily for us, we don't need to worry about writing a decoder for these events. The Gizra/elm-keyboard package provides this for us.

subscriptions : Model -> Sub Msg
subscriptions model =
    onKeyDown (D.map HandleKeyboardEvent decodeKeyboardEvent)

This subscriptions function is going to return a subscription message. In this case a HandleKeyboardEvent type.

We need that in our message type.

type Msg
    = ...
    | HandleKeyboardEvent KeyboardEvent

Handle the key events

Now we can put this message and handle it in our update function.

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        ...
        HandleKeyboardEvent event ->
            case event.keyCode of
                KK.Add ->
                    update (InputOperator Add) model
                KK.Subtract ->
                    update (InputOperator Sub) model
                KK.NumpadZero ->
                    update (InputNumber 0) model
                ...
                -- ignore anything else
                _ -> ( model, Cmd.none )

I used a small trick here. When we get a key matching one of our cases, just call the appropriate update function again.

What I hope you take away from this chapter is how nice it is to refactor things in Elm. We made some sweeping changes to our application and the compiler was able to help us out.

Now that we have keyboard input, it would be nice if the user had some more options for deleting the stack frames. The next chapter will cover using key combinations such as ctrl-shift-delete to clear out the frames.

Elm Calculator Part 7 - Add Dirty State

Ryan Frazier — Fri, 24 Apr 2020 00:00:00 +0000

This post is part of a series. To see all published posts in the series see the tag "elm calculator book".If you wish to support my work you can purchase the book on gumroad.

This project uses Elm version 0.19

Part 1 - Introduction
Part 2 - Project Setup
Part 3 - Add CSS
Part 4 - Basic Operations
Part 5 - Adding Decimal Support
Part 6 - Supporting Negative Numbers
Part 7 - Add Dirty State (this post)
Part 8 - Support Keypad Input
Part 9 - Combination Key Input
Part 10 - Testing
Part 11 - Netlify Deployment

This allows users to overwrite the input area with a new number if the calculator is in a dirty state.

browse: https://gitlab.com/pianomanfrazier/elm-calculator/-/tree/v0.7
diff: https://gitlab.com/pianomanfrazier/elm-calculator/-/compare/v0.6...v0.7
ellie: https://ellie-app.com/72p3SNcV8Fva1

The way it works is if a user has just entered a number in, the input area is now dirty. Users can press enter again to keep pushing that same number on the stack. Or they can start typing a new number and it will over-write the existing number.

We need to add another piece of state to our model.

type alias Model =
    { stack : List Float
    , currentNum : String
    , error : Maybe String
    , dirty : Bool
    }

initialModel : Model
initialModel =
    { stack = []
    , currentNum = "0"
    , error = Nothing
    , dirty = False
    }

In the model update we need to add some logic around when the input field is dirty.

We need to do this to the Clear, Enter, InputOperator, SetDecimal, SetSign, and InputNumber messages.

Note: When I initially wrote the code I forgot to flip the flag on SetDecimal and SetSign. The Master branch has this fix. v0.7 does not.

Clear ->
    { model | currentNum = "0", dirty = False }

Enter ->
    ...
    { model
        | ...
        , dirty = True
    }

InputOperator operator ->
    ...
    { model
        | ...
        , dirty = True
    }

InputNumber num ->
    ...
    else if model.dirty then
        { model
            | ...
            , dirty = False
        }

The next chapter is going to add support for users to enter numbers into the calculator using their number pad on their keyboard.

Elm Calculator Part 6 - Supporting Negative Numbers

Ryan Frazier — Fri, 17 Apr 2020 00:00:00 +0000

This post is part of a series. To see all published posts in the series see the tag "elm calculator book".If you wish to support my work you can purchase the book on gumroad.

This project uses Elm version 0.19

Part 1 - Introduction
Part 2 - Project Setup
Part 3 - Add CSS
Part 4 - Basic Operations
Part 5 - Adding Decimal Support
Part 6 - Supporting Negative Numbers (this post)
Part 7 - Add Dirty State
Part 8 - Support Keypad Input
Part 9 - Combination Key Input
Part 10 - Testing
Part 11 - Netlify Deployment

browse: https://gitlab.com/pianomanfrazier/elm-calculator/-/tree/v0.6
diff: https://gitlab.com/pianomanfrazier/elm-calculator/-/compare/v0.5...v0.6
ellie: https://ellie-app.com/72p2Gt2gpkXa1

Users need to be able to input negative numbers. Since negatives are different than the subtract operation we need to handle this separately.

Many RPN calculators I have seen have a toggle sign button.

section : Html Msg
section =
    div [ class "section" ]
    [ ...
    , cell (onClick SetSign) Single White "+/-"
    , cell (onClick Enter) Single Yellow "Enter"
    ]

And then let's add the message type and update the model.

type Msg
    = ...
    | SetSign

We need to do some string checking to make this work.

update : Msg -> Model -> Model
update msg model =
    case msg of
        ...
        SetSign ->
            -- don't allow the user to make a negative zero
            if model.currentNum == "0" then
                model

            -- drop the negative sign from the string
            else if String.startsWith "-" model.currentNum then
                { model | currentNum = String.dropLeft 1 model.currentNum }
            -- add the negative sign
            else
                { model | currentNum = "-" ++ model.currentNum }

And that's it. We now have a working calculator.

The next few chapters will be adding some nice extra features.

Elm Calculator Part 5 - Adding Decimal Support

Ryan Frazier — Fri, 10 Apr 2020 00:00:00 +0000

This post is part of a series. To see all published posts in the series see the tag "elm calculator book".If you wish to support my work you can purchase the book on gumroad.

This project uses Elm version 0.19

Part 1 - Introduction
Part 2 - Project Setup
Part 3 - Add CSS
Part 4 - Basic Operations
Part 5 - Adding Decimal Support (this post)
Part 6 - Supporting Negative Numbers
Part 7 - Add Dirty State
Part 8 - Support Keypad Input
Part 9 - Combination Key Input
Part 10 - Testing
Part 11 - Netlify Deployment

browse: https://gitlab.com/pianomanfrazier/elm-calculator/-/tree/v0.5
diff: https://gitlab.com/pianomanfrazier/elm-calculator/-/compare/v0.3...v0.5
ellie: https://ellie-app.com/72nWGqwYmXSa1

In the last chapter, we input numbers as floats and did some math to shift the numbers around. This will be a big problem when we start to introduce decimals.

Failed attempt still using floats

You'll notice that I skipped v0.4 of the app. This was my failed attempt to keep using math to manipulate the user input number.

If we try to do something similar with floats we get the following.

> 0.1 + 0.02
0.12000000000000001 : Float

Here is my code for reference.

browse: https://gitlab.com/pianomanfrazier/elm-calculator/-/tree/v0.4
diff: https://gitlab.com/pianomanfrazier/elm-calculator/-/compare/v0.3...v0.4
ellie: https://ellie-app.com/72nWgBWynwRa1

Change inputNumber to String

Again like before, I like to start a new feature or refactor by changing the model.

type alias Model =
    { stack : List Float
    , currentNum : String
    }

initialModel : Model
initialModel =
    { stack = []
    , currentNum = "0"
    }

As you can see in the model only the currentNum is a String. At some point we need to parse our input into an actual number so we can do operations on it. We'll do that when we push the number to the stack.

The way we'll parse is using String.toFloat. Let's play around with this function in the elm repl. If you have elm installed, go to a terminal and type elm repl.

As of writing this book the official Elm Guide https://guide.elm-lang.org/core_language.html has a live repl you can play with on the webpage. No installation necessary. This is helpful if you have been following along on ellie-app.

> String.toFloat
<function> : String -> Maybe Float

Why does it return a Maybe Float? What happens if we try to give this function a string that isn't a number?

> String.toFloat "abcd"
Nothing : Maybe Float
> String.toFloat "123.456"
Just 123.456 : Maybe Float

This is Elm's way of dealing with uncertainty. If it can't parse it, it will return a Nothing otherwise it will return a Just <some float>. Let's look at some other examples and then we'll explore this Maybe thing a bit more.

Again, Elm types are powerful but take some getting used to.

Parse float in JavaScript and Python

Here is the same thing in JavaScript.

» parseFloat("abcd")
← NaN
» parseFloat("123.456")
← 123.456

And again in Python.

>>> float("123.456")
123.456
>>> float("abcd")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: could not convert string to float: 'abcd'

No matter what language we are using, we need to deal with these kind of errors. In Elm it uses the Maybe type. JavaScript returns NaN, not a number. And Python throws a ValueError.

The Maybe type

The Maybe type is something that took me a while to understand. I had been writing quite a bit of Elm code but I just kind of ignored it. Hopefully I can make it click for you sooner.

Let's play around with the Maybe type in the elm repl.

The Maybe type is defined as the following.

type Maybe
    = Just a
    | Nothing

What this means is that Just can hold any value.

> Just 1
Just 1 : Maybe number
> Just 1.2
Just 1.2 : Maybe Float
> Just "123.456"
Just "123.456" : Maybe String
> Just (Just 1)
Just (Just 1) : Maybe (Maybe number)
> Just Nothing
Just Nothing : Maybe (Maybe a)

And Nothing is just nothing.

> Nothing
Nothing : Maybe a

So how is this useful?

Let's go back to parsing strings. The compiler will make sure we deal with the case our string doesn't parse into a number.

parsedNumber = String.toFloat model.currentNum

What is the type of parsedNumber? It's a Maybe Float. Meaning it can be Just Float or it can be Nothing. We can now pattern match on these two cases.

case parsedNumber of
    Nothing ->
        -- deal with the case it doesn't parse
    Just num ->
        -- yay it parsed! Do something with num

This is how Elm in practice has no runtime errors. The compiler will help us to think about uncertainty and require us to deal with it.

Now that we know about Maybe we can continue on.

Push the parsed float to the stack

Now that we can parse strings to floats we can update the model when a user clicks "Enter".

update : Msg -> Model -> Model
update msg model =
    case msg of
        ...
        Enter ->
            let
                maybeNumber =
                    String.toFloat model.currentNum
            in
            case maybeNumber of
                Nothing ->
                    { model | error = Just "PARSE ERR" }
                Just num ->
                    { model
                    | stack = num :: model.stack
                    , currentNum = "0"
                    }

The compiler will now tell us that there is no error field in our model. So let's add that.

type alias Model =
    { stack : List Float
    , currentNum : String
    , error : Maybe String
    }

initialModel : Model
initialModel =
    { stack = []
    , currentNum = "0"
    , error = Nothing
    }

We might not have an error, so we'll make the error a Maybe.

We also need to display the error if it exists. Let's pattern match on the error in our view to display the error.

case model.error of
    Nothing ->
        inputBox (text model.currentNum)
    Just err ->
        inputBox (span [class "error"] [text err])

Input the decimal

Inputing the decimal requires some special treatment. Users should not be able to put in multiple decimals into a number.

First add the message.

type Msg
    = InputOperator Operator
    | ...
    | SetDecimal

Then handle the message in the update.

update : Msg -> Model -> Model
update msg model =
    case msg of
        SetDecimal ->
            if String.contains "." model.currentNum then
                model
            else
                { model | currentNum = model.currentNum ++ "." }

Now we need to be able to input negative numbers and we will have a fully functioning calculator. The next chapter will add negative number support.

Elm Calculator Part 4 - Basic Operations

Ryan Frazier — Fri, 03 Apr 2020 00:00:00 +0000

This post is part of a series. To see all published posts in the series see the tag "elm calculator book".If you wish to support my work you can purchase the book on gumroad.

This project uses Elm version 0.19

Part 1 - Introduction
Part 2 - Project Setup
Part 3 - Add CSS
Part 4 - Basic Operations (this post)
Part 5 - Adding Decimal Support
Part 6 - Supporting Negative Numbers
Part 7 - Add Dirty State
Part 8 - Support Keypad Input
Part 9 - Combination Key Input
Part 10 - Testing
Part 11 - Netlify Deployment

browse: https://gitlab.com/pianomanfrazier/elm-calculator/-/tree/v0.3
diff: https://gitlab.com/pianomanfrazier/elm-calculator/-/compare/v0.2...v0.3
ellie: https://ellie-app.com/72nTbWP6rjka1

Now that we have a good looking calculator, we can add some functionality. We need to do 2 things do have something working.

Push stuff to the stack
Do operations on the stack

Whenever I start a new feature in Elm I start with the Model.

type alias Model =
    { stack : List Float
    , currentNum : Float
    }

initialModel : Model
initialModel =
    { stack = []
    , currentNum = 0
    }

Let's also output some debugging information to see what's going on as we work. We can turn on the time travelling debugger by restarting our elm-live server with the --debug flag.

npx elm-live src/Main.elm --hot --open -- --output=elm.js --debug

Now you should see the debugger in the bottom left side of your browser window.

If you click on it the window will show you the model.

Display the stack

We also need a way to view the stack. Let's update the view function.

The resulting HTML will look something like this.

<div class="calculator">
    <!-- THE STACK -->
    <div class="input-box"></div>
    <div class="input-box"></div>
    <div class="input-box"></div>
    <!-- THE INPUT BOX -->
    <div class="input-box"></div>
    <!-- THE CALCULATOR BUTTONS -->
    <div class="section">
    ...
    </div><!-- section -->
</div><!-- calculator -->

We already created the input box in the previous chapter. We can reuse that function to display the stack.

Now we need to loop through the stack and print it out. We do this by using List.map.

List.map inputBox model.stack

If we look at the function signature of List.map in the Elm repl this is what we get.

> List.map
> <function> : (a -> b) -> List a -> List b

What this is telling us is that it takes a function a -> b and a list List a and outputs a new list List b. Notice how the first list matches the first argument of the input function a. And the output list matches the output of the input function b.

If we do this the stack will be displayed from top to bottom. RPN calculators usually show the stack from the top to bottom so we need to reverse the stack before we print it out.

List.map inputBox (List.reverse model.stack)

Here is the final Elm code in our view function. We place the stack on top of our input box and the button grid.

view : Model -> Html Msg
view model =
    div
        [class "calculator"]
        (List.map
            inputBox
            (List.reverse model.stack)
        ++ [ inputBox model.currentNum
           , section
           ]
        )

Input numbers

We now need to attach an event to each button in our button grid. All events in Elm are handled as messages to our update function. We'll need to tweak our cell function to take an event listener.

Let's first define the message that will be sent to the update function.

type Msg
    = InputNumber Float

Now we need to handle that message in our update function.

update : Msg -> Model -> Model
update msg =
    case msg of
        InputNumber num ->
            { model | currentNum = num }

Now we can attach the event to our buttons. Be sure to import onClick at the top of the file.

import Html.Events exposing (onClick)

...

cell (onClick (InputNumber 1)) Single White "1"

And finally we need to change the cell function to recieve this onClick message. If you are unsure what the type signature of a thing is usually your code editor can tell you if you hover over the thing in question. Another way is to make your best guess and let the compiler error tell you what type it was expecting.

In this case onClick is an Html.Attribute Msg.

cell : Html.Attribute Msg -> Size -> Color -> String -> Html Msg
cell attr size color content =
    button
        [ ...
        , attr
        ]
        [text content]

Now we can add the onClick event to every button and we will be able to input any digit.

section : Html Msg
section =
    div
        [class "section"]
        [ cell ...
        , cell (onClick (InputNumber 1)) Single White "1"
        , cell (onClick (InputNumber 2)) Single White "2"
        , cell (onClick (InputNumber 3)) Single White "2"
        , ...
        ]

If you look back in the view funtion we already set it up so that model.currentNum is being displayed.

Homework

You will learn best by struggling to do something yourself. Try to pick it up from here and do the following.

Implement the clear button event.
Implement the back button (i.e. 123 [press back] 12 [press back] 1)
Input larger numbers. Not only single digits.

And if you are really ambitious you could finish up this chapter by doing

Push a number to the stack
Perform operations on the stack

Try it first. If you get stuck I'm going to go through pushing to the stack and doing operations in the next two sections.

Push numbers onto the stack

Now that we can input numbers, we can now push things onto the stack.

Let's first create an Enter message.

type Msg
    = InputNumber Float
    | Enter

And then add the event to our button.

cell (onClick Enter) Double Yellow "Enter"

Now what needs to happen to our model when the user clicks "Enter"?

We need to push the model.currentNum to the stack. We can do that with the :: cons operator.

1 :: [2, 3] == [1, 2, 3]

See https://package.elm-lang.org/packages/elm/core/latest for more information about list operations.

And we will also reset the model.currentNum to 0.

update : Msg -> Model -> Model
update msg =
    type msg of
        ...
        Enter ->
            { model
            | stack = model.currentNum :: model.stack
            , currentNum = 0
            }

Operate on the stack

Now that we have numbers on the stack we can operate on them.

We need a way to tie an event from our buttons to call a function on our stack.

Let's start by defining our message.

type Msg
    = InputNumber Float
    | ...
    | InputOperator Operator

We have no Operator type so let's add that.

type Operator
    = Add
    | Sub
    | Mult
    | Div

And bind the event to our button.

cell (onClick (InputOperator Add)) Single Yellow "+"

Now we need a way to pop off an element from our stack and do the operator with the model.currentNum.

case model.stack of
    -- the stack is empty to do nothing
    [] ->
        -- just return the model
        model
    -- x is the head of the list
    -- xs is the rest of the list
    x :: xs ->
        -- do stuff here

Let's talk about this pattern a little more. I know for myself coming from Python or JavaScript this looks really weird. Why can't we just do a foreach over the list? In Elm there is no such thing as a for loop. Processing a list is a recursive operation.

Pattern match on a list

There are two cases when dealing with a list. Either it is empty or it has stuff in it.

If there is stuff in it we can deconstruct it with x :: xs.

x :: xs is a nifty way of popping off the first element of the list. x is the first element. xs is the rest of the list.

Since we have popped off the first element, we can now operate on the element with the currentNum. We can then assign the stack to the remaining list, xs.

Handle the model update

And add handle the message in the update.

update : Msg -> Model -> Model
update msg =
    type msg of
        ...
        InputOperator operator ->
            case model.stack of
                [] ->
                -- stack is empty, do nothing
                    model
                -- split up the list and do stuff
                x :: xs ->
                    let
                        -- lookup the function to use
                        op =
                            operatorFunction operator
                        -- do the math
                        newNum =
                            op model.currentNum x
                    in
                    -- now update the model
                    { model
                    | stack = xs
                    , currentNum = newNum
                    }

Ok. So I introduced some new stuff in this code chunk. Let's go through some of the pieces.

`let ... in` blocks

let ... in blocks allow you to define a local scope. I feel it can make the code a lot more readable if you need to manipulate your data around.

Get the operator function

We need to assign a function to each of our Operator types. The function needs to return another function. In this case the function of arithmetic functions takes 2 numbers and returns a number, Float -> Float -> Float.

Putting parens around the + operator, is syntax for, "treat this as a function that takes 2 arguments." It can be used like this: (+) 1 2 == 3.

operatorFunction : Operator -> (Float -> Float -> Float)
operatorFunction operator =
    case operator of
        Add -> (+)
        Sub -> (-)
        ...

Your homework solutions

Hopefully you tried input larger numbers and to implement the clear and back buttons yourself. If you haven't, stop reading and try it. Even if you fail you will learn better than me telling you how to do it.

Input larger numbers

Right now we can only put in a single number. Let's fix that.

update : Msg -> Model -> Model
update msg model =
    ...
    InputNumber num ->
        { model | currentNum = (model.currentNum * 10) + num }
    ...

We need to do a little bit of math to create a larger number. Shift the model.currentNum back and then add the new number.

Clear and back buttons

Let's start by adding Clear and Back to our message type.

type Msg
    = InputOperator Operator
    | InputNumber Float
    | Clear
    | Back
    | ...

Now the compiler will squawk at you to add those two new types to the update function.

MISSING PATTERNS - This `case` does not have branches for all possibilities:
102|#># case msg of
...

Let's add those.

update : Msg -> Model -> Model
update msg model =
    case msg of
        Clear ->
            { model | currentNum = 0 }
        Back ->
            { model
            | currentNum = toFloat <| floor <| model.currentNum / 10
            }

For the Back message we need to undo what we did to create larger numbers. This is getting awkward to do this math to input numbers and will have its limitations when we deal with decimal numbers. We will fix that in the next chapter.

How that we have some basic operations done, the next chapter will introduce decimal numbers.

Forem: Ryan Frazier

What Is Functional Programming

FP Vocabulary

Pure Functions

What is a side effect?

Referential Transparency

No For Loops?

Currying

Exception Throwing is a Side Effect

JavaScript helper libraries

JS Libraries

TypeScript Libraries

Other Resources

Introduction to Algebraic Data Types

Why are they useful?

Animal Names

Immutability

An example with error handling

Case Statement in Typescript

Exceptions Considered Harmful

Pattern 1 - return true or false

Pattern 2 - return null if failed

Pattern 3 - throw exception

Pattern 4 - return a result type

JavaScript tooling

Other libraries and languages

Elm Calculator Part 11 - Netlify Deployment

Add deploy script

Configure Netlify

We're done

Elm Calculator Part 10 - Testing

Some Refactoring

Write the test

Elm Calculator Part 9 - Combination Key Input

Elm Calculator Part 8 - Support Keypad Input

Refactor to use Elm subscriptions

Change to Browser.element

Add subscriptions

Handle the key events

Elm Calculator Part 7 - Add Dirty State

Elm Calculator Part 6 - Supporting Negative Numbers

Elm Calculator Part 5 - Adding Decimal Support

Failed attempt still using floats

Change inputNumber to String

Parse float in JavaScript and Python

The Maybe type

Push the parsed float to the stack

Input the decimal

Elm Calculator Part 4 - Basic Operations

Display the stack

Input numbers

Homework

Push numbers onto the stack

Operate on the stack

Pattern match on a list

Handle the model update

let ... in blocks

Get the operator function

Your homework solutions

Input larger numbers

Clear and back buttons

Change to `Browser.element`

`let ... in` blocks