Language manual

Expression syntax

Expressions are the core building blocks of programs in Coal. They include variables, literals, let-bindings, operators, and control structures like if-then-else. An expression can often be composed of other, smaller expressions. For example, a binary operator consists of two sub-expressions: its left-hand side and right-hand side operands:

  (+)     
  / \     x and y are sub-expressions of the expression x + y
 x   y

Variables

A variable in Coal is simply a name bound to a value. Unlike in imperative languages, it is not very meaningful to think of a variable as a “box” that represents some data store in memory. In functional programming, expressions behave more like mathematical expressions: once a variable is defined, its value never changes.

Naming rules

Variable names are subject to the following rules:

• A name can consist of letters (A-Z, a-z), digits (0-9), and the underscore character (_).
• The first character of a variable name must be a lowercase letter or an underscore.
• Variable names are case-sensitive, meaning that my_VAR and my_var refer to different variables.
• Variable names cannot contain spaces.
• Special characters other than underscores (e.g., !, #, %, @) are not permitted in variable names.

Reserved keywords

Reserved language keywords cannot be used as variable names. They are:

alias           float           int64           trait
as              fn              let             true         
bignum          fold            match           type
bool            fun             module          unit 
char            if              nat             when       
double          import          or              where
do              in              otherwise       with            
else            instance        string          
false           int32           then           

Shadowing considered harmful

Shadowing occurs when a variable declared in an inner scope has the same name as a variable from an outer scope.

fun go(x) =
  let x = 3 in x + 3fun go(x) =
  let x = 3 in x + 3

In this example, the inner let attempts to declare a new variable that has the same name as the function parameter, namely x.

Because shadowing is often a source of subtle bugs, the Coal compiler treats it as an error.

Literal expressions

A literal is an expression that directly represents a fixed value. It is either one of the built-in primitive types, such as integers, booleans, or strings, or a composite value, like lists or tuples.

Integral types

Integer literals introduced in code without an explicit type annotation, such as

let answer = 42let answer = 42

are overloaded. The inferred type of this expression is n with (Numeric<n>), which means that n can be any type, as long as it implements the Numeric trait (see Traits). This includes the built-in int32, int64, float, double, bignum, and nat types. All Numeric types support the basic arithmetic operations of addition, subtraction, and multiplication. For example:

fun sum_of(x, y, z) = 
  x + y + z 
fun sum_of(x, y, z) = 
  x + y + z 

In this example, the function sum_of is polymorphic: it can operate on any type that implements Numeric. With explicit type annotations:

fun sum_of(x : a, y : a, z : a) : a with (Numeric<a>) = fun sum_of(x : a, y : a, z : a) : a with (Numeric<a>) = 

We can then use sum_of in the following way:

let n : int32  = sum_of(1, 2, 3)
let d : double = sum_of(0.5, 1.0, 1.5)let n : int32  = sum_of(1, 2, 3)
let d : double = sum_of(0.5, 1.0, 1.5)

The expected types of n and d specialize the first call to int32 and the second to double, respectively.

Function application

Unlike Haskell, ML, and OCaml, Coal uses parentheses and commas to separate arguments in function applications — a syntax more akin to languages like C, Java, or Python. For example:

concat("one", "two")concat("one", "two")

This applies the function concat to the arguments "one" and "two".

By default, functions are curried. There is a difference between a function that takes multiple arguments, and one that takes a single tuple as its argument. Consider the following two type signatures:

f : a -> b -> c
g : (a, b) -> cf : a -> b -> c
g : (a, b) -> c

The first of these is in curried form, which is usually more convenient to work with. Curried functions can be partially applied. This is useful, for example, when working with higher-order functions. Suppose we define an addition function:

fun add(x, y) = x + yfun add(x, y) = x + y

Using partial application, we can create a new function increment by supplying just one argument to add:

let increment = add(1)let increment = add(1)

Partially applied functions can also be passed directly to a higher-order function like map:

map(add(1), [1, 2, 3, 4])   // which yields the same result as map(increment, [1, 2, 3, 4])map(add(1), [1, 2, 3, 4])   // which yields the same result as map(increment, [1, 2, 3, 4])

If-then-else

If-expressions in Coal are similar to those found in many programming languages, especially other functional languages. Both the then and else clauses must be present, and they must produce values of the same type:

if (%e_1 : bool) then %e_2 : %t else %e_3 : %tif (%e_1 : bool) then %e_2 : %t else %e_3 : %t

For example:

if (temperature > 20) then wear("shorts") else go_home()if (temperature > 20) then wear("shorts") else go_home()

Let-bindings

A let-binding introduces a new scope by matching a pattern against the result of an expression. The variables bound by the pattern become available within the expression following the in keyword:

let %pattern = %e_1 in %e_2

Variables form the simplest form of pattern, namely one that matches any value and binds it to a name:

let name = "Zlatan" let name = "Zlatan" 

The pattern used on the left-hand side must be such that it is guaranteed to match the result of the expression %e_1. For example:

// Destructuring with a tuple
let (x, y) = (1, 2) in x + y

// Matching nested records
let { tidbits = { f = a | _ } } = compute(4)// Destructuring with a tuple
let (x, y) = (1, 2) in x + y

// Matching nested records
let { tidbits = { f = a | _ } } = compute(4)

  (fn(f) => (f(3 : int32), f("three")))(fn(x) => x)  (fn(f) => (f(3 : int32), f("three")))(fn(x) => x)

  let id = fn(x) => x 
    in 
      (id(3 : int32), id("three"))  let id = fn(x) => x 
    in 
      (id(3 : int32), id("three"))

Name binding semantics

A subtle but important detail that makes let-bindings in Coal different from those in most other languages is that the identifier introduced by a let is not in scope within the definition itself. In other words, let x = e1 in e2 makes x available in e2, but not in e1. In the ML-family of languages (e.g. OCaml), this is also the case for the standard let keyword. However, in these languages, a special let rec syntax makes it possible to evade this restriction. Coal doesn’t have an equivalent to let rec. This prevents non-well-founded expressions, such as let f = f in f, but more generally, makes it impossible for any function to refer to itself. The restriction also applies to top-level definitions. For example, as far as the compiler is concerned, the function

fun fib(n) = if (n == 0 || n == 1) then n else fib(n - 1) + fib(n - 2)fun fib(n) = if (n == 0 || n == 1) then n else fib(n - 1) + fib(n - 2)

translates into:

let fib = fn(n) => if (n == 0 || n == 1) then n else fib(n - 1) + fib(n - 2)
                                                     ^^^
Error: Name "fib" not in scopelet fib = fn(n) => if (n == 0 || n == 1) then n else fib(n - 1) + fib(n - 2)
                                                     ^^^
Error: Name "fib" not in scope

In fact, one can think of a module as one big let-binding, only laid out in a more readable way:

  let
    some_function = fn(...) => ...
      in
        let
          some_other_function = fn(...) => ...
            in
              let 
                main = fn() => 
                  ...  let
    some_function = fn(...) => ...
      in
        let
          some_other_function = fn(...) => ...
            in
              let 
                main = fn() => 
                  ...

This is why functions such as the fibonacci function above are rejected by the compiler.

Lambda expressions

An anonymous (lambda) function is declared with the fn keyword and the “fat” arrow (=>) symbol:

fn(%arg_1, %arg_2, ..., %arg_n) => %expr

Function expressions are first-class objects; they can be passed as arguments to other functions, assigned and stored inside data structures, etc.

fun apply_fst(xs, x : int32) =
   match(xs) {
     | f :: _ => f(x)
     | [] => 0
   }

fun main() =
  let fns = 
    [ fn(x) => x + 1
    , fn(x) => x + 2
    , fn(x) => x + 3
    ]
  in
    trace_int32(apply_fst(fns, 3))fun apply_fst(xs, x : int32) =
   match(xs) {
     | f :: _ => f(x)
     | [] => 0
   }

fun main() =
  let fns = 
    [ fn(x) => x + 1
    , fn(x) => x + 2
    , fn(x) => x + 3
    ]
  in
    trace_int32(apply_fst(fns, 3))

Just like with let-bindings, the arguments in a lambda-function are patterns:

fn((lhs, rhs)) => lhsfn((lhs, rhs)) => lhs

Function binding let syntax

In addition to ordinary value bindings, let-expressions support a convenient function binding syntax. A definition of the form

let
  add(x, y) =
    x + y
  in 
    ...let
  add(x, y) =
    x + y
  in 
    ...

is syntactic sugar for binding add to a lambda expression:

let
  add =
    fn(x, y) =>
      x + y
    in 
      ...let
  add =
    fn(x, y) =>
      x + y
    in 
      ...

Operators

Arithmetic and comparison

The basic arithmetic operators are overloaded and work with all types for which there exists an instance of the appropriate trait (explained under Built-in traits).

Logical

Coal supports the standard logical operators for working with boolean values.

Data

Algebraic structures

Function composition and pipelining

List operations

String manipulation

Reverse application pipelining

The operator |. is the reversed version of ordinary function application. For example, instead of:

let my_list = [1, 2, 3] in
  map(fn(x) => 2 ^ x, [1, 2, 3])let my_list = [1, 2, 3] in
  map(fn(x) => 2 ^ x, [1, 2, 3])

we can write:

let my_list = [1, 2, 3] in
  my_list |.map(fn(x) => 2 ^ x)let my_list = [1, 2, 3] in
  my_list |.map(fn(x) => 2 ^ x)

This way of expressing operations resembles method invocation in object-oriented programming. It is very convenient when chaining together multiple function calls. Suppose we have the following basic drawing API:

circle       : Config -> Shape
fill         : string -> Shape -> Shape
set_position : float -> float -> Shape -> Shape
draw_shape   : Shape -> Canvas -> Canvas

To describe a sequence of steps that creates a circle, sets properties such as its color and position, and finally places it on the canvas, we would normally write:

draw_shape(set_position(10.0f, 5.0f, fill("blue", circle({ radius = 5.0f }))), canvas)draw_shape(set_position(10.0f, 5.0f, fill("blue", circle({ radius = 5.0f }))), canvas)

Using the reverse function application operator, we could instead write the above in a more readable pipeline-style:

circle({ radius = 5.0f })
  |.fill("blue")
  |.set_position(10.0f, 5.0f)
  |.flip(draw_shape, canvas)circle({ radius = 5.0f })
  |.fill("blue")
  |.set_position(10.0f, 5.0f)
  |.flip(draw_shape, canvas)

Type annotations

Type annotations explicitly specify the type of an expression or pattern. While Coal's type inference can usually determine types automatically, annotations are useful for documentation, catching errors early, and disambiguating when multiple types are possible. Annotations can appear in many contexts: let-bindings, function parameters, lambda arguments, match patterns, and standalone expressions.

A type annotation is written in postfix form, as a colon (:) followed by the type:

<expr> : type

<pattern> : type

For example, you can specify the exact type of a numeric expression:

5 + 3 : int325 + 3 : int32

Or annotate a pattern in a function parameter:

fun process(value : string) = ...

In let-expressions, you can annotate variables to specify their type:

let x : int32 = 42let x : int32 = 42

When provided, the compiler verifies that the annotated type matches the inferred type, reporting an error if there's a mismatch.

Comments

There are two types of comments:

• Single-line comments begin with a double forward slash (//) and extend to the end of the line. Any text following // is considered a comment.

foo(1)  // Leave any comments about this comment in the comment field below.foo(1)  // Leave any comments about this comment in the comment field below.

• Multi-line comments (also called block comments) start with /* and end with */. All text between these delimiters is treated as a comment.

/* This is a long comment. It can extend over multiple 
   lines. It may or may not contain ASCII art depicting,
   for example, a giraffe. 

       (\-/)
      (:O O:)
       \   /o\
        | |\o \  
        (:) \ o\  
             \o \--_ 
             ( o O
             (  O
*/
fun sqrt(d : double) =
  .../* This is a long comment. It can extend over multiple 
   lines. It may or may not contain ASCII art depicting,
   for example, a giraffe. 

       (\-/)
      (:O O:)
       \   /o\
        | |\o \  
        (:) \ o\  
             \o \--_ 
             ( o O
             (  O
*/
fun sqrt(d : double) =
  ...

Types

Built-in language primitives

Coal provides the following built-in types:

Numeric types

Coal has six distinct numeric types.

1. int32
2. int64
3. float
4. double
5. bignum
6. nat

Integer types

The fixed-size integer types int32 and int64 provide efficient arithmetic for most common use cases. Use int32 for typical counting and indexing operations, and int64 when you need a larger range.

let small : int32 = 42
let large : int64 = 9000000000let small : int32 = 42
let large : int64 = 9000000000

For computations requiring arbitrary precision — such as cryptography, number theory, or working with very large numbers — use bignum:

let factorial_100 : bignum = 
  93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000let factorial_100 : bignum = 
  93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000

Floating-point types

Coal provides both single and double precision floating-point types following the IEEE 754 standard. Use float when memory efficiency is important, and double when you need higher precision.

To distinguish between float and double literals, suffix float values with f:

3.0   // double (default for decimal literals)
3.0f  // float (explicitly marked with 'f')3.0   // double (default for decimal literals)
3.0f  // float (explicitly marked with 'f')

let pi_approx  : float = 3.14159f
let pi_precise : double = 3.141592653589793let pi_approx  : float = 3.14159f
let pi_precise : double = 3.141592653589793

Natural numbers

Natural numbers (nat) are covered in detail under Natural numbers. They provide a recursion-friendly representation of non-negative integers, based on the Peano construction.

Numeric literal overloading

Numeric literals in Coal are polymorphic — their type is inferred from context or can be explicitly annotated. When you write a literal like 42, its inferred type is n with (Numeric<n>), meaning it can be any type that implements the Numeric trait.

let a : int32 = 100   // 100 inferred as int32
let b : int64 = 100   // 100 inferred as int64
let c : bignum = 100  // 100 inferred as bignum
let d : double = 100  // 100 inferred as double (converted to 100.0)let a : int32 = 100   // 100 inferred as int32
let b : int64 = 100   // 100 inferred as int64
let c : bignum = 100  // 100 inferred as bignum
let d : double = 100  // 100 inferred as double (converted to 100.0)

This polymorphism extends to arithmetic expressions:

fun add(x, y) = x + y

add(1 : int32, 2 : int32)   // returns int32
add(1.0, 2.0)               // returns double
add(1.0f, 2.0f)             // returns floatfun add(x, y) = x + y

add(1 : int32, 2 : int32)   // returns int32
add(1.0, 2.0)               // returns double
add(1.0f, 2.0f)             // returns float

The compiler resolves the concrete type based on how the value is used, ensuring type safety. This makes numeric literals straightforward to work with.

from_int32(42)from_int32(42)

fun do_stuff(x, y) =
  ...
    let z =
      from_int32(42)
    in
  ...fun do_stuff(x, y) =
  ...
    let z =
      from_int32(42)
    in
  ...

fun do_stuff(num_instance : Numeric<n>, x, y) =
  ...
    let x =
      num_instance.from_int32(42)
    in
  ...fun do_stuff(num_instance : Numeric<n>, x, y) =
  ...
    let x =
      num_instance.from_int32(42)
    in
  ...

Function types

Function types are written in arrow notation, following the same convention as in Haskell. The type a -> b represents a function from a to b. Parentheses can be added to make grouping explicit, such as in (a -> b) -> c. The arrow operator is right-associative, which means that a -> b -> c is the same type as a -> (b -> c).

Natural numbers

Recursion in Coal is closely tied to pattern matching: we peel off layers of a recursively defined data structure step by step, until reaching its base case. This works naturally with lists, trees, and other algebraic data types. Ordinary machine integers (int32, int64), however, cannot be pattern matched on in such a manner. Nevertheless, we often want to use numbers in recursive computations — for example, when repeating an action, or mimicking the behavior of loops in imperative languages. To describe numbers in a way compatible with recursion, we need to borrow some ideas from the standard axiomatization of the natural numbers:

Every natural number is either zero or the successor of another natural number.

This is known as the Peano construction of the natural numbers, named after the Italian mathematician Giuseppe Peano. In code, the Peano numbers are expressed as the built-in type nat:

type nat
  = Zero
  | Succ(nat)type nat
  = Zero
  | Succ(nat)

The number five, for example, can then be expressed as:

Succ(Succ(Succ(Succ(Succ(Zero)))))Succ(Succ(Succ(Succ(Succ(Zero)))))

This representation makes it possible to use numbers directly in patterns, just like with other algebraic data types:

match(n : nat) {
  | Zero    => "yay"
  | Succ(_) => "nay"
}match(n : nat) {
  | Zero    => "yay"
  | Succ(_) => "nay"
}

Writing numbers in this style quickly becomes impractical, however. In order to make it convenient (and efficient) to work with naturals, the compiler internally represents values of type nat as ordinary integers. Converting between the two views is called packing and unpacking. These are constant time (O(1)) operations:

pack   : int32 -> nat
unpack : nat -> int32pack   : int32 -> nat
unpack : nat -> int32

Unit

The unit type has only a single value, written as an empty pair of parentheses: (). At first glance this type may appear to serve no purpose, but it has several practical uses. It is very commonly used to indicate that a function doesn't take any meaningful input:

fun five(() : unit) : int32 = 5fun five(() : unit) : int32 = 5

Two pairs of parentheses for the price of one

Removing the type annotation, the above becomes fun five(()) = 5, which is perfectly valid. But since an expression like five() doesn’t have any other meaningful interpretation, the compiler accepts this as a shorthand for the slightly awkward-looking double parentheses:

fun five() = 5   // i.e., fun five(() : unit) = 5fun five() = 5   // i.e., fun five(() : unit) = 5

Similarly, when calling a function that only takes a unit value as argument, the extra parentheses can be omitted:

let 
  x = 
    five()   // we could have written five(()) here, but less is more
  in
    x + 5let 
  x = 
    five()   // we could have written five(()) here, but less is more
  in
    x + 5

Note that this only works with unit. For non-empty tuples, you still need the extra parentheses:

fun fst4((fst, _, _, _)) = fstfun fst4((fst, _, _, _)) = fst

String

Strings in Coal represent UTF-8 encoded text. String literals are written using double quotes:

"Hello, world!"
"Unicode characters like 🎉 and ✨ are supported""Hello, world!"
"Unicode characters like 🎉 and ✨ are supported"

String concatenation

The +++ operator concatenates two strings:

"Hello, " +++ "world!"  // "Hello, world!""Hello, " +++ "world!"  // "Hello, world!"

Multiple concatenations can be chained naturally:

"first" +++ "second" +++ "third"  // "firstsecondthird""first" +++ "second" +++ "third"  // "firstsecondthird"

Common string operations

The built-in String module provides functions for working with strings. These can be imported using:

import String(length, head, tail, to_list, from_list, ...)import String(length, head, tail, to_list, from_list, ...)

String inspection

length

length : string -> natlength : string -> nat

Returns the number of characters in a string:

length("hello")  // 5length("hello")  // 5

is_empty

is_empty : string -> boolis_empty : string -> bool

Tests whether a string contains no characters:

is_empty("")      // true
is_empty("hello") // falseis_empty("")      // true
is_empty("hello") // false

Head and tail

head

head : string -> Option<char>head : string -> Option<char>

Returns the first character of a string as an Option<char> (this type is explained here) if the string is empty:

head("hello")  // Some('h')
head("")       // Nonehead("hello")  // Some('h')
head("")       // None

tail

tail : string -> stringtail : string -> string

Returns the string without its first character:

tail("hello")  // "ello"
tail("")       // ""tail("hello")  // "ello"
tail("")       // ""

Conversion from and to other types

char_to_string

char_to_string : char -> stringchar_to_string : char -> string

Converts a single character to a one-character string:

char_to_string('A')  // "A"char_to_string('A')  // "A"

to_list

to_list : string -> List<char>to_list : string -> List<char>

Converts a string into a list of its characters:

to_list("hi")  // ['h', 'i']to_list("hi")  // ['h', 'i']

from_list

from_list : List<char> -> stringfrom_list : List<char> -> string

Builds a string from a list of characters:

from_list(['h', 'i'])  // "hi"from_list(['h', 'i'])  // "hi"

String manipulation

reverse

reverse : string -> stringreverse : string -> string

Reverses the order of characters in a string:

reverse("hello")  // "olleh"reverse("hello")  // "olleh"

drop

drop : nat -> string -> stringdrop : nat -> string -> string

Removes the first n characters from a string:

drop(2, "hello")  // "llo"drop(2, "hello")  // "llo"

cons

cons : char -> string -> stringcons : char -> string -> string

Prepends a character to the front of a string:

cons('H', "ello")  // "Hello"cons('H', "ello")  // "Hello"

Working with lists of strings

concat

concat : List<string> -> stringconcat : List<string> -> string

Concatenates a list of strings into a single string:

concat(["Hello", " ", "world", "!"])  // "Hello world!"concat(["Hello", " ", "world", "!"])  // "Hello world!"

intercalate

intercalate : string -> List<string> -> stringintercalate : string -> List<string> -> string

Inserts a separator between strings in a list and concatenates them:

intercalate(", ", ["apple", "banana", "cherry"])  // "apple, banana, cherry"intercalate(", ", ["apple", "banana", "cherry"])  // "apple, banana, cherry"

Type conversions

The String module also provides functions to convert various types to their string representations:

bool_to_string   : bool -> string
int32_to_string  : int32 -> string
float_to_string  : float -> string
double_to_string : double -> stringbool_to_string   : bool -> string
int32_to_string  : int32 -> string
float_to_string  : float -> string
double_to_string : double -> string

For example:

int32_to_string(42)    // "42"
bool_to_string(true)   // "true"
float_to_string(3.14f) // "3.14"int32_to_string(42)    // "42"
bool_to_string(true)   // "true"
float_to_string(3.14f) // "3.14"

List

A list is an ordered collection in which all elements share the same type. Lists are one of the most fundamental data structures in functional programming. They are commonly used to store and manipulate collections of data, and serve as a building block for many higher-level abstractions.

In Coal, list literals are written as a sequence of comma-separated expressions enclosed in square brackets:

[%expr_1, %expr_2, ..., %expr_n] 

[%expr_1 : %t, %expr_2 : %t, ..., %expr_n : %t] : List<%t>

For example:

[1, 1, 2, 5, 14, 42, 132, 429] : List<int32>[1, 1, 2, 5, 14, 42, 132, 429] : List<int32>

Lists are defined inductively and implemented internally as singly linked lists. This means that a list of type List<a> is either:

1. the empty list []; or
2. a value of type a (the head) followed by another list of type List<a> (the tail).

In pseudo-code:

type List<a>
  = []
  | a :: List<a>type List<a>
  = []
  | a :: List<a>

Here :: denotes the cons-operator, which constructs a new list by prepending an element to an existing list.

Lists are deconstructed using pattern matching. For example, the following function removes the first element from a list if it happens to be a zero:

fun remove_head_if_zero(list) = 
  match(list) {
    | [] => []
    | head :: tail =>
        if (head == 0)
          then tail     // remove the first element, if it is zero
          else list     // otherwise return the original list
  }fun remove_head_if_zero(list) = 
  match(list) {
    | [] => []
    | head :: tail =>
        if (head == 0)
          then tail     // remove the first element, if it is zero
          else list     // otherwise return the original list
  }

This style of unpacking data is common with all algebraic data types (see Pattern matching).

You can also match lists using literal patterns. The following example matches a list of exactly three elements and checks if they form a Pythagorean triple:

fun is_pythagorean(numbers) =
  match(numbers) {
    | [a, b, c] =>
        a^2 + b^2 == c^2 || 
        a^2 + c^2 == b^2 || 
        b^2 + c^2 == a^2
    | _ =>
        false
  }fun is_pythagorean(numbers) =
  match(numbers) {
    | [a, b, c] =>
        a^2 + b^2 == c^2 || 
        a^2 + c^2 == b^2 || 
        b^2 + c^2 == a^2
    | _ =>
        false
  }

Common list operations

import List(length, head, tail, uncons)import List(length, head, tail, uncons)

The function length returns the number of elements in a list:

length([0, 1, 2, 3, 4])   // returns 5length([0, 1, 2, 3, 4])   // returns 5

Its type is:

length : List<a> -> natlength : List<a> -> nat

Since lists are laid out in memory as linked nodes connected by pointers, the time complexity of many list operations, including length, is O(n).

Head, tail, and uncons

• head returns the first element of a list, wrapped in an Option (described below) to account for the empty list.
• tail returns all elements except the first, also as an Option.
• uncons combines the two: it returns both the head and tail as a tuple, or None if the list is empty. In a sense, it undoes what the cons (::) constructor does.

These functions take constant (O(1)) time.

head : List<a> -> Option<a>
tail : List<a> -> Option<List<a>>
uncons : List<a> -> Option<(a, List<a>)>head : List<a> -> Option<a>
tail : List<a> -> Option<List<a>>
uncons : List<a> -> Option<(a, List<a>)>

xs |.map(f)xs |.map(f)

Take, drop and slice

Use take to get another list with the first n elements from a given list:

take : nat -> List<a> -> List<a>take : nat -> List<a> -> List<a>

For example:

[1, 2, 3, 4, 5, 6, 7] |.take(3)     // [1, 2, 3][1, 2, 3, 4, 5, 6, 7] |.take(3)     // [1, 2, 3]

Note that, if the list’s length is less than the requested number of elements, then take returns the entire list. So, for example, take(5, [1, 2, 3]) returns [1, 2, 3]. As expected, take(0) always returns an empty list.

The function drop removes the first n elements from a list.

drop : nat -> List<a> -> List<a>drop : nat -> List<a> -> List<a>

For example:

[1, 2, 3, 4, 5, 6, 7] |.drop(3)     // [4, 5, 6, 7][1, 2, 3, 4, 5, 6, 7] |.drop(3)     // [4, 5, 6, 7]

If you attempt to drop a greater number of elements than what the list contains, drop returns an empty list.

Combining drop and take allows you to obtain a range of elements from within a list:

[1, 2, 3, 4, 5, 6, 7] 
  |.drop(2)
  |.take(3)

// == [3, 4, 5][1, 2, 3, 4, 5, 6, 7] 
  |.drop(2)
  |.take(3)

// == [3, 4, 5]

The function slice does exactly this, in a way that allows you to specify the range of elements to extract from the input list:

slice : nat -> nat -> List<a> -> List<a>slice : nat -> nat -> List<a> -> List<a>

[1, 2, 3, 4, 5, 6, 7] |.slice(2, 5)
// == [1, 2, 3, 4, 5, 6, 7] |.drop(2) |.take(5 - 2)
// == [3, 4, 5][1, 2, 3, 4, 5, 6, 7] |.slice(2, 5)
// == [1, 2, 3, 4, 5, 6, 7] |.drop(2) |.take(5 - 2)
// == [3, 4, 5]

List concatenation

The list concatenation operator (++) appends one list to the end of another, resulting in a new list.

let s = ["Khufu", "Hatshepsut", "Akhenaten"] ++ ["Tutankhamun"]let s = ["Khufu", "Hatshepsut", "Akhenaten"] ++ ["Tutankhamun"]

Note: The time complecity of ++ is linear (O(n)) in the length of the first list.

Useful higher-order list functions

These are functions that take some other function as input and modify the list in some way based on the behavior of the given function.

Mapping over a list

The function map applies a function to each element of a list.

For example:

[0, 1, 2, 3, 4] |.map(fn(x) => 2 ^ x)       // [1, 2, 4, 8, 16][0, 1, 2, 3, 4] |.map(fn(x) => 2 ^ x)       // [1, 2, 4, 8, 16]

The type of map is:

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

map : (a -> b) -> f<a> -> f<b> with (Functor<f>)map : (a -> b) -> f<a> -> f<b> with (Functor<f>)

a           ==>  f<a>                         // The functor transforms objects
z : a -> b  ==>  map(z) : f<a> -> f<b>        // and functions

map(id) == idmap(id) == id

map(f << g) == map(f) << map(g)     // The operator `<<` denotes function composition, so `f << g = f(g(x)))`.map(f << g) == map(f) << map(g)     // The operator `<<` denotes function composition, so `f << g = f(g(x)))`.

Filtering a list

Filtering is a technique for removing all elements of a list, except those that meet a given condition.

For example:

[0, 1, 2, 3, 4] |.filter(fn(x) => x > 2)    // [3, 4] [0, 1, 2, 3, 4] |.filter(fn(x) => x > 2)    // [3, 4] 

The type of filter is:

filter : (a -> bool) -> List<a> -> List<a>filter : (a -> bool) -> List<a> -> List<a>

That is, filter takes a predicate and a list as input, and returns a new list with only the elements that return true for the predicate.

Reducing a list

The higher-order function reduce takes a list and combines its elements into a single result. A common example is reducing a list of numbers to a single value by repeatedly applying an operation, such as summing each element with a running total:

let sum = reduce(fn(n, a) => n + a, 0, [1, 2, 3])let sum = reduce(fn(n, a) => n + a, 0, [1, 2, 3])

The operation described here is also commonly referred to as a fold. That name is not used, however, since it is a reserved language keyword in Coal. Along with the special @-pattern syntax, it provides the foundation for implementing recursive functions, including reduce. This is explained in detail in Recursion and corecursion.

The type of reduce is:

reduce : (e -> a -> a) -> a -> List<e> -> areduce : (e -> a -> a) -> a -> List<e> -> a

• The first argument is a function that combines an element of type e with an accumulator of type a to produce a new accumulator.
• The second argument is the initial value of the accumulator.
• The third argument is the list to reduce.

Examples of using reduce

Concatenating strings:

let words = ["Hello", " ", "world", "!"]
let sentence = reduce(fn(w, a) => w +++ a, "", words)
// sentence = "Hello world!"let words = ["Hello", " ", "world", "!"]
let sentence = reduce(fn(w, a) => w +++ a, "", words)
// sentence = "Hello world!"

Finding the maximum element:

let max_val = reduce(fn(n, a) => if n > a then n else a, 0, [3, 7, 2, 9])
// max_val = 9let max_val = reduce(fn(n, a) => if n > a then n else a, 0, [3, 7, 2, 9])
// max_val = 9

Counting elements satisfying a condition:

let numbers = [1, 2, 3, 4, 5]
let number_of_evens = reduce(fn(n, a) => if n % 2 == 0 then a + 1 else a, 0, numbers)
// number_of_evens = 2let numbers = [1, 2, 3, 4, 5]
let number_of_evens = reduce(fn(n, a) => if n % 2 == 0 then a + 1 else a, 0, numbers)
// number_of_evens = 2

reduce(f, 0, [1, 2, 3, 4, 5])reduce(f, 0, [1, 2, 3, 4, 5])

f(1, f(2, f(3, f(4, f(5, 0))))f(1, f(2, f(3, f(4, f(5, 0))))

reduce_left(f, 0, [1, 2, 3, 4, 5])reduce_left(f, 0, [1, 2, 3, 4, 5])

f(f(f(f(f(0, 1), 2), 3), 4), 5)f(f(f(f(f(0, 1), 2), 3), 4), 5)

reduce(fn(x, acc) => x - acc, 0, [1, 2, 3])      // 1 - (2 - (3 - 0)) = 1 - 2 - 3 = -4
reduce_left(fn(acc, x) => acc - x, 0, [1, 2, 3]) // ((0 - 1) - 2) - 3 = -6reduce(fn(x, acc) => x - acc, 0, [1, 2, 3])      // 1 - (2 - (3 - 0)) = 1 - 2 - 3 = -4
reduce_left(fn(acc, x) => acc - x, 0, [1, 2, 3]) // ((0 - 1) - 2) - 3 = -6

List predicates

A predicate is a function that tests for some condition with respect to its argument and returns true or false. By convention, functions that serve this purpose are often prefixed with is_. The below predicates are available in the standard List package:

is_empty     : List<a> -> bool
is_nonempty  : List<a> -> bool
is_singleton : List<a> -> boolis_empty     : List<a> -> bool
is_nonempty  : List<a> -> bool
is_singleton : List<a> -> bool

is_empty

A common operation on lists is to check if a list is empty or not. This is what the function is_empty does.

is_empty([])                                   // true
is_empty(["wheat", "oats", "rye", "barley"])   // falseis_empty([])                                   // true
is_empty(["wheat", "oats", "rye", "barley"])   // false

is_nonempty

This function is the opposite of is_empty. That is:

is_nonempty(xs) <==> ! is_empty(xs)

is_singleton

This function returns true when the input list has precisely one element.

is_singleton(["oats"])                             // true  
is_singleton([])                                   // false
is_singleton(["wheat", "oats", "rye", "barley"])   // falseis_singleton(["oats"])                             // true  
is_singleton([])                                   // false
is_singleton(["wheat", "oats", "rye", "barley"])   // false

Option

The Option type is a built-in algebraic data type that represents optional values — values that may or may not be present. This type is called Maybe in Haskell and is similar to Option in languages like Rust or Scala.

type Option<a>
  = Some(a)
  | Nonetype Option<a>
  = Some(a)
  | None

Since match statements in Coal need to be exhaustive, Option is useful to express the fact that a value cannot be produced in certain cases. For example, let’s say that we are trying to define a function head, returning the first element of a list:

fun head(list : List<a>) : a =
  match(list) {
    | head :: _ => head
    | [] => // 💥 What should I return here?
  }fun head(list : List<a>) : a =
  match(list) {
    | head :: _ => head
    | [] => // 💥 What should I return here?
  }

The type of this function would be:

head : List<a> -> ahead : List<a> -> a

We can read this type as: Given any type a and a list of elements of this type, return an a value. That is to say; we know nothing about a, except that the list’s elements has this type. Therefore, if the input list is empty, then we have nothing to look at. Option solves this problem. The head function provided by the standard List package is defined in the following way:

fun head(list : List<a>) : Option<a> =
  match(list) {
    | head :: _ => Some(head)
    | [] => None
  }fun head(list : List<a>) : Option<a> =
  match(list) {
    | head :: _ => Some(head)
    | [] => None
  }

Result

The Result type represents computations that may either succeed or fail. It is similar to Either in Haskell:

type Result<r, e>
  = Ok(r)
  | Err(e)type Result<r, e>
  = Ok(r)
  | Err(e)

A value of type Result<r, e> is one of:

• Ok(r), indicating a successful outcome carrying a result value of type r, or
• Err(e), indicating a failure carrying an error value of type e.

Example

This example shows how Result is used in the return type of read_file from the IO-package to handle errors when reading a file from the file system.

module Main {

  import IO(println_string, read_file, FileIOError)
  import Coal.Monad(and_then)

  fun show_error(error : FileIOError) =
    match(error) {
      | FileNotFound => 
          println_string("File not found")
      | _ => 
          println_string("Unspecified error")
    }

  fun main() =
    read_file("does_not_exist.txt")
      |. and_then(fn(result) =>
           match(result) {
             | Ok(file) => println_string(file)
             | Err(err) => show_error(err)
           })

}module Main {

  import IO(println_string, read_file, FileIOError)
  import Coal.Monad(and_then)

  fun show_error(error : FileIOError) =
    match(error) {
      | FileNotFound => 
          println_string("File not found")
      | _ => 
          println_string("Unspecified error")
    }

  fun main() =
    read_file("does_not_exist.txt")
      |. and_then(fn(result) =>
           match(result) {
             | Ok(file) => println_string(file)
             | Err(err) => show_error(err)
           })

}

The type of read_file is:

read_file : string -> IO<Result<string, FileIOError>>read_file : string -> IO<Result<string, FileIOError>>

Tuples

Just like lists, tuples are ordered sequences of values. Unlike lists, however, a tuple’s length is fixed (i.e. determined at compile-time), and its elements can have different types. In code, a tuple is written as a comma-separated sequence of expressions enclosed in parentheses:

  (%expr_1, %expr_2, ..., %expr_n) 

  ( %expr_1 : %type_1
  , %expr_2 : %type_2
  , ...
  , %expr_n : %type_n
  ) : 
  ( %type_1
  , %type_2
  , ...
  , %type_n
  )

For example:

(10, "covfefe", false)  // The type of this tuple is: (int32, string, bool)(10, "covfefe", false)  // The type of this tuple is: (int32, string, bool)

Tuples of length two and three are often called pairs and triples, respectively. There is no singleton tuple type — a single value in parentheses is just the value itself:

(42)  // Not a tuple -- just the integer 42(42)  // Not a tuple -- just the integer 42

The empty tuple does exist, and has special meaning. It is written () and is known as the unit value. The type of () is unit. (See Built-in language primitives for more on this type.)

()            : unit                           // unit value
(1, 2)        : (int32, int32)                 // 2-tuple
(1, 2, 3)     : (int32, int32, int32)          // 3-tuple
(1, 2, 3, 4)  : (int32, int32, int32, int32)   // 4-tuple
// ...()            : unit                           // unit value
(1, 2)        : (int32, int32)                 // 2-tuple
(1, 2, 3)     : (int32, int32, int32)          // 3-tuple
(1, 2, 3, 4)  : (int32, int32, int32, int32)   // 4-tuple
// ...

As with other data types, tuples can be deconstructed through pattern matching:

fun fst3((fst, _, _) : (a, b, c)) : a = fst
fun snd3((_, snd, _) : (a, b, c)) : b = snd
fun thd3((_, _, thd) : (a, b, c)) : c = thd fun fst3((fst, _, _) : (a, b, c)) : a = fst
fun snd3((_, snd, _) : (a, b, c)) : b = snd
fun thd3((_, _, thd) : (a, b, c)) : c = thd 

Tuples and currying

To specify a tuple as the only argument to a function, you need to use an extra pair of parentheses:

fun add((a, b)) = a + b

let five = add((1, 4))fun add((a, b)) = a + b

let five = add((1, 4))

The curry and uncurry combinators convert an uncurried function into a curried one, and vice versa.

curry   : ((a, b) -> c) -> a -> b -> c
uncurry : (a -> b -> c) -> (a, b) -> ccurry   : ((a, b) -> c) -> a -> b -> c
uncurry : (a -> b -> c) -> (a, b) -> c

To import these, add the following import statement:

import Coal.Combinators(curry, uncurry)import Coal.Combinators(curry, uncurry)

Here is how curry is used with the uncurried version of add, to change it into curried form.

let five = curry(add, 1, 4)         // or (curry(add))(1, 4)let five = curry(add, 1, 4)         // or (curry(add))(1, 4)

Records

Records are unordered collections of name–value pairs, where the values can be of any type, including other records. In Coal, records are first-class values. They are suitable for representing structured data with multiple properties, or nested objects. A record expression is written as a sequence of comma-separated fields enclosed in curly braces. Each field consists of a name, called the label, paired with a value. The two are separated by an equals sign (=):

{ 
  name = "Robert Sixkiller", 
  shoe_size = 43.0f, 
  privileges = ["read", "edit", "karaoke"]
}{ 
  name = "Robert Sixkiller", 
  shoe_size = 43.0f, 
  privileges = ["read", "edit", "karaoke"]
}

The corresponding type for the above record is:

{ name : string, shoe_size : float, privileges : List<string> }{ name : string, shoe_size : float, privileges : List<string> }

The type of a record resembles the expression itself, except that each field is written as a label followed by its type. Instead of an equals sign, a colon (:) separates the label and the type.

Since the order of fields is irrelevant, the following two records are considered identical:

{ x = 1, y = 2 }
{ y = 2, x = 1 }{ x = 1, y = 2 }
{ y = 2, x = 1 }

The naming rules for labels are the same as for variables: labels must consist of alphanumeric characters or underscores (_), and the first character cannot be a digit.

Field access

The contents of a record field can be obtained using the field-access operator, which is simply a dot (.) followed by the field’s label:

let language = { name = "Java", paradigm = "OOP" }
  in language.namelet language = { name = "Java", paradigm = "OOP" }
  in language.name

Extending records

Records in Coal are extensible, meaning that new fields can be added to a record at run time. For example:

fun tagged(rec, t : string) = { tag = t | rec }  fun tagged(rec, t : string) = { tag = t | rec }  

This function accepts two arguments: an existing record rec and a string t. It returns a copy of rec augmented with a new field tag which assumes the value of t. The pipe symbol (|) is an infix operator that takes the record on the right-hand side and extends it with the fields on the left.

For example, if we define a record r = { day = "monday", humidity = 73.5 } and apply tagged(r, "wet"), we obtain a new record:

{ day = "monday", humidity = 73.5, tag = "wet" }{ day = "monday", humidity = 73.5, tag = "wet" }

What makes this especially useful is that the type of the original record does not matter; its labels and field types need not be known at compile time.

The left-hand side of the pipe is itself a list of fields, so any number of fields can be added at once:

{ a = 1, b = 2 | { c = 3 } } 
  == { a = 1 | { b = 2 | { c = 3 } } } 
  == { a = 1 | { b = 2, c = 3 } }
  => { a = 1, b = 2, c = 3 }  { a = 1, b = 2 | { c = 3 } } 
  == { a = 1 | { b = 2 | { c = 3 } } } 
  == { a = 1 | { b = 2, c = 3 } }
  => { a = 1, b = 2, c = 3 }  

Open and closed records

Here is the function signature for tagged again, this time with added type annotations:

tagged(rec : { | r }, t : string) : { tag : string | r } = 
  { tag = t | rec }tagged(rec : { | r }, t : string) : { tag : string | r } = 
  { tag = t | rec }

These types look a bit different from earlier examples. Here, the pipe (|) also appears at the type level. It serves a similar purpose: combining fields with an existing record type. The type variable r represents a row, which can be thought of as a type-level list of fields. A record type of this form is called open. By contrast, a closed record type explicitly lists all its fields. The following example illustrates the difference. Suppose we want to represent GPS coordinates with two fields, lat and lng:

fn(p : { lat : float, lng : float }) => p.latfn(p : { lat : float, lng : float }) => p.lat

In this example, the function requires its argument p (a record) to have exactly two fields: lat and lng, both of type float. This type is closed.

fn(p : { lat : float, lng : float | q }) => p.latfn(p : { lat : float, lng : float | q }) => p.lat

This function, on the other hand, is polymorphic in the row variable q. It accepts any record that includes lat and lng (both floats), regardless of any additional fields. For instance, all of the following are valid:

• { lat = -3.067425, lng = 37.355625, alt = 5895 } ,
• { location = "Great Pyramid", time = "2024-09-15T10:57:19Z", lat = 29.9792, lng = 31.1342 }, and
• { lat = 0.0, lng = 1.0 },

This type is open. The general format of an open record type is

{ %label_1 : %type_1, %label_2 : %type_2, ..., %label_n : %type_n | %r },

for some n ≥ 0.

The variable %r on the right-hand side of the pipe represents a row variable that captures all remaining fields of the record — those not explicitly listed on the left-hand side. Unlike the field patterns on the left, %r is a simple variable name, not a pattern. It serves as a placeholder for "whatever other fields this record might have," making the type polymorphic over those additional fields.

Recall the earlier tagged example and the type of the argument rec in that function:

rec : { | r }rec : { | r }

In this type, the variable r captures all fields of the input record, so n is zero. This explains the somewhat unusual-looking type { | r }.

Pattern matching over records

As with other data types, it is possible to pattern match on records. In this context, the right-hand side of a field acts as the binding pattern used to match the sub-expression. The simplest case is to bind a field directly to a variable:

fun full_name({ first_name = fn, last_name = ln }) = fn +++ " " +++ ln fun full_name({ first_name = fn, last_name = ln }) = fn +++ " " +++ ln 

Shorthand syntax

When the variable name you want to bind to is the same as the field label, you can use a shorthand notation to omit the explicit binding. Instead of writing { field = field }, you can simply write { field }. This is purely syntactic sugar and behaves in the exact same way.

fun full_name({ first_name, last_name }) = first_name +++ " " +++ last_name fun full_name({ first_name, last_name }) = first_name +++ " " +++ last_name 

Deconstructing records

The pipe (|) operator allows you to deconstruct records by matching against a subset of their fields:

fun get_name({ name = n | _ }) = nfun get_name({ name = n | _ }) = n

The right-hand side pattern must be either a variable or a wildcard (_). If you use a variable here, it will capture the remainder of the record (all fields not explicitly matched). A common use case is to remove one or more fields from a record. For example:

fun drop_name({ name = _ | fields } : { name : string | q }) : { | q } = fieldsfun drop_name({ name = _ | fields } : { name : string | q }) : { | q } = fields

Here, the name field is removed and a record with all remaining fields are returned.

Keep in mind that if you only need to retrieve a single field, the dot syntax (record.field) is simpler and more concise. Pattern matching really becomes necessary when you want to extract multiple fields at once, remove fields, or work with the remainder of a record.

Updating a field

By combining field extension with pattern matching, you can replace an existing field in a record. For instance, here is a function that updates the tag field:

fun set_tag({ tag = _ | fields }, new_tag : string) =
  { tag = new_tag | fields }    fun set_tag({ tag = _ | fields }, new_tag : string) =
  { tag = new_tag | fields }    

This proceeds in two steps: first remove the old field using pattern matching, then reinsert it with the new value. With type annotations:

fun set_tag(
  { tag = _ | fields } : { tag : string | r }, 
  new_tag : string
) : { tag : string | r } = 
  { tag = new_tag | fields }fun set_tag(
  { tag = _ | fields } : { tag : string | r }, 
  new_tag : string
) : { tag : string | r } = 
  { tag = new_tag | fields }

This function requires not only that the tag field is present, but also that it has the expected type. For example, { tag = false } would be rejected, since tag is required to have type string.

Modules

Projects in Coal are organized as collections of modules. Modules make it possible to group related functionality into distinct namespaces. A module contains functions, type definitions and other language constructs, typically focused on a specific purpose within a library or application.

module %path(%export_list) {
  %import_statement
  %import_statement
  ...
  %definition
  %definition
  ...
}

A definition can be a function, let-binding, data type definition, type alias, trait, or trait instance. Traits and trait instances are introduced here. The rest of these are explained in more detail under Top-level definitions.

Every module is uniquely identified by its path.

• The path mirrors the directory structure of the source file in which the module is located.
• Path segments begin with an uppercase letter and are separated by a dot (.).
• Files have a .coal extension.

A module Utils.Math.Trigonometry, for instance, is defined in a file named Trigonometry.coal, located under Utils/Math/ relative to your project’s root directory:

src
└── Utils
    └── Math
        └── Trigonometry.coal

Top-level definitions

Definitions that occupy the outermost scope of a module are functions, top-level let-expressions, data type definitions, traits, trait instances, and folds.

Functions

A function is defined with the fun keyword, followed by the function’s name and a list of comma-separated arguments enclosed in parentheses. The function body is simply an expression, which comes after the arguments and is preceded by an equals sign:

  fun %name(%arg_1, %arg_2, ..., %arg_n) = %expr

A type annotion can be given to indicate a function’s return type, as in the following example:

fun is_even(n : int32) : bool =
  n % 2 == 0fun is_even(n : int32) : bool =
  n % 2 == 0

Function parameters are patterns, allowing functions to directly deconstruct their arguments. In addition to basic variables, records, tuples, and other data constructors, patterns can also include wildcards, literals, and nested structures.

fun grok({ n : int32 }, (fst, snd), _) =
  ...fun grok({ n : int32 }, (fst, snd), _) =
  ...

Top-level functions can also be defined in the form of a list of pattern-expression pairs, separated by a |-symbol. For example:

fun unpack
  | [a], true    => a
  | [a, _], true => a
  | [a, _, _], _ => a
  | _, _         => 0fun unpack
  | [a], true    => a
  | [a, _], true => a
  | [a, _, _], _ => a
  | _, _         => 0

This style of top-level function is equivalent to defining the function with an explicit match expression inside its body:

fun unpack(a1, a2) =
  match((a1, a2)) {
    | ([a], true)    => a
    | ([a, _], true) => a
    | ([a, _, _], _) => a
    | (_, _)         => 0
  }fun unpack(a1, a2) =
  match((a1, a2)) {
    | ([a], true)    => a
    | ([a, _], true) => a
    | ([a, _, _], _) => a
    | (_, _)         => 0
  }

Here is another example from the Option module:

fun with_default
  | _, Some(value) => value
  | value, _       => valuefun with_default
  | _, Some(value) => value
  | value, _       => value

This function is used to extract a value of type a from an Option<a> by providing a default value for the case when the input is None. For example:

let name = Option.with_default("Anonymous", user.name)let name = Option.with_default("Anonymous", user.name)

or

let name = user.name |. with_default("Anonymous")let name = user.name |. with_default("Anonymous")

See Pattern matching for a more detailed discussion of patterns and the match syntax.

Main

Just like in many other programming languages, the main function serves as the entry point of a program:

module Main {

  fun main() =
    ...module Main {

  fun main() =
    ...

The type of main is unit -> IO<unit>. See IO for an explanation of the IO type.

Let-expressions

The let keyword introduces a new name bound to the result of an expression. Inside functions, a let is often used to give names to intermediate values:

fun hypotenuse(a, b) =
  let sqr_a = a * a;
      sqr_b = b * b
  in 
    sqrt(sqr_a + sqr_b)fun hypotenuse(a, b) =
  let sqr_a = a * a;
      sqr_b = b * b
  in 
    sqrt(sqr_a + sqr_b)

Here, sqr_a and sqr_b are local bindings, only visible in the body that follows the in.

At the top level of a module, a let works in the same way, except there is no enclosing body — the binding simply introduces a global name that can be referenced elsewhere in the module (or from other modules):

let days = 
  [ "Monday"
  , "Tuesday"
  , "Wednesday"
  , "Thursday"
  , "Friday"
  , "Saturday"
  , "Sunday" 
  ]let days = 
  [ "Monday"
  , "Tuesday"
  , "Wednesday"
  , "Thursday"
  , "Friday"
  , "Saturday"
  , "Sunday" 
  ]

Type annotations for let-bindings look similar to those for functions:

let days : List<string> =
  [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ]let days : List<string> =
  [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ]

Since a let can hold any expression, top-level functions can also be defined this way:

let add = fn(x, y) => x + y
// Equivalent to:
// fun add(x, y) = x + ylet add = fn(x, y) => x + y
// Equivalent to:
// fun add(x, y) = x + y

Note that, unlike at the expression level, it isn't possible to bind to a pattern in a top-level let-binding.

  let (a, b) = (1, 3)  // This only works inside expressions  let (a, b) = (1, 3)  // This only works inside expressions

Data types

User-defined data types in Coal are introduced using the type keyword. They are of the product-sum variety.

A product type combines multiple fields into one single value: All of the components appear together in the constructed data. An RGB color triplet that contains individual red, green, and blue values can be described with a type:

type Color = Rgb(int8, int8, int8)type Color = Rgb(int8, int8, int8)

A sum type is a choice between alternatives: A value belongs to exactly one of the specified variants. A type that represents a shape that can be either a Circle or a Rectangle can be defined as:

type Shape = Circle | Rectangletype Shape = Circle | Rectangle

More complex types can be built by combining product and sum constructors. The following is a type that defines a binary tree, parameterized by the type (a) of its nodes:

type Tree<a> 
  = Leaf
  | Node(a, Tree<a>, Tree<a>)type Tree<a> 
  = Leaf
  | Node(a, Tree<a>, Tree<a>)

This definition says that a Tree<a> is either:

• a Leaf (the empty tree), or
• a Node containing a value of type a along with two sub-trees (the left and right branches).

Using this type, we can represent any finite binary tree. For example, here is a tree of integers:

//          (4)
//          / \
//       ---------
//       /       \
//     (2)       (6)
//    -----     -----
//    /   \     /   \ 
//  (1)   (3) (5)   (7)  

let tree_of_gondor = 
  Node 
    ( 4
    , Node
        ( 2
        , Node(1, Leaf, Leaf)
        , Node(3, Leaf, Leaf)
        )
    , Node
        ( 6
        , Node(5, Leaf, Leaf)
        , Node(7, Leaf, Leaf)
        )
    )//          (4)
//          / \
//       ---------
//       /       \
//     (2)       (6)
//    -----     -----
//    /   \     /   \ 
//  (1)   (3) (5)   (7)  

let tree_of_gondor = 
  Node 
    ( 4
    , Node
        ( 2
        , Node(1, Leaf, Leaf)
        , Node(3, Leaf, Leaf)
        )
    , Node
        ( 6
        , Node(5, Leaf, Leaf)
        , Node(7, Leaf, Leaf)
        )
    )

The structure of the tree is entirely determined by its constructors (Leaf and Node), which makes recursion natural.

Algebraic data types are especially useful for describing language grammars and other hierarchical structures. Consider this JSON representation:

type JsonValue
  = Null
  | Bool(bool)
  | Number(double)
  | String(string)
  | Array(List<JsonValue>)
  | Object(List<(string, JsonValue)>)type JsonValue
  = Null
  | Bool(bool)
  | Number(double)
  | String(string)
  | Array(List<JsonValue>)
  | Object(List<(string, JsonValue)>)

Type aliases

A type alias assigns a name to an existing type, making complex definitions easier to express and reuse. It can refer to primitive types, records, function types, or algebraic data types.

  type alias %Name<%param_1, ..., %param_n> = %type

For example:

type alias User = { username : string, email : string, permissions: List<Permission> }type alias User = { username : string, email : string, permissions: List<Permission> }

An alias can include type parameters. For example, given a type Map<key, val>, we can define:

type alias Dictionary<val> = Map<string, val>type alias Dictionary<val> = Map<string, val>

Imports

An import statement is used to bring in functions and other definitions from a module in your project. These statements must appear at the beginning of the module, before any definitions. The following line makes some functions from the List module available to the current module:

import List(concat, head, tail)import List(concat, head, tail)

Note that only definitions that are exported by the source module can be imported. See Exports.

Type imports

Importing a type follows the same pattern. After the name of the type is an optional list of data constructors enclosed in parentheses. For example, let’s say our project includes a module Utilities, and that this module defines the following type:

type Answer = Yes | Notype Answer = Yes | No

To import this type and its constructors, we use the following statement:

import Utilities(Answer(Yes, No))import Utilities(Answer(Yes, No))

If the list of constructors is omitted, all public data constructors of the type are imported:

import Utilities(Answer)   // Brings in Answer and its constructorsimport Utilities(Answer)   // Brings in Answer and its constructors

Trait imports

Traits are imported in the same way.

import Utilities(Countable)import Utilities(Countable)

Alternatively, you can import the individual methods of a trait directly. For example, if Countable is defined as:

trait Countable<a> {
  count :: a -> nat
}trait Countable<a> {
  count :: a -> nat
}

Then count can be imported like any regular function:

import Utilities(count)import Utilities(count)

Qualified imports

The special namespace keyword allows you to import and access all functions, types, and other definitions from a module via their qualified names. A qualified name is formed by prefixing the name with the path of the module followed by a dot (.):

// Import the List module under its namespace
import namespace List

  // And use it like this:
  let zs = List.concat(xs, ys)// Import the List module under its namespace
import namespace List

  // And use it like this:
  let zs = List.concat(xs, ys)

Exports

In a module declaration, the path identifier is followed by an optional list of exported names enclosed in parentheses. Only exported names are visible outside the module (or public in OOP terminology).

module Utils.Math.Trigonometry(sin, cos, tan) {
  // ...module Utils.Math.Trigonometry(sin, cos, tan) {
  // ...

If this list is left out, everything in the module is exported.

Pattern matching

The match expression in Coal is used to deconstruct data based on its shape, effectively reversing what the data constructors of algebraic data types do. Pattern matching allows you to branch on the structure of a value and directly bind its components to variables. For example:

type Shape = Rectangle(float, float) | Circle(float)

fun area(shape) : float =
  match(shape) {
    | Rectangle(w, h) => w * h
    | Circle(r)       => pi * r^2
  }type Shape = Rectangle(float, float) | Circle(float)

fun area(shape) : float =
  match(shape) {
    | Rectangle(w, h) => w * h
    | Circle(r)       => pi * r^2
  }

A case in a match expression is called a clause and consists of a pattern on the left and an expression on the right. Pattern matching proceeds by checking each clause in order until it finds one whose pattern matches the value. The corresponding right-hand side expression is then evaluated, with any variables in the pattern bound to the matched sub-components.

match(list : List<int32>) {
  | [a]       => a
  | [a, _]    => a
  | [a, _, _] => a
  | _         => 0
}match(list : List<int32>) {
  | [a]       => a
  | [a, _]    => a
  | [a, _, _] => a
  | _         => 0
}

Variables introduced by a pattern are only in scope in the corresponding right-hand side expression:

match(opt) {
  | Some(x) => x + 1  // x is bound here
  | None    => 0      // x is not in scope here
}match(opt) {
  | Some(x) => x + 1  // x is bound here
  | None    => 0      // x is not in scope here
}

Patterns can take several forms, including data constructors, literals, tuples, records, variables, wildcards, or combinations of these:

match(shape) {
  | Rectangle(0.0, _) => "flat rectangle"
  | Rectangle(w, h)   => "rectangle with width " +++ show(w)
}match(shape) {
  | Rectangle(0.0, _) => "flat rectangle"
  | Rectangle(w, h)   => "rectangle with width " +++ show(w)
}

See below for a complete list of available patterns.

Totality requirement

For a function to be total, it must be defined for all inputs of its corresponding type. In Coal, functions are always total. A consequence of this in the context of match expressions is that all possible cases for a type need to be covered by the patterns. In other words, the patterns must be exhaustive. If a case is missing, the compiler will reject the program.

For example, the following function

fun head(input) =
  match(input) {
    | x :: xs => x
  }fun head(input) =
  match(input) {
    | x :: xs => x
  }

will produce an error:

4:5:
  |
  |     match(input) {
  |     ^^^^^^^^^^^^^^
  |       | x :: xs => x
  | ^^^^^^^^^^^^^^^^^^^^
  |     }

Non-exhaustive patterns

Wildcard patterns

A wildcard pattern is a pattern that matches any value without binding it to a name and is written as an underscore (_). These are often useful to guarantee exhaustiveness in match expressions. For instance, we can use literal patterns along with a wildcard when matching on integers:

fun describe_int(n : int32) : string =
  match(n) {
    | 0 => "zero"
    | 1 => "one"
    | _ => "something else"
  }fun describe_int(n : int32) : string =
  match(n) {
    | 0 => "zero"
    | 1 => "one"
    | _ => "something else"
  }

Guards

Guards add conditional logic to patterns, allowing you to refine a match based on boolean conditions. Instead of using nested if-then-else expressions within a match clause, guards provide a cleaner syntax with the when and otherwise keywords.

The first example below shows the traditional approach using if-then-else:

match(parse_int32(s)) {
  | Some(n) =>
      if (n == rand) 
        then println_string("You guessed right!")
      else if (n > rand)
        then println_string("Too large!")
      else
        println_string("Too small!")
  | None =>
      println_string("Not a number")
}match(parse_int32(s)) {
  | Some(n) =>
      if (n == rand) 
        then println_string("You guessed right!")
      else if (n > rand)
        then println_string("Too large!")
      else
        println_string("Too small!")
  | None =>
      println_string("Not a number")
}

With guards, the same logic becomes more declarative:

match(parse_int32(s)) {
  | Some(n) 
      when (n == rand) => 
        println_string("You guessed right!")
      when (n > rand) => 
        println_string("Too large!")
      otherwise => 
        println_string("Too small!")
  | _ =>
      println_string("Not a number")
}match(parse_int32(s)) {
  | Some(n) 
      when (n == rand) => 
        println_string("You guessed right!")
      when (n > rand) => 
        println_string("Too large!")
      otherwise => 
        println_string("Too small!")
  | _ =>
      println_string("Not a number")
}