Skip to content

Types

Gale builds richer types from fixed-length tuples, aliases, literal unions, and recursive algebraic data types. Generic parameters use angle brackets. Exhaustive case covers every finite shape.

Tuples group values, aliases name existing types, and literal unions describe finite choices. Algebraic data types define named alternatives and recursive structures.

An alias gives a name to an existing type. This one names a generic tuple:

mod types
pub type Pair<A, B> = {A, B}
pub fn make_pair(left: Integer, right: String) -> Pair<Integer, String> {
{left, right}
}

An atom literal such as :ok is itself a type containing exactly one value. Joining literals with | makes a finite union, which is precisely what case can cover exhaustively:

mod types
pub fn label(status: :ok | :error) -> String {
case status {
:ok -> "ok"
:error -> "error"
}
}

Boolean is the built-in union :true | :false, and Nilable<T> is shorthand for T | nil. Both use union checking and narrowing; Nilable is useful for nullable native fields.

An algebraic data type names its constructors and their payloads, and can contain itself. Nullary constructors emit snake-case atoms; payload constructors emit tagged tuples:

mod types
pub type Tree<A> =
| Leaf
| Node(A, Tree<A>, Tree<A>)
pub fn sum(tree: Tree<Integer>) -> Integer {
case tree {
Leaf -> 0
Node(n, left, right) -> n + sum(left) + sum(right)
}
}

After you add a constructor, the compiler reports case expressions that need another arm to cover it.

Constructor arguments can have labels, allowing calls and patterns to list fields in any order. Trailing fields can carry pure defaults. Named declarations require labels; positional ones use positions:

mod types
alias gale_std.list
@typedoc "Constructor fields can have labels and trailing, pure defaults."
pub type Retry = Retry(delay_ms: Integer, attempts: Integer = 3)
pub fn retry() -> Retry {
Retry(delay_ms: 100)
}
pub fn attempts(retry: Retry) -> Integer {
case retry {
Retry(attempts: count, delay_ms: _) -> count
}
}
@doc "Construct payload values inside an explicit lambda."
pub fn present(values: List<Integer>) -> List<Option<Integer>> {
list.map(values, fn(value) -> Some(value))
}
pub fn from_native(value: Nilable<String>) -> Option<String> {
case value {
nil -> None
text -> Some(text)
}
}

Supplied arguments evaluate once, in source order, then omitted defaults fill in declaration order. Defaults cannot reference sibling fields. Omitting a field in a pattern is a wildcard, not a comparison against the default. Write Retry(attempts: 3) for the literal comparison, which keeps the ordinary Retry type and adds a branch fact for the proof. And nil is never None: one is an atom, the other a constructor.

Term can hold any BEAM value. A guard narrows its type within the matching arm. Gale emits the corresponding Elixir guard; a type annotation alone does not insert a runtime test:

mod types
pub fn as_binary(value: Term) -> Option<Binary> {
case value {
binary when is_binary(binary) -> Some(binary)
_ -> None
}
}

Keyword entries need no special machinery: they are ordinary atom-keyed tuples in a list.

pub fn as_integer(value: Term) -> Option<Integer> {
case value {
integer when is_integer(integer) -> Some(integer)
_ -> None
}
}
@doc "Keyword entries are ordinary atom-keyed tuples in a list."
pub fn options() -> List<{:timeout, Integer} | {:mode, :safe}> {
[timeout: 5_000, mode: :safe]
}

An opaque type gives a value a distinct identity and keeps its representation inside the defining module. A UserId is stored as an integer, but functions that accept UserId require an ID created through its public API:

mod types
pub opaque type UserId = Integer
pub fn user_id(raw: Integer) -> UserId {
UserId(raw)
}
pub fn user_id_value(UserId(raw): UserId) -> Integer {
raw
}

Other modules call types.user_id(42) to create an ID and types.user_id_value(id) to read it. Only types can use the UserId(raw) constructor or open it in a pattern. The wrapper adds no runtime tag; the BEAM value is still the integer 42.

Opaque types can also carry invariants. The GenServer chapter uses one for server state, and the proving chapter shows how to verify that updates preserve it.

A constructor can choose a type argument. Here, Count asks for an Integer and Name asks for a String. The return type of answer follows the request:

mod types
pub type Request<Reply> =
| Count: Request<Integer>
| Name: Request<String>
pub fn answer<Reply>(request: Request<Reply>) -> Reply {
case request {
Count -> 42
Name -> "Ada"
}
}
pub fn current_count() -> Integer {
answer(Count)
}
pub fn current_name() -> String {
answer(Name)
}

Matching Count tells the compiler that Reply is Integer in that branch. Matching Name makes it String. Callers keep the specific result type, so current_count returns an integer without a cast or another match. The same relationship can connect a message request to its reply type.

Never has no values. A function returning Never cannot return a value normally; this does not promise termination or process survival.