liminfoGleam Language Reference
Free reference guide: Gleam Language Reference
About Gleam Language Reference
The Gleam Language Reference is a searchable syntax cheat sheet for Gleam, a statically typed functional programming language that compiles to Erlang and JavaScript. It covers five core areas: Basic syntax (let bindings for immutable variables, fn function definitions, pub fn for public API functions, the |> pipe operator for chaining transformations, the use expression for flattening callback-style code, and labelled arguments for named parameters), Type system (Int with arbitrary precision, Float, UTF-8 String, Bool, immutable List(a) with prepend syntax, the Result(value, error) type for error handling without exceptions, and Option(a) for nullable values), Pattern matching and custom types (case expressions with guards, custom type definitions like Shape with Circle and Rect constructors, and type aliases), Module system (import with selective imports, pub type for exported types), and Erlang/OTP integration (gleam.toml project configuration and OTP actor pattern using gleam/otp/actor).
Gleam is designed for teams building reliable, concurrent backend services on the BEAM virtual machine — the same runtime powering Erlang and Elixir. Its static type system catches errors at compile time with friendly error messages, while its Erlang interoperability enables access to OTP primitives like supervisors, gen_servers, and lightweight processes. The JavaScript compilation target allows Gleam to be used for frontend development and Node.js scripts as well. Developers coming from Rust, Elm, or Haskell will find Gleam's type system and functional patterns familiar, while those from Elixir will recognize the BEAM runtime model.
The reference groups entries into five browsable categories. The Basics section is especially useful for developers new to Gleam who need to understand immutable bindings, the distinction between fn and pub fn, and how the pipe operator |> chains function calls without nested parentheses. The Types section documents the built-in types and the critical Result/Option types used for safe error handling. The Patterns section explains Gleam's exhaustive case expressions and how to define algebraic data types. Each entry includes a code example demonstrating the syntax in context.
Key Features
- Basics: let bindings (immutable), fn/pub fn definitions, |> pipe operator, use expression for callback flattening, labelled arguments
- Types: Int (arbitrary precision), Float, String (UTF-8), Bool, List(a) with prepend, Result(value, error), Option(a)
- Pattern matching: case expressions with guards (n if n > 0), exhaustive matching with _ wildcard
- Custom types: algebraic data type definitions with constructors (Circle, Rect), type aliases
- Modules: import with selective imports (import gleam/string.{append}), pub type for exported types
- OTP integration: gleam.toml project config (name, version, target), OTP actor pattern with gleam/otp/actor
- Code examples for every entry showing real Gleam syntax including string concatenation with <> operator
- Covers both Erlang (BEAM) and JavaScript compilation targets via gleam.toml target setting
Frequently Asked Questions
What is Gleam and who is it for?
Gleam is a statically typed functional programming language that compiles to Erlang bytecode (running on the BEAM VM) or JavaScript. It is designed for developers who want the reliability and concurrency model of Erlang/OTP combined with a modern, friendly type system. It is particularly well-suited for building fault-tolerant backend services, APIs, and distributed systems. Developers from Rust, Elm, Elixir, and TypeScript backgrounds find Gleam approachable.
What is the pipe operator |> in Gleam?
The pipe operator |> passes the result of the left-hand expression as the first argument to the right-hand function. It allows you to write data transformation chains in a left-to-right, top-to-bottom reading order without deeply nested parentheses. For example, "hello" |> string.uppercase |> string.append(" WORLD") is equivalent to string.append(string.uppercase("hello"), " WORLD").
How does Gleam handle errors without exceptions?
Gleam uses the Result(value, error) type for functions that can fail. A function returns Ok(value) on success or Error(reason) on failure. Callers must handle both variants using a case expression or helper functions from the gleam/result module. The use expression combined with result.try provides a concise way to chain fallible operations without nested case blocks, similar to the ? operator in Rust.
What is the difference between Result and Option in Gleam?
Result(value, error) represents either a successful computation with a value or a failure with an error reason. Option(a) represents either a present value (Some(value)) or the absence of a value (None). Use Result when the failure case carries meaningful information (error message, error code). Use Option when a value is simply optional — for example, finding an item in a list that may not exist.
How do custom types work in Gleam?
Custom types in Gleam are algebraic data types defined with the type keyword followed by one or more constructors. Each constructor can have named fields with types. For example, type Shape { Circle(radius: Float) Rect(width: Float, height: Float) } creates a type with two variants. Pattern matching with case is exhaustive — the compiler requires all constructors to be handled, preventing unhandled cases at runtime.
What is the use expression in Gleam?
The use expression is syntactic sugar for callbacks that makes code with multiple nested callback functions look flat and sequential. Instead of nesting functions like result.try(read_file("data.txt"), fn(file) { ... }), you write use file <- result.try(read_file("data.txt")) followed by the code that uses file. This is especially useful when chaining multiple Result or Future operations.
What is the BEAM target and how does it differ from the JavaScript target?
When gleam.toml sets target = "erlang", Gleam compiles to Erlang bytecode that runs on the BEAM virtual machine. This gives access to OTP primitives like supervisors, gen_servers, and the process model for building highly concurrent, fault-tolerant systems. When target = "javascript", Gleam compiles to JavaScript suitable for browser or Node.js environments. The language syntax is identical in both targets, but available standard library modules differ.
How do labelled arguments work in Gleam?
Gleam functions can have labelled (named) arguments that callers must use by name. Define them with label name: in the function signature: fn create(name name: String, age age: Int) { }. Call them as create(name: "Jo", age: 30). Labelled arguments improve call-site readability, allow arguments to be passed in any order, and eliminate confusion when multiple parameters have the same type.