Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/izdi/elm-cheat-sheet

An overview of Elm syntax and features
https://github.com/izdi/elm-cheat-sheet

cheatsheet education elm functional-programming learn tutorial

Last synced: about 2 months ago
JSON representation

An overview of Elm syntax and features

Awesome Lists containing this project

README

        

# Elm Cheat Sheet

## Table of Contents
1. [Hello World](#hello-world)
2. [Comments](#comments)
3. [Modules](#modules)
* [Imports](#imports)
4. [Tools](#tools)
* [REPL](#repl)
* [Compile](#compile)
* [Packaging](#packaging)
* [Publish](#publish)
* [Documentation](#documentation)
5. [HTML Embedding](#html-embedding)
6. [Primitives](#primitives)
* [Numbers](#numbers)
* [Strings](#strings)
* [Booleans](#booleans)
* [Other](#other)
7. [Collections](#collections)
* [Lists](#lists)
* [Tuples](#tuples)
* [Records](#records)
* [Other](#other)
8. [Functions](#functions)
* [Anonymous](#anonymous)
* [Prefix](#prefix)
9. [Types](#types)
* [Union Types](#union-types)
* [Maybe](#maybe)
10. [Type Aliases](#type-aliases)
11. [Type Annotation](#type-annotation)
12. [Operators](#operators)
* [Arithmetic](#arithmetic)
* [Bitwise](#bitwise)
* [Comparison](#comparison)
* [Logical](#logical)
* [Function Composition](#function-composition)
* [Other](#other)
13. [Control Statements](#control-statements)
* [If](#if)
* [Case-of](#case-of)
* [Let-in](#let-in)
14. [Ports](#ports)

## Elm in a nutshell
- purely functional language
- statically typed
- no runtime exceptions
- outperforms most popular rendering libraries
- package manager
- built-in tooling
- HTML, CSS, JavaScript interoperability
- clean syntax
- I like frontend again...

## Hello World
File `HelloWorld.elm`:
```elm
import Html exposing (h1, text)
import Html.Attributes exposing (id)

-- Hello world example
main =
h1 [id "hw"] [text "Hello World!"]
```

## Comments
```elm
-- Single line comment

{-
Multi-line comment
-}
```

Comments for package [documentation](#documentation)

## Modules
```elm
-- Defining a module that exports everything
module Mymodule exposing (..)

-- Export only specified entities
module Mymodule exposing (Type, value)

-- Export all or specific states of type
module Mymodule exposing
( Error(Forbidden, Timeout)
, Stuff(..)
)

type Error
= Forbidden String
| Timeout String
| NotFound String
```

#### Imports
```elm
-- qualified imports
import String -- String.toUpper, String.repeat
import String as Str -- Str.toUpper, Str.repeat

-- unqualified imports
import Mymodule exposing (..) -- Error, Stuff
import Mymodule exposing ( Error ) -- Error
import Mymodule exposing ( Error(..) ) -- Error, Forbidden, Timeout
import Mymodule exposing ( Error(Forbidden) ) -- Error, Forbidden
```

## Tools
#### REPL
`elm repl` / `elm-repl`

Import required modules
```elm
> import List
```

Get function signature
```elm
> List.map
: (a -> b) -> List a -> List b
> (++)
: appendable -> appendable -> appendable
```

Elm expressions return resulting value and type
```elm
> 1 + 1
2 : number
```

Backslash `\` is for multi-line expressions
```
> fn a b = \
| a + b
: number -> number -> number
```

#### Compile
`elm make` / `elm-make`

```bash
# Default compilation
elm make HelloWorld.elm -> index.html

# Custom name
$ elm make HelloWorld.elm --output hw.js

# Multiple files
$ elm make HelloWorld.elm MyModule.elm --output hw.js

# With warnings
$ elm make HelloWorld.elm --warn

# To HTML
$ elm make HelloWorld.elm --output hw.html
```

#### Packaging
`elm package` / `elm-package`

Installation automatically adds `dependencies` in `package.json`.
```bash
# Install a package
$ elm-package install evancz/elm-html

# Specific version
$ elm-package install evancz/elm-html 1.0.0

# Diff two versions
$ elm-package diff evancz/virtual-dom 2.0.0 2.1.0
Comparing evancz/virtual-dom 2.0.0 to 2.1.0...
This is a MINOR change.

------ Changes to module VirtualDom - MINOR ------

Added:
attributeNS : String -> String -> String -> VirtualDom.Property
```

#### Documentation
Publishing a package requires well documented code.

```elm
module Documentation exposing
( Type
, value
, anyfinCanHappen
)

{-| Module level documentation

# Just a header, what to include below
@docs Type, value

# About Anyfin
@docs anyfinCanHappen

-}

import Random exposing (int)

{-| Type level documentation comment -}
type Type = Bool

{-|-}
-- Empty comment above
value : Int
value = 1 + 1

{-| More on anyfinCanHappen -}
anyfinCanHappen : Generator Int
anyfinCanHappen =
int 0 64

{-| This value is not exported, so isn't required -}
-- Use basic comment syntax
imNotExported =
"Don't need to comment me"
```

* Documentation comment starts `{-|` ends with `-}`
* Module documentation comes after module declaration, before the imports
* Functions are grouped into related sections by keyword `@docs ` and declared with Markdown
* Each exported entity should have documentation comment on top of its declaration

#### Publish
Add `README.md` otherwise publishing will fail

All packages start with initial version `1.0.0`

Versions all have exactly three parts: `MAJOR.MINOR.PATCH`

* `PATCH` - the API is the same, no risk of breaking code
* `MINOR` - values have been added, existing values are unchanged
* `MAJOR` - existing values have been changed or removed

`elm-package.json`
* `source-directories` - array of directories to look up for project source code inside the working directory
* `exposed-modules` - modules that exposed to a user after publishing, kind of interface to your internal API.

```bash
# elm-package.json
source-directories": [
".",
"SubOne",
"SubTwo"
]
"exposed-modules": [
"SubOne",
"Goodmodule",
"Module"
]

├── SubOne
│   └── SubOne.elm # Compiled and exposed
├── SubTwo
│   └── SubTwo.elm # Compiled, but unexposed
├── SubThree
│   └── SubThree.elm # Compiler won't see the source, unexposed to the users
├── README.md
├── elm-package.json
├── Goodmodule.elm # Compiled and exposed
└── Module.elm # Compiled and exposed
```

Publish
```bash
$ git tag -a 1.0.0 -m "initial release"
$ git push --tags

$ elm-package publish
```

Updating
```bash
$ elm-package bump

$ git tag -a 1.0.1 -m "secondary release"
$ git push --tags

$ elm-package publish
```

## HTML Embedding
Running fullscreen
`elm-make HelloWorld.elm` -> `elm.js`
```html

Elm.Main.fullscreen();

```

Embed explicitly in a html element
```html

var elmHolder = document.getElementById('hw-wrapper');

Elm.Main.embed(elmHolder);

```

Run without graphics
```javascript
Elm.Main.worker();
```

## Primitives
#### Numbers
Numeric types are `Int` and `Float`, `number` represents both `Int` and `Float`:
```elm
> 1
1 : number
> 2.0
2 : Float
> truncate 0.1
0 : Int
> truncate 1
1 : Int
```

#### Strings
String types are `Char` and `String`
```elm
> 'a'
'a' : Char
> "Hello"
"Hello" : String
```

Multi-line string
```elm
"""
Hello
World
"""
```

Single quotes are for `char` only
```elm
> 'ab'
-- SYNTAX PROBLEM --
> "ab"
"ab" : String
```

#### Booleans
```elm
> True
True : Bool
> False
False : Bool
```

#### Other
`comparable` - `ints`, `floats`, `chars`, `strings`, `lists`, `tuples`


`appendable` - `strings`, `lists`, `text`.


Kind of dynamic types are represented as `a`, `b`, `c` etc. meaning that you can pass any value, even functions

## Collections
All values and data structures in Elm are immutable.

#### Lists
A `list` holds a collection of related values separated by commas and enclosed in
square brackets. All the values in a list must have the same type:
```elm
> []
[] : List a
> [1,2,3]
[1,2,3] : List number
> ["a", "b", "c"]
["a","b","c"] : List String
```

Ways to create a list
```elm
> List.range 1 4
> [1,2,3,4]
> 1 :: [2,3,4]
> 1 :: 2 :: 3 :: 4 :: []
```

#### Tuples
Tuples package many expressions into a single expression.
They have a minumum of two elements and maximum of nine.
The type of a tuple records the number of components and each of their types.
```elm
> (1, "2", True)
(1,"2",True) : ( number, String, Bool )
```

It's also possible to use commas as a tuple function, like a [prefix operation](#prefix).
```elm
> (,,,) 1 True 'a' []
(1,True,'a',[]) : ( number, Bool, Char, List a )
```

Destructuring
```elm
(x, y) = (1, 2)
> x
1 : number
```

#### Records
A `record` is a collection of key/value pairs,
similar to objects in JavaScript or dictionary in Python
```elm
myRecord =
{ style = "Blue",
number = 1,
isCool = True
}
```

Accessing records
```elm
> myRecord.style
"Blue" : String
> .style myRecord
"Blue" : String
```

Updating records returns a new record
```elm
> updatedRecord = { myRecord | style = "Red", number = 10, isCool = False }
> myRecord.style
"Blue" : String
> updatedRecord.style
"Red" : String
```

Destructuring
```elm
{ style, number, isCool } = myRecord
> style
"Blue" : String
```

Extensible records

```elm
-- good usecase for extensible records is to be able to compose records and to be able to define functions that work on different kinds of records

-- define a type of record that has some properties and could have other properties

type alias Mammal r = {
r | legs : Int
}

-- cat is an example of extending the record Mammal by adding properties name and ageInHumanYears

cat : Mammal
{ name : String
, ageInHumanYears = 13
}

cat =
{ name = "Mittens"
, ageInHumanYears = 13
, legs = 4
}
```

```elm
-- mutate is a function that can work on any Mammal

mutate : Mammal r -> Mammal r
mutate mammal =
{ mammal | legs = mammal.legs + 1 }

mutatedCat = mutate cat
mutatedCat.legs == 5
```

#### Other
Core library also has:
* [Array](http://package.elm-lang.org/packages/elm-lang/core/latest/Array)
* [Dict](http://package.elm-lang.org/packages/elm-lang/core/latest/Dict)
* [Set](http://package.elm-lang.org/packages/elm-lang/core/latest/Set)

## Functions
Basics
```elm
-- function name | arguments names = function body
sum a b = a + b

-- combine arguments in a tuple
sum (a, b) = a + b
```

All functions in Elm are _curried_ by default.

If you have "a function of 2 arguments", it's really a function that takes one argument and returns a function that takes another argument:
```elm
-- Both are equal
myFunction arg1 arg2
((myFunction arg1) arg2)

-- Partial application
> minus x y = (-) x y
: number -> number -> number
> minus1 = minus 1
: number -> number
> minus1 11
-10 : number
```

#### Anonymous
Also known as _lambdas_
```elm
-- (\function arguments -> function body)
-- parenthesized, content starts with backslash
(\n -> n < 0)
(\x y -> x * y)
```

#### Prefix
_Prefix_ notation is when we use [operators](#operators) as regular functions by enclosing them in parentheses.
```elm
-- Normally you would do this
> "abcde" ++ "fghij"
"abcdefghij" : String

-- Prefix
> (++) "abcde" "fghij"
"abcdefghij" : String
```

## Types
#### Union Types
Elm allows to create custom types known as _union types_.

The expression below creates a type which can have one of the values (or _tags_) from the right. _Union types_ tightly coupled with [case-of](#case-of) statement.
```elm
type Movement = Right | Left | Stop
```

Tags bring additional information, after tag itself comes a type or multiple types.
```elm
type Movement
= Right Int
| Left Int
| Stop Bool
| Coordinates (Float, Float)

-- passing to the function
myFunction ( Coordinates (45.7, 67.5) )
```

_Union types_ can also have type variables
```elm
type Person a
= Name String
| Surname String
| Age Int
| About a
```

#### Maybe
A `Maybe` can help you with optional arguments, error handling, and records with optional fields. Think of it as a kind of `null`
```elm
-- Maybe resides in a module
import Maybe exposing ( Maybe(..) )

-- Takes an argument that can be filled with any value
type Maybe a = Just a | Nothing
```

[Type annotation](#type-annotation) explicitly tells that it will give back an `Int` or it won't.
```elm
getId : Int -> Maybe Int
getId id =
if id >= 0 then
Just id
else
Nothing
```

## Type Aliases
You can give existing types a custom name with `type alias`
```elm
type alias Name = String
type alias Dob = String

type alias Record = { name: Name, dob: Dob }
```

We can use it later annotating function
```elm
record : Record
record =
{ name = "Dave", dob = "27/08/1999" }
```

But still `type alias` equals to it's parent `type`
```elm
type alias Name = String

name : Name
name =
"Dave"

secondName : String
secondName =
"Dave"

-- True
name == secondName
```

## Type Annotation
Elm, like most ML dialects, automatically infers most types.

```elm
-- function name : 1st arg type -> 2nd arg type -> return type
fnc : Int -> List -> Int
```
Example below is read as function that takes an __a__ value and returns a __b__ value, list of __a__ values returns a list of __b__ values
```elm
map: (a -> b) -> List a -> List b
```

Pattern matching on record fields
```elm
-- Requires the argument with x and y fields
multiply {x,y} =
x * y
```

Annotating records
```elm
coordinates : { x : Float, y : Float }
coordinates =
{ x = 0,
y = 0
}
```

## Operators
In a nutshell Elm operators are _functions_ that take two arguments.

#### Arithmetic
|Operator|Description|Type hint|
|--------|-----------|----------|
|`+`|addition|`number -> number -> number`
|`-`|subtraction|`number -> number -> number`
|`*`|multiplication|`number -> number -> number`
|`/`|floating point division|`Float -> Float -> Float`
|`//`|integer division, discard the reminder|`Int -> Int -> Int`
|`^`|exponentiation|`number -> number -> number`
|`%`|modulo|`Int -> Int -> Int`

#### Bitwise
|Operator|Description|Type hint|
|--------|-----------|----------|
|`and`|bitwise AND|`Int -> Int -> Int`
|`or`|bitwise OR|`Int -> Int -> Int`
|`xor`|biwise XOR|`Int -> Int -> Int`

#### Comparison
|Operator|Description|Type hint|
|--------|-----------|----------|
|`==`|equal|`comparable -> comparable -> Bool`
|`/=`|not equal|`comparable -> comparable -> Bool`
|`<`|less than|`comparable -> comparable -> Bool`
|`<=`|less than or equal|`comparable -> comparable -> Bool`
|`>`|greater than|`comparable -> comparable -> Bool`
|`>=`|greater than or equal|`comparable -> comparable -> Bool`

#### Logical
|Operator|Description|Type hint|
|--------|-----------|----------|
|`&&`|logical and|`Bool -> Bool -> Bool`
|`\|\|`|logical or|`Bool -> Bool -> Bool`
|`not`|logical not|`Bool -> Bool`

#### Function Composition
|Operator|Description|Type hint|
|--------|-----------|----------|
|`<\|`|backward (pipe) function application `f <\| x == f x`|`(a -> b) -> a -> b`
|`\|>`|forward (pipe) function application `x \|> f == f x`|`a -> (a -> b) -> b`
|`<<`|composes functions into one, arguments first applied to the function from the right side|`(b -> c) -> (a -> b) -> a -> c`
|`>>`|same as before except arguments first applied to the function from the left side|`(a -> b) -> (b -> c) -> a -> c`

#### Other
|Operator|Description|Type hints|
|--------|-----------|----------|
|`++`|put appendable things together|`appendable -> appendable -> appendable`|
|`::`|add an element to the front of a list|`a -> List a -> List a`|
|`as`|keyword that creates aliases for values `(x, y) as t == t = (x, y)`|`a -> a`|

## Control statements
#### If
All the branches of an if need to match so that no matter which one we take, we get back the same type of value overall.
```elm
if a < 1 then
"It's zero"
else
"Non-zero"

-- Multi-line.
if y > 0 then
"Greater"
else if x /= 0 then
"Not equals"
else
"silence"
```

Elm does not have the notion of “truthiness”.

The condition must evaluate to True or False, and nothing else.
```elm
> if 1 then "nope" else "nope again"
- TYPE MISMATCH --
```

#### Case-of
Case tries to match the value of type against patterns defined after the `of` keyword
```elm
type User
= Activated
| Deleted

update state =
case state of
Activated ->
-- do something
Deleted ->
-- do again
```

In case of passing tags with additional properties, parameters are passed along with type checking
```elm
type User
= Activated Int
| Deleted (Int, String)

update state =
case state of
Activated value ->
-- do something with value
Deleted values ->
-- do something with values

update ( Activated 1 )
update ( Deleted (0, "gone") )
```

#### Let-in
`let` allows you to define intermediate values.
```elm
let
x = 3 * 8
y = 4 ^ 2
in
x + y
```

`let` helps simplify complex expressions
```elm
let
activeUsers = List.filter (\u -> u.state /= 1) model.users
in
{ model | user = activeUsers}
```

## Ports
Ports are a general purpose way to communicate with JavaScript.

#### From JavaScript to Elm
```elm
-- declare that this module uses ports
port module Main exposing (..)

-- define port
port portName : (String -> msg) -> Sub msg
```

```javascript
var main = Elm.Main.embed(div);

// send into port
main.ports.portName.send("Port value");
```

#### From Elm to JavaScript
```elm
port showPortName : String -> Cmd msg
```

```javascript
function logName(name) {
console.log(name);
}

// subscribe to receive events
main.ports.showPortName.subscribe(logName);

// unsubscribe
main.ports.showPortName.unsubscribe(logName);
```

#### Type interoperability
|JavaScript|Elm|
|----------|---|
|Booleans|Bool|
|Numbers|Int, Float|
|Strings|Char, String|
|Arrays|List, Array, Tuples (fixed-length)|
|Objects|Records|
|JSON|[Json.Encode.Value](http://package.elm-lang.org/packages/elm-lang/core/latest/Json-Encode#Value)|
|null|Maybe Nothing|