Gleam Programming Language

The Gleam compiler is composed of several Rust crates and supporting components:

Rust Crates

• compiler-core: The pure core of the compiler. It handles parsing, analysis, and compilation. It has no IO; IO is provided by the wrapper crates.
• language-server: Implements the Gleam language server (LSP) features like autocomplete, code actions, and hover.
• compiler-cli: The command line interface that wraps compiler-core and language-server to provide IO for files and the console.
• compiler-wasm: A WebAssembly interface to the core compiler, allowing it to run in web browsers via JavaScript.

Other Components

• Makefile: Contains shortcut commands for common development tasks. Use make help to see them.
• test: A collection of Gleam projects used for integration testing.
• containers: Docker files for producing OCI containers for Gleam releases.

The Gleam compiler (v1.11.0-rc1 and later) provides more descriptive error messages:

• Inexhaustive patterns: When a case expression does not cover all possible values, the error message now explicitly lists the missing patterns (e.g., The missing patterns are: Person(name:, age:)).
• Incorrect arity: When a type is used with the wrong number of arguments, the error message specifies the expected vs. actual number of type arguments (e.g., Expected 1 type argument, got 0).

In Gleam, todo and panic are not functions; they are special expressions. If you attempt to pass arguments to them like functions (e.g., todo(1)), the compiler will issue a warning. To include an error message, use the as syntax.

// Incorrect
todo(1)

// Correct
todo as "my error message"

The Gleam Language Server (v1.15.0-rc1) provides enhanced developer experience features:

• Folding: Supports textDocument/foldingRange, allowing you to fold contiguous import blocks and multiline top-level definitions (functions, types, constants, etc.).
• Hover Information: Now shows hover details for custom type definitions and their constructors.
• Find References & Rename: Now supported for variables and string prefix patterns in case clause guards.
• Function Signature Help: When arguments are unbound, the helper displays the original generic names from the function definition (e.g., wibble(something, fn() -> something, anything)) instead of placeholder names (e.g., wibble(a, fn() -> a, b)).

The compiler now warns if a case expression contains a bit array pattern that can never match due to impossible values. For example, matching a single byte against a value like 404 will trigger a warning because a 1-byte unsigned integer cannot exceed 255.

pub fn get_payload(packet: BitArray) -> Result(BitArray, Nil) {
  case packet {
    <<200, payload:bytes>> -> Ok(payload)
    <<404, _:bits>> -> Error(Nil) // Warning: Unreachable pattern
    _ -> Ok(packet)
  }
}

The [a..b] syntax is deprecated to avoid confusion with range syntax (which Gleam does not have). Use the [a, ..b] syntax instead for pattern matching or appending to the start of a list.

// Use this:
[a, ..b]

// Instead of this (deprecated):
[a..b]

The Gleam compiler uses cargo-insta for snapshot testing. Instead of manually defining expected outputs, the compiler saves outputs as .snap files.

If a change in the compiler's output (like error messaging or code generation) causes a test to fail, you can use cargo insta review to interactively decide whether to reject the change or accept the new output as the correct version.

# Run the tests
make test

# Interactively verify changes to the snapshots
cargo insta review