The Rock Programming Language

A practical guide to learning Rock, from your first expression to generic functional abstractions and systems programming.

Rock is a statically typed, expression-oriented language with significant indentation. It combines algebraic data types, pattern matching, traits, ownership and borrowing, first-class functions, user-defined operators, and a system-programming core.

This book assumes that you have programmed before. You do not need experience with Rust, Haskell, or another functional language. When Rock uses an unfamiliar idea, the book introduces the motivation before the syntax.

Rock is under active development. This book describes the language implemented in this repository, calls out current limitations, and avoids compiler-only mechanisms that ordinary programs should not use.

Use the left and right arrow keys to move between pages, press S to focus search, or use the chapter list in the sidebar.

Introduction

Rock is a full-fledged, expression-oriented programming language designed to make powerful programs easy to read. Like Rust, it embraces a rich syntax while keeping structure visible and understandable. It provides the foundations expected of a modern systems language, including type checking, ownership, and contracts for method receivers. Indentation forms blocks, function calls use spaces and commas, and operators are supplied by the program and its explicit dependencies.

This is a complete program. It uses only names supplied by the standard-library prelude and can be read from top to bottom.

enum Greeting
    Hello &Str
    Goodbye

message = greeting ->
    match greeting
        Greeting::Hello name => "Hello, " + name
        Greeting::Goodbye => "See you soon"

main = !->
    Greeting::Hello "Rock"
        |> message
        |> (.println!)

The program has three top-level declarations:

1. Greeting is an enum. A value is either Hello with a borrowed string payload or Goodbye with no payload.
2. message is a function. Its parameter is greeting, and its body is the indented expression after ->.
3. main is the executable entry point. Its !-> body runs for effects and returns unit (()).

The execution order is explicit. main constructs a Greeting::Hello, passes it to message, and prints the returned string. Its !-> body discards the trailing value and returns unit (()), which the runtime maps to process exit status 0. The match expression chooses the first arm whose pattern fits the value. Because the Hello arm binds name, the body can concatenate that payload with another string.

The visual grammar

Rock uses indentation instead of braces. Every line indented farther than its header belongs to that header. The else keyword aligns with the if that owns it, and match arms align with one another.

Function declarations use name = parameters -> body. Calls put arguments after the callee and separate multiple arguments with commas:

add = left, right -> left + right
main = !-> add 20, 22 .println!

The call add 20, 22 has two arguments. Each argument is a complete expression, so add 2 + 3, 4 passes 5 and 4 without extra grouping. Parentheses remain useful when they change precedence or delimit a nested call containing commas; they do not replace the space-and-comma call syntax. A trailing ! invokes a zero-argument function or method, so println! means “call println with no explicit arguments.”

Blocks are expressions. A block evaluates each earlier expression for its effects and gives the final expression as its value:

square = number ->
    number * number

main = !->
    square 6 .println!

The function square returns 36 because its final expression is number * number. In main, .println! runs for its effect, and !-> discards its value and returns unit.

Types without ceremony

Local types are commonly inferred. An annotation is useful when it documents an interface or removes ambiguity:

double: I64 -> I64
double = value ->
    value * 2

main = !->
    answer: I64 = double 21
    answer.println!

double accepts an I64 and returns an I64. The annotation does not change the call syntax or create a runtime conversion. It gives the compiler a contract to check.

What to expect from the book

The getting-started chapters build a runnable program before the language reference separates the ideas. Read Hello, Rock! first, then A First Project. The language chapters revisit values, functions, control flow, and data types before introducing ownership, borrowing, traits, and reusable library interfaces.

Most examples use the standard library shipped with the selected Rock toolchain. The rock project command resolves that matching library automatically unless a manifest explicitly sets no_std = true.

A Learning Path

Read the book in order for a first pass, or choose a checkpoint that matches your experience:

Higher-kinded types and unsafe programming are deeper topics, not prerequisites for writing your first application. Return to them when a reusable abstraction or a low-level boundary makes their motivation concrete.

At each stage, run the complete program first. Then change one input, predict the result, and compare it with the output or diagnostic. For the HTTP project, the chapter includes requests that check success, method rejection, and missing routes rather than relying only on a server-started message.

The examples in this book are intentionally complete. A rock fence either contains a whole program or a complete top-level module fragment whose declarations are all present in that fence. A name supplied by the stdlib prelude may be used without an import; any other external name must be imported in the same file.

What this book does not cover

This is a user guide, not a compiler implementation guide. It does not document parser data structures, intermediate representations, artifact internals, compiler-recognized item markers, or code-generation machinery. Low-level syntax appears only when it is part of a public application or library interface.

Rock is still a prototype. The broad language model is exercised by parser and compiler tests, but some ecosystem commands and library conveniences are incomplete. Each chapter calls out current behavior where it differs from the ideal a future release may provide.

Common first mistakes

• Treating parentheses as mandatory call syntax. Write max 5, 7, not max(5, 7).
• Forgetting that a block’s last expression is its value.
• Using an enum payload without first matching the enum variant.
• Assuming a familiar operator has a compiler-defined meaning. The active program and its dependencies must provide the operator implementation.
• Running rock outside a project directory containing rock.toml.

Installation

Rock’s release toolchain supports only Linux x86_64 with GNU glibc (x86_64-unknown-linux-gnu). The binary baseline is Ubuntu 24.04, requiring glibc 2.39 or newer and a C linker available as cc. LLVM 18 is statically linked, so end users do not need to install LLVM. The executables are not fully static: system-library dependencies remain.

Release format: rockup requires v0.5.0 or later. Historical releases use a different asset layout and cannot be installed through this bootstrap.

Prerequisites

For binary installation on Ubuntu 24.04, install the runtime requirements yourself:

$ sudo apt install build-essential curl ca-certificates

GNU tar, gzip, and sha256sum must also be installed (normally already present on Ubuntu). Rockup uses curl for HTTPS downloads and those tools to verify and unpack archives. The installer never invokes sudo or installs operating-system packages. Neither Rust nor LLVM is required to use a binary release.

Install a release

Install the manager and complete Rock toolchain with this one-liner. It executes a script from the official Rock-lang-org/Rock release publisher; only run it if you trust that publisher. You can inspect install.sh separately first.

curl --proto '=https' -fsSL https://github.com/Rock-lang-org/Rock/releases/latest/download/install.sh | sh

The bootstrap downloads the standalone rockup-x86_64-unknown-linux-gnu and its exact .sha256 sidecar over HTTPS, checks that the sidecar names that asset and that its checksum matches, then executes rockup self install. This copies the manager and command shims and adds shell setup. The script then invokes the installed manager’s rockup install stable automatically to download and install the compiler, project command, language server, and standard library. No shell restart or separate command is needed between these steps.

Rockup verifies the toolchain archive before unpacking it. Checksums detect corruption; they are not independent signatures, so you still trust the official release publisher and HTTPS.

The bootstrap defaults to stable, meaning GitHub’s latest published non-prerelease release, not a promise that this experimental language has a stable API. To pin both the manager and toolchain versions when bootstrapping, pass a published vVERSION tag:

$ curl --proto '=https' -fsSL https://github.com/Rock-lang-org/Rock/releases/latest/download/install.sh | sh -s -- v0.6.0

That command installs both rockup and the v0.6.0 toolchain. From a checkout, sh scripts/install.sh v0.6.0 does the same. Stable manager assets come from releases/latest/download; pinned manager assets come from releases/download/vVERSION.

Home and shell setup

The bootstrap persists rockup as ~/.rockup/bin/rockup, creates rock, rockc, and rock-lsp shims in ~/.rockup/bin, and installs the selected toolchain under ~/.rockup/toolchains. Set ROCKUP_HOME to a nonempty absolute path before installation to use another location; keep using that value in later shells.

An installed toolchain uses the standard library beside its own binaries, even when you run it inside a compiler checkout with a target/ directory. CARGO_TARGET_DIR affects development sysroot discovery, not installed toolchains. ROCK_SYSROOT remains an explicit override; leave it unset for normal rockup-managed use.

The bootstrap refuses to overwrite an existing ROCKUP_HOME/bin/rockup, including a dangling symlink. Use that installed manager’s install, update, or self update command instead of rerunning the bootstrap. If toolchain installation fails after the manager is installed, the script exits with an error and prints the exact command to retry; the manager remains installed. Installing a release does not delete an installed local dev toolchain or replace an existing default; the first toolchain in an empty home becomes the default.

Rockup writes an env file and a managed activation block to .bashrc for Bash, .zshrc for Zsh, or .profile for other shells, based on SHELL. It also updates existing Bash and Zsh configuration files. Restart your shell, or activate a POSIX-compatible shell immediately:

. "${ROCKUP_HOME:-$HOME/.rockup}/env"

After activating the shell, verify:

rock --version
rock-lsp --help

The generated activation script uses POSIX shell syntax; it is not native Fish or PowerShell setup. rock-lsp without arguments starts an LSP server over standard input/output, not an interactive prompt.

Manage releases and pins

With rockup installed, the shortest commands install or update the latest stable release:

$ rockup install
$ rockup update

Both commands default to stable. Use update when that toolchain is already installed.

Install a version without changing an existing default:

$ rockup install v0.6.0

The bare spelling rockup install 0.6.0 selects the same release and stores it as v0.6.0; do not run both installation commands for the same version. To choose it globally or run a single command explicitly:

$ rockup default v0.6.0
$ rockup run v0.6.0 rock --version

rockup default NAME selects an installed toolchain, including local dev, and automatically installs a missing stable or versioned release. Arbitrary local names must first be installed with --path.

For a project pin, create rock-toolchain.toml in the project directory with this schema:

[toolchain]
channel = "v0.6.0"

Install that version first. The shims select a toolchain using ROCKUP_TOOLCHAIN first, then the nearest rock-toolchain.toml in the current directory or its ancestors, then the global default. A project pin selects an installed toolchain; it does not automatically download one. Use the canonical v spelling for version pins, or an installed local name such as dev.

Update the moving stable toolchain and the manager separately:

$ rockup update
$ rockup update stable
$ rockup self update
$ rockup list

The first two commands are equivalent. Updating stable leaves separately installed pinned versions and local development toolchains in place. self update replaces the running rockup executable with the latest stable manager. To remove a version, select a different default first and remove any project or environment selection that still refers to it:

$ rockup default stable
$ rockup remove v0.6.0

Rockup is not a full Rustup replacement. Release downloads do not support Windows, macOS, musl, other CPU architectures, a nightly channel, or automatic cross-target installation. The local target add --path component workflow does not imply downloadable cross-target releases.

Build from source

For compiler development or a local source build, install these additional tools through your operating system:

• Git
• A Rust toolchain with Cargo
• LLVM 18 development tools (including llvm-config), headers, and static archives
• A C linker available as cc

On Ubuntu 24.04, install the build dependencies and select LLVM 18 explicitly:

$ sudo apt install llvm-18-dev libpolly-18-dev libzstd-dev libxml2-dev zlib1g-dev libffi-dev libedit-dev libncurses-dev build-essential
$ export LLVM_SYS_180_PREFIX=/usr/lib/llvm-18

Source builds require static LLVM archives; there is no dynamic-linking fallback.

Clone the repository and build the release toolchain:

$ git clone https://github.com/Rock-lang-org/Rock.git
$ cd Rock
$ cargo build --release

Preparing a development toolchain

Package the standard library beside the release binaries, then install that directory as a local toolchain:

$ target/release/rockup dev stdlib package \
    --path stdlib \
    --sysroot target/release
$ target/release/rockup install dev --path target/release
$ target/release/rockup default dev

The installer creates command shims and prints the shell setup it added. Restart the shell when prompted, then verify the user-facing command:

$ rock --version
$ rock-lsp --help
$ rockup list

The selected toolchain contains the compiler implementation and matching standard library, but application authors interact with it through rock. The project command discovers manifests, builds path dependencies, selects the standard library, and manages output paths.

It also contains rock-lsp, the language server used by editors. rockup installs a shim for this command alongside rock, so an editor started from the activated shell can find the selected server. rock-lsp --help checks that the command can start; running it without arguments starts an LSP server over standard input and output, not an interactive compiler prompt.

Optional editor setup

The separate rock.nvim repository contains a plugin that uses Neovim’s built-in LSP client; it does not require nvim-lspconfig. The plugin requires Neovim 0.11 or newer. Clone that repository, then add this to init.lua, replacing the path with your checkout:

vim.opt.runtimepath:prepend("/absolute/path/to/rock.nvim")
require("rock").setup()

Installing the plugin does not build or install the Rock toolchain. Complete the toolchain steps above first, then open a project’s .rk file and run :checkhealth rock.

For local-checkout setup, editor commands, and a walkthrough of compiler errors, continue with Editors and Diagnostics. Other LSP clients can start rock-lsp for .rk files using the rock language identifier and standard input/output transport.

Compiler contributor checks

Run the compiler’s Rust tests when changing the language implementation:

$ cargo test -p rock-lib

Common setup failures

• HTTP 404 for bootstrap assets means the selected release does not provide the required assets; select v0.5.0 or later, or use the source workflow.
• A checksum mismatch or malformed sidecar stops installation before the downloaded manager executes. Do not bypass verification; retry or report the release asset problem.
• GLIBC_2.39 errors mean the host is older than the release baseline. Use Ubuntu 24.04 or a compatible newer GNU system, or build from source on your host.
• Source-build llvm-config or missing static-archive errors mean you should check the LLVM 18 development packages above and LLVM_SYS_180_PREFIX=/usr/lib/llvm-18; do not switch to dynamic linking. Binary releases do not require an LLVM installation.
• A missing standard-library component means the packaging step did not complete or the installed toolchain does not match the checkout.
• If rock is not found after installation, restart the shell or apply the activation command printed by rockup.
• If rock-lsp is missing from a toolchain built from an older checkout, rebuild and package the current workspace before installing it; a current toolchain installation requires the server binary too.
• If an editor cannot find rock-lsp but the shell can, start the editor from that shell or configure an absolute server command as shown in Editors and Diagnostics.
• If a generated executable is not found, inspect the project’s build/ directory.

Hello, Rock!

Create your first project with rock new:

rock new hello
cd hello

This creates a new directory containing rock.toml, src/main.rk, and a .gitignore that excludes build output. Existing directories are never overwritten. Project names start with an ASCII letter and can contain letters, digits, hyphens, and underscores; stdlib is reserved.

The generated rock.toml manifest is:

[crate]
name = "hello"
version = "0.1.0"

[lib]
path = "src/main.rk"

The generated src/main.rk contains this complete program:

main = !->
    "Hello, Rock!".println!

Run it from the project directory:

$ rock run
Hello, Rock!

The output contains one line, and the process exits with status zero.

Reading the program

main = !-> declares a function named main with no parameters. The arrow separates its parameter list from its body. The extra indentation makes the next line part of that body.

The string literal is borrowed string data. .println! calls the prelude’s printing method with no explicit arguments. The !-> body evaluates that call, discards its result, and returns unit (()). The runtime maps a unit-returning main to process exit status 0, so no final 0 expression is needed.

Use main = !-> for ordinary programs. Keep main = -> when you intentionally return an integer exit status, such as 1 to report failure; that arrow returns the body’s trailing value instead of discarding it.

Calls with arguments use spaces and commas:

main = !->
    max 10, 20 .println!

max is a prelude function. The first argument is 10 and the second is 20. The space before .println! makes the method apply to the result of the complete max 10, 20 call, so this prints 20 directly.

Expressions and statements

A one-expression function can stay on one line or use an indented body:

square = number ->
    number * number

main = !->
    square 5 .println!

The final expression of square is its return value. Earlier expressions can perform effects before the final value:

announce_square = number ->
    "squaring a number".println!
    number * number

main = !->
    announce_square 5 .println!

An if/else expression produces the value of the selected branch. When it is the final expression in a function, that value becomes the function’s return value:

absolute = number ->
    if number >= 0 
    then number
    else -number

main = !->
    absolute -5 .println!

For -5, the condition is false, so the else branch evaluates -number and produces 5. For a nonnegative value, the then branch produces number unchanged. The selected value is returned by absolute.

Comments

Rock supports line and block comments:

main = !->
    // This line explains why the next value is printed.
    /* A block comment can
       cover several source lines. */
    "comments do not produce values".println!

Comments are ignored by the compiler. Use them for intent, constraints, or a non-obvious reason, not as a translation of every line.

Common mistakes

• Using !-> when you intend to return a custom integer exit status; use -> instead.
• Writing println("text"); the current call form is "text".println!.
• Indenting a statement at the same level as main = !->; that makes it a separate top-level item instead of part of main.
• Running rock outside the directory containing rock.toml.

A First Project: FizzBuzz

FizzBuzz is a useful first project because it combines a value-producing function, an enum, guarded pattern matching, a range, and an inline callback without needing a large library. The rules are:

1. Visit the integers from 1 through 30.
2. Print FizzBuzz for a multiple of both 3 and 5.
3. Otherwise print Fizz for a multiple of 3.
4. Otherwise print Buzz for a multiple of 5.
5. Print the number for every other value.

The complete program

Create a project manifest as rock.toml:

[crate]
name = "fizzbuzz"
version = "0.1.0"

[lib]
path = "main.rk"

Save the program as main.rk beside the manifest:

enum FizzBuzzValue
    Text &Str
    Number I64

fizzbuzz_value: I64 -> FizzBuzzValue
fizzbuzz_value = number ->
    match number
        n if n % 15 == 0 => FizzBuzzValue::Text "FizzBuzz"
        n if n % 3 == 0 => FizzBuzzValue::Text "Fizz"
        n if n % 5 == 0 => FizzBuzzValue::Text "Buzz"
        n => FizzBuzzValue::Number n

print_value: FizzBuzzValue -> I32
print_value = value ->
    match value
        FizzBuzzValue::Text text => text.println!
        FizzBuzzValue::Number number => number.println!

main = !->
    for_each 1..=30, number !->
        number
            |> fizzbuzz_value
            |> print_value

Run it from the project directory:

$ rock run

The complete output is:

1
2
Fizz
4
Buzz
Fizz
7
8
Fizz
Buzz
11
Fizz
13
14
FizzBuzz
16
17
Fizz
19
Buzz
Fizz
22
23
Fizz
Buzz
26
Fizz
28
29
FizzBuzz

Start with the result type

The calculation has two possible shapes: a word or the original number. The enum gives both shapes one static type:

enum FizzBuzzValue
    Text &Str
    Number I64

FizzBuzzValue is the type. Text carries borrowed string data, while Number carries an I64. A constructor is qualified with the enum name:

enum FizzBuzzValue
    Text &Str
    Number I64

main = !->
    word = FizzBuzzValue::Text "Fizz"
    number = FizzBuzzValue::Number 7
    word_text = match word
        FizzBuzzValue::Text text => text
        FizzBuzzValue::Number value => "number"
    word_text.println!
    number_text = match number
        FizzBuzzValue::Text text => text
        FizzBuzzValue::Number value => "number"
    number_text.println!

Both local bindings have the same enum type even though their payloads differ. The matches make the payload types visible: text is &Str in its arm and value is I64 in its arm.

Separate calculation from output

The signature states the contract before the definition:

enum FizzBuzzValue
    Text &Str
    Number I64

fizzbuzz_value: I64 -> FizzBuzzValue
fizzbuzz_value = number ->
    match number
        n if n % 15 == 0 => FizzBuzzValue::Text "FizzBuzz"
        n if n % 3 == 0 => FizzBuzzValue::Text "Fizz"
        n if n % 5 == 0 => FizzBuzzValue::Text "Buzz"
        n => FizzBuzzValue::Number n

The signature says that one I64 becomes one FizzBuzzValue. The body does not print, so the calculation can be reused by another output function or a test. Each match arm constructs the same enclosing enum type even though the selected variant differs.

Each n pattern binds the input integer within its own arm. An if guard checks an additional condition; % computes a remainder and == produces a Bool. Arms are checked from top to bottom, and the first successful arm supplies the result. Checking divisibility by 15 first is essential because a 3-only arm placed first would hide the combined case. The final unguarded n arm handles every remaining number.

Recover the payload with match

The output function consumes one enum value and handles both variants:

enum FizzBuzzValue
    Text &Str
    Number I64

print_value: FizzBuzzValue -> I32
print_value = value ->
    match value
        FizzBuzzValue::Text text => text.println!
        FizzBuzzValue::Number number => number.println!

An arm pattern checks the variant and binds its payload at the same time. The arm body is evaluated only after its pattern succeeds. Listing both variants makes the output decision visible in one place.

Traverse the range with for_each

for_each is a generic prelude function with two arguments: the values to visit and an action to run for each value. Here 1..=30 includes both endpoints, and number !-> introduces the inline action:

1. for_each supplies the next integer as number, in ascending order.
2. number |> fizzbuzz_value passes that integer to the calculation and produces a FizzBuzzValue.
3. |> print_value passes that result to the output function.
4. The action’s !-> discards the printing result and returns unit (()).

The |> operator passes the value on its left to the function on its right. Indented continuation lines keep the pipeline together as one expression. There is no counter to update and no intermediate collection: bounded ranges are traversed directly, and for_each returns only after every action has completed. Both endpoints are required; an open-ended range is rejected at runtime.

The same function also works with foldable containers such as Vec, Option, and Result; Higher-Kinded Types explains how their shared Foldable abstraction supplies the traversal.

A for version

An ordinary for loop can express the same traversal. An exclusive range written with .. excludes its upper bound, so this version uses 1..31:

enum FizzBuzzValue
    Text &Str
    Number I64

fizzbuzz_value: I64 -> FizzBuzzValue
fizzbuzz_value = number ->
    match number
        n if n % 15 == 0 => FizzBuzzValue::Text "FizzBuzz"
        n if n % 3 == 0 => FizzBuzzValue::Text "Fizz"
        n if n % 5 == 0 => FizzBuzzValue::Text "Buzz"
        n => FizzBuzzValue::Number n

print_value: FizzBuzzValue -> I32
print_value = value ->
    match value
        FizzBuzzValue::Text text => text.println!
        FizzBuzzValue::Number number => number.println!

main = !->
    for number in 1..31
        value = fizzbuzz_value number
        print_value value

The loop pattern number receives each range element. There is no explicit increment because the range iterator advances it.

Extract a repeated idea

The divisibility test is a reusable function with two arguments:

is_divisible: I64 -> I64 -> Bool
is_divisible = number, divisor ->
    number % divisor == 0

The signature lists two I64 parameters followed by a Bool result. The -> definition receives both arguments in one call; it is not a curried ~> definition. In a larger version of the project, the first match arm could read n if is_divisible n, 15 => FizzBuzzValue::Text "FizzBuzz" without changing the underlying calculation.

Common mistakes

• Checking % 3 before % 15, which changes the result for 15.
• Forgetting that 1..31 excludes 31 and therefore includes 30 as its final element.
• Placing the unguarded n arm first, which would match every number before any divisibility guard is checked.
• Returning a raw string from one match arm and an integer from another; all arms still need one enclosing type.
• Using -> for an action that leaves the printing result as its return value; for_each expects a unit-returning action, so use !->.
• Assuming an enum payload is available outside its matching arm; the binding is introduced by the pattern.

The next chapters isolate each of these language features so that you can reason about the type and value flowing through every line.

Projects and the Toolchain

A project gives rock enough information to find an entry file, resolve path modules, and choose build output locations. This chapter starts with one file; Modules and Visibility later shows the complete source of a multi-file project, and Packages and Dependencies builds two path-dependent packages.

The manifest

Create a directory containing rock.toml:

[crate]
name = "hello"
version = "0.1.0"

[lib]
path = "main.rk"

Put a complete Rock program in main.rk:

main = !->
    "project entry point".println!

Rock currently calls the source entry a library path even when it contains the executable main function. From the project directory, build and run it:

$ rock build
$ rock run
project entry point

Pass application arguments after --:

$ rock run -- first second

The project command writes products below build/, including object files, crate artifacts, and a linked executable when requested.

Everyday commands

$ rock format     # Format the configured entry source
$ rock build      # Build the current project
$ rock run -- first second # Build and run it with two arguments
$ rock expand     # Print macro-expanded source
$ rock artifact   # Materialize a reusable crate artifact

There is currently no rock test command. Compiler contributors use Cargo’s Rust test suite; application tests are ordinary Rock programs or external harnesses.

Formatting caution

The formatter is still maturing. Known rough edges affect some trait implementation headers, nested generic applications, and &mut expressions. Keep source under version control, inspect formatter changes, and compile after formatting nontrivial code.

One project workflow

Keep even small learning programs in a project with rock.toml. This gives examples, scripts, editors, and larger packages the same rock format, rock build, and rock run workflow from the beginning.

How the editor finds your program

When you open a .rk file, rock-lsp searches its parent directories for the nearest rock.toml. It uses the manifest’s entry path and crate name, resolves path dependencies through the same project code as rock build, and selects the toolchain standard library. Ordinary projects do not need a hand-written list of editor dependency artifacts.

For the project above, opening main.rk analyzes the program selected by [lib].path. In a multi-file project, the server still starts from that entry and follows its module graph; opening an unrelated .rk file below the same manifest does not automatically include it in the program. See Modules and Visibility for declaring modules.

Open source buffers are supplied to analysis with their unsaved text. Files in the entry graph that are not open are read from disk. Path dependencies are resolved as compiled artifacts, rather than merged into one live source workspace, so save dependency changes before expecting a consuming project to see them. Resolving dependencies can build or refresh artifacts and write build outputs; editor startup is not necessarily a read-only operation.

Project resolution is cached. After changing rock.toml, dependency files, or the selected toolchain, save a Rock source buffer to invalidate its cached project resolution, or restart the language server. In Neovim, use :RockLspRestart. Unsaved manifest edits are not a replacement for the manifest on disk.

Without a manifest, the server analyzes the opened file as a standalone entry and does not automatically supply the toolchain standard library. Prefer a small project like the one above for learning, especially when using operators or prelude methods.

From editor feedback to a build

Live diagnostics help you fix syntax, name resolution, and type errors before saving. They are not a successful build: the editor’s source analysis does not run borrow checking, code generation, or linking for the main project.

Save your source, then check the complete program:

$ rock build
$ rock run

If the build fails, read the first diagnostic’s message and source labels before the final command-failure summary. A label can point to a module or dependency rather than the entry file. Editors and Diagnostics walks through both source errors and setup failures.

Editors and Diagnostics

An editor can show a problem while you type; a build checks whether the saved program can become an executable. This chapter sets up that feedback loop and shows how to read an error without guessing which line to change.

Start with a project

Complete Installation, then create a directory with these two files. Every Rock example in this chapter is a complete replacement for main.rk, not an addition to the previous example.

rock.toml:

[crate]
name = "diagnostics_demo"
version = "0.1.0"

[lib]
path = "main.rk"

Correct program: main.rk:

add: I64 -> I64 -> I64
add = left, right -> left + right

main = !->
    add 20, 22 .println!

From the directory containing rock.toml, run:

$ rock run
42

The manifest lets the editor and build command agree on the program entry, path dependencies, and standard library. The + operator and println method in this example come from the standard library selected by the project tooling.

Connect Neovim

The separate rock.nvim plugin uses Neovim’s native LSP APIs and requires Neovim 0.11 or newer; no nvim-lspconfig dependency is needed.

Clone the repository if you do not already have a checkout:

$ git clone https://github.com/rock-lang-org/rock.nvim.git

Add the plugin repository root to runtimepath in init.lua before setup. Replace the path with your checkout’s absolute path:

vim.opt.runtimepath:prepend("/absolute/path/to/rock.nvim")
require("rock").setup()

These snippets install or load Lua integration, not the compiler. The toolchain installation provides rock-lsp. By default, the plugin uses rock-lsp on PATH. You can also set the command explicitly:

require("rock").setup({
  cmd = { "rock-lsp" },
})

If Neovim’s environment does not include the command, use an absolute path in cmd instead. Start Neovim after activating the toolchain shell environment so that both the server and its compiler dependencies can be found.

Open main.rk, then inspect the integration:

:set filetype?
:checkhealth rock
:RockLspInfo

The filetype should be rock. The health check verifies the Neovim APIs, executable, setup, and active clients; it is not a compilation check. RockLspInfo shows the command and client root, which is useful when diagnosing a server-path problem.

With the cursor on left in the body of add in the correct program, request hover information:

:lua vim.lsp.buf.hover()

The server can show the parameter’s I64 type from the function signature. With the cursor inside add 20, 22, request call information:

:lua vim.lsp.buf.signature_help()

Signature help identifies the function’s parameters and the active argument. Commas trigger requests automatically in supporting clients; an explicit request is useful because Rock calls do not need parentheses. The plugin does not add custom key mappings, so these commands work without relying on a particular user’s keybindings.

Tree-sitter highlighting is separate. tree-sitter-rock supplies the grammar and queries, but the LSP setup above does not install that parser. The VS Code extension is also maintained separately.

Reading a source diagnostic

Intentional error: an integer annotation with a Boolean value.

main = !->
    count: I64 = true
    count.println!

Replace main.rk with this example and save it, then run rock build. Compilation should fail: true has type Bool, but the binding requires I64. The following reading order applies even as exact diagnostic wording and terminal layout evolve:

1. Read the message and any bracketed family such as type. The family describes the kind of problem, not a unique numbered error.
2. Read the displayed file path and source position. A project can contain several files; do not assume the report refers to the file currently open in the editor.
3. Read the primary underline and its label. It marks the source expression or construct associated with the failure, not necessarily the only place you should edit.
4. Read secondary labels, if present. They can show another constraint, an earlier access, or a declaration in another file.
5. Read any note or help text before changing the program. Not every diagnostic includes these sections.

For this example, compare the annotation with the initializer. If count is meant to be a number, provide a number rather than changing an unrelated print call.

Corrected program:

main = !->
    count: I64 = 3
    count.println!

rock run prints 3. If the intended value were a flag instead, a Bool annotation and a suitable binding name would express that different intent. A compiler error tells you which constraints disagree; it cannot choose the intended design for you.

In Neovim, put the cursor at the reported location and open the full diagnostic text:

:lua vim.diagnostic.open_float()

The LSP message includes available notes and help. Secondary labels are sent as related diagnostic information, though how they are displayed or navigated depends on the client. The terminal build report remains useful when an editor only shows a short message.

Following an earlier borrow

Some errors concern the relationship between two operations. Here is a complete program with a shared reference that is still needed after an assignment.

Intentional error: changing a value while it is borrowed.

main = !->
    mut number: I64 = 1
    view = &number
    number = 2
    *view .println!

Run rock build to check this example. The assignment conflicts with the shared borrow: view is used afterward, so its access must remain valid across the assignment. A borrow-conflict report can label both the conflicting access and where the borrow was introduced. Read those labels together rather than deleting the highlighted assignment without considering the later use.

Corrected program: finish using the reference before assigning.

main = !->
    mut number: I64 = 1
    view = &number
    *view .println!
    number = 2
    number.println!

This version prints 1 and then 2. The last use of view now precedes the assignment. See References and Borrowing for the ownership rules behind this correction.

The editor may show no error for the incorrect version: its main-project analysis checks the source frontend, including types, but does not run borrow checking, code generation, or linking. A clean editor diagnostic list is not proof that rock build will succeed.

When the location is not your source

Source-aware diagnostics keep labels associated with the file and source text they describe. A label in another module, a macro-related source location, or source retained with a dependency artifact is not an instruction to edit the same line number in main.rk. Follow the displayed path and read the related labels. Artifact-backed excerpts can describe the source used to build the artifact rather than your current working copy.

Not all failures have a meaningful source range. A missing file, invalid project configuration, unreadable artifact, or missing toolchain component can be reported with a file, project, artifact, or toolchain location instead. If no source text is available, a terminal report can fall back to a path and byte offsets; those offsets are not line numbers. In the editor, a project or toolchain failure may appear at the start of a buffer simply because it has no source range.

For setup failures, use this order:

1. Run rock build from the manifest directory and read the original diagnostic before the final command-failure summary.
2. Check the named path: does rock.toml select an existing entry, and do its path dependencies exist?
3. Check that the selected toolchain has its matching standard library; follow Installation if packaging or selection is incomplete.
4. After correcting files or configuration, save and restart editor analysis if its report has not refreshed.

Do not change valid source to work around a missing toolchain. Likewise, an internal diagnostic is a compiler/tooling failure, not a request to guess at syntax changes; retain the full message and a small reproducing project when reporting it.

Keep feedback current

The server finds the nearest ancestor rock.toml and analyzes its entry graph. Unsaved open source buffers overlay that graph, while unopened source comes from disk. Files outside the graph are not automatically analyzed just because they are under the project directory. Dependency packages are consumed as artifacts, so save their changes before refreshing a consuming project.

Dependency resolution can build artifacts and is cached. There is no automatic manifest/dependency file-watcher refresh; after saving changes to project configuration or selecting another toolchain, save a Rock buffer or restart:

:RockLspRestart

Diagnostics are currently published to open files rather than collected into a complete workspace index. Hover and signature help require a successful analysis; after an invalid edit, the server retains the previous successful snapshot, so information can be stale. Refreshing one buffer also does not guarantee that all other buffers’ diagnostics have been cleared. Save and run rock build when editor feedback is incomplete or disagrees with your expectations.

The server currently provides diagnostics, hover, and signature help, not completion, go-to-definition, rename, code actions, or LSP formatting. Use rock format for the configured entry and inspect its changes, then rock build and rock run for the saved program. Tooling Reference lists server overrides and plugin options when you need more control.

Bindings, Reassignment, and Mutability

A binding gives a value a name. Rock does not use a let keyword; an assignment-shaped statement introduces a local when the name has not been seen in the current scope.

main = !->
    answer = 42
    name = "Ada"
    answer.println!
    name.println!

The compiler infers answer as I64 and name as &Str. The names are available only after their declarations. The println! calls are evaluated for effects; !-> discards the trailing value and makes main return unit (()), which maps to process exit status 0.

Type annotations

Put an annotation after the name and before =:

main = !->
    answer: I64 = 42
    ratio: F64 = 0.75
    enabled: Bool = true
    answer.println!
    ratio.println!
    enabled.println!

An annotation documents the intended type and gives inference an expected type. It is not a conversion: 0.75 already has a floating-point type in this example.

Observed reassignment behavior

The current compiler permits a later assignment to an existing local without requiring mut:

main = !->
    count = 0
    count = count + 1
    count = count + 1
    count.println!

The first count = 0 establishes the local. The next two assignments target that local and update its value. This is current observed behavior, not a promise that every future mutability rule will be identical.

mut is required where the operation explicitly requests a mutable place. A mutable borrow is the clearest example:

main = !->
    mut value = 1
    reference = &mut value
    *reference = 2
    value.println!

value must be marked mut because &mut value creates a mutable reference. The assignment through *reference changes the original place, so the output is 2.

The same requirement applies to a mutable receiver method. ^@ marks a method that borrows its receiver mutably:

struct Counter
    < value: I64

impl Counter
    ^@increment = amount ->
        self.value = self.value + amount
        return

main = !->
    mut counter = Counter
        value: 3
    counter.increment 4
    counter.value.println!

counter is marked mut because increment needs a mutable receiver. The method changes the field from 3 to 7. Ordinary reassignment and mutable borrowing are separate checks: the former currently works without mut, while the latter requires it.

Reusing a name during a transformation

A parameter can be assigned a new value as a transformation step:

increment_and_print = value ->
    value = value + 1
    value.println!
    value

main = !->
    increment_and_print 4 .println!

The assignment changes the current value of value; it does not introduce a second parameter. Keeping the same name is useful when the old representation is no longer needed, but a new descriptive name is clearer when both values remain meaningful.

Destructuring

A pattern on the left can bind several parts of a tuple:

main = !->
    pair = (10, "ten")
    (number, word) = pair
    number.println!
    word.println!

pair = (10, "ten") creates the tuple. In (number, word) = pair, the pattern binds that tuple’s first element to number and its second element to word. The pattern must have a shape compatible with the value.

Patterns can mark an individual binding as mutable. Here only left is marked mut; the plain reassignment shown would also work without that marker:

main = !->
    (mut left, right) = (1, 2)
    left = left + right
    left.println!

The output is 3, while right remains 2. The matching chapter shows how an enum pattern can both check a variant and bind its payloads.

Updating a field

A field path is also an assignment target. Declare the struct in the same module as the use:

struct Point
    < x: I64
    < y: I64

main = !->
    point = Point
        x: 1
        y: 2
    point.x = 5
    point.x.println!
    point.y.println!

The first assignment constructs point; point.x = 5 updates its existing field. Indexing and mutable receiver calls use the same general idea of selecting a place, but their trait and receiver contracts can impose additional requirements.

Unit-valued functions

Some functions exist for effects and return (). A unit-arrow body uses !->:

log_value: I64 -> ()
log_value = value !->
    value.println!

main = !->
    log_value 9

A !-> body evaluates every statement, including its trailing expression, then discards the trailing value and returns () automatically. Use an ordinary -> body when the trailing value should become the function result.

Common mistakes

• Saying that every assignment requires mut; plain reassignment currently does not.
• Forgetting mut before a value passed to &mut or a ^@ receiver.
• Destructuring a tuple with the wrong number of elements.
• Using a field or enum name without declaring its containing type in the module.

Types and Values

Rock is statically typed: the compiler determines a type for every expression before generating executable code. Local annotations are optional when inference is clear, while signatures make function boundaries explicit.

Primitive values

The primitive families used in ordinary programs are:

This complete program gives each of the commonly encountered literal forms an explicit type:

main = !->
    signed: I64 = -5
    unsigned: U64 = 255
    fraction: F64 = 3.5
    enabled: Bool = true
    letter: Char = 'R'
    text: &Str = "rock"
    signed.println!
    unsigned as I64 .println!
    fraction.println!
    enabled.println!
    letter.println!
    text.println!

Numeric literals receive an expected type from an annotation or a function signature. When no expected type is available, the compiler applies its numeric defaulting rules. Use fixed-width names in public signatures so callers do not have to guess.

Without an expected type, whole-number literals default to I64 and decimal literals default to F64:

show_default_integer: I64 -> ()
show_default_integer = value !->
    value.println!

show_default_float: F64 -> ()
show_default_float = value !->
    value.println!

main = !->
    whole = 42
    decimal = 2.5
    show_default_integer whole
    show_default_float decimal

The unannotated bindings are already defaulted before the calls are checked. The functions make those inferred types explicit to the reader, and the program prints 42 and 2.5. A surrounding annotation can choose another numeric type before defaulting occurs.

Borrowed and owned strings

A string literal is borrowed string data with type &Str. String is a separate prelude type that owns a heap allocation:

main = !->
    borrowed: &Str = "hello"
    owned = String::from borrowed
    borrowed.println!
    owned.println!

The literal can be used while its source is available; String::from copies the bytes into owned storage. Current string helpers operate on bytes, so an index or offset is not automatically a Unicode scalar-value position.

Annotations and signatures

Local annotations use a colon:

main = !->
    enabled: Bool = true
    distance: F64 = 12.5
    enabled.println!
    distance.println!

Function signatures use arrows. The following declaration and definition agree on two F64 parameters and an F64 result:

hypotenuse: F64 -> F64 -> F64
hypotenuse = a, b ->
    a * a + b * b

main = !->
    hypotenuse 3.0, 4.0 .println!

The arrows are read left to right as the function’s parameter types followed by its return type. Calls still use spaces and commas. Despite its name, this hypotenuse body computes the sum of the squares without taking a square root, so the call prints 25, not 5.

Compound type notation

Tuples, arrays, slices, references, pointers, generic applications, and function types use the following spellings. The example declares every local value it mentions:

enum DemoError
    Missing

read_shared: &I64 -> I64
read_shared = value ->
    *value

first_slice: &[I64] -> I64
first_slice = values ->
    values[0]

apply: (I64 -> I64) -> I64 -> I64
apply = function, value ->
    function value

main = !->
    pair: (I64, Bool) = (7, true)
    array: [I64; 4] = [1, 2, 3, 4]
    maybe: Option I64 = Option::Some 5
    result: Result I64, DemoError = Result::Ok 5
    mut number: I64 = 7
    shared: &I64 = &number
    shared_value = read_shared shared
    mutable_reference: &mut I64 = &mut number
    pointer: *I64 = mutable_reference as *I64
    unsafe *pointer = 9
    doubled = apply value -> value * 2, 4
    pair.0.println!
    array[0].println!
    shared_value.println!
    doubled.println!

The tuple has two elements, the fixed array has four I64 elements, and Option and Result are generic prelude enums. [I64] is an unsized slice type, so a borrowed slice is written &[I64]. &T and &mut T are shared and mutable references. *I64 is a raw pointer type; the dereference and assignment in the example are inside unsafe because the compiler cannot prove a raw pointer’s validity.

Generic applications use spaces and commas rather than angle brackets. For example, Result I64, DemoError means Result with success type I64 and error type DemoError.

Casts

Use as for an explicit primitive or pointer conversion:

main = !->
    byte: U8 = 7
    count = byte as I64
    fraction = count as F64
    fraction.println!

The cast binds more tightly than binary operators, so each operand is converted before division:

average: I64 -> I64 -> F64
average = total, count ->
    total as F64 / count as F64

main = !->
    average 9, 2 .println!

A cast is still checked against the supported conversion rules; it is not a general escape from type checking. Pointer casts deserve the same care as raw-pointer dereferences.

Common mistakes

• Writing Str without a reference; unsized string data is used as &Str.
• Using a result type without declaring or importing its failure type. This chapter uses the locally declared DemoError.
• Confusing [I64; 4] with [I64]: the first is fixed-size storage, the second is an unsized slice type.
• Assuming as changes ownership; it changes representation or numeric type, not the ownership contract.

Functions and Calls

Functions are the main unit of behavior in Rock. A declaration has a name, an equals sign, parameters, an arrow, and a body:

add = left, right ->
    left + right

main = !->
    add 2, 3 .println!

The parameter names are introduced before the body is evaluated. The final expression of add is its result.

Signatures

A separate signature documents and checks a function’s interface:

clamp: I64 -> I64 -> I64 -> I64
clamp = value, low, high ->
    if value < low
        low
    else if value > high
        high
    else
        value

main = !->
    clamp 120, 0, 100 .println!

The signature lists three parameter types followed by the return type. The branches of clamp all produce I64, so the definition satisfies the contract.

Calling functions

Arguments follow the function and are separated by commas. Each argument consumes a complete expression, including a nested call with its own comma-separated arguments:

add = left, right ->
    left + right

double = value ->
    value * 2

main = !->
    double add 2, 3 .println!

The inner call owns the arguments 2, 3 and produces 5; the outer call receives that complete result and produces 10. Neither call needs grouping.

An inline callback can follow another argument: for_each 1..=3, number !-> number.println!. At this level, the comma separates call arguments, so the lambda has just the number parameter. Parenthesize a callback with multiple parameters, as in apply (left, right -> left + right), to keep its parameter commas inside the lambda.

Use ! for a zero-argument call:

main = !->
    mut values = Vec::new!
    values.push 10
    length = values.len!
    length.println!

Vec::new! calls an associated function through the type path. values.push 10 passes one argument to a method, while values.len! calls a method with no explicit arguments. The mut binding is required because push uses a mutable receiver.

Associated functions and paths

:: selects an item through a type or module path. Associated functions do not receive an existing instance:

main = !->
    some = Option::Some 5
    text = String::from 42
    some_text = match some
        Option::Some value => text
        Option::None => String::from "missing"
    some_text.println!

Option::Some constructs a prelude enum variant, and String::from constructs an owned string through the From trait’s associated function. A method would instead use a receiver and dot syntax, as some_text.println! does.

Receiver contracts

Methods declare how they use self. A shared receiver uses @; a mutable receiver uses ^@; a consuming receiver uses ~@:

struct Counter
    < value: I64

impl Counter
    @read = -> @value

    ^@add = amount !->
        self.value = self.value + amount

    ~@finish = -> self.value

main = !->
    mut counter = Counter
        value: 4
    current = counter.read!
    counter.add 3
    total = counter.finish!
    current.println!
    total.println!

The first call borrows counter shared. The second needs a mutable receiver, so the binding is marked mut. The final call consumes counter; after it returns, that value is no longer available for another use. The markers are part of the method’s type-level contract, not decoration.

Return values and early exit

With an ordinary -> body, the final expression is returned:

sign = value ->
    if value < 0
    then -1
    else 1

main = !->
    sign -8 .println!
    sign 8 .println!

Use return when a condition should leave the function immediately:

first_nonzero = left, right ->
    if left != 0
    then left
    else right

main = !->
    first_nonzero 3, 9 .println!
    first_nonzero 0, 9 .println!

For (3, 9), the first branch returns 3 and skips right. For (0, 9), execution reaches the final expression and returns 9.

Unit-returning functions

A function whose purpose is an effect can use !->:

greet: &Str -> ()
greet = name !->
    "Hello, " + name .println!

main: () -> ()
main = !->
    greet "Ada"

The trailing expression still runs, but its value is discarded and the function returns () automatically. An ordinary -> body returns its trailing value instead. The signature of this main is () -> (): it takes no arguments and returns unit. The runtime maps unit to process exit status 0, so ordinary programs should use main = !-> without a trailing 0.

Keep -> when main intentionally chooses an integer exit status:

> stdlib::env::args

main: () -> I64
main = ->
    if args!.len! > 1
        0
    else
        "expected at least one argument".println!
        1

This program exits with status 0 when given a user argument and 1 otherwise. Both integers are meaningful results here; !-> would discard the selected status.

Receiver sections

A parenthesized expression beginning with . creates a one-parameter function whose parameter is the receiver. (.println!) is shorthand for value -> value.println!: it returns the method’s result.

Use (!.println!) when the callback should return () instead. It is shorthand for value !-> value.println!, which suits for_each:

main = !->
    for_each 1..=3, (!.println!)
    for_each (Option::Some 7), (!.println!)

This prints 1, 2, 3, and 7, each on its own line. The leading ! discards the section body’s result; the trailing ! calls println with no explicit arguments.

The body can include method arguments and chains. The entire chain runs before its final result is discarded:

main = !->
    suffix = String::from "!"
    for_each (Option::Some (String::from "hello")), (!.concat suffix.clone! .println!)

This prints hello!. As with an explicit lambda, values referenced by the body are captured, and ordinary receiver and ownership rules still apply.

Recursion

A function can call itself after its declaration:

factorial: I64 -> I64
factorial = n ->
    if n <= 1
    then 1
    else n * factorial n - 1

main = !->
    factorial 5 .println!

The recursive call decreases n, so the base case n <= 1 is eventually reached. Rock does not promise tail-call optimization; use a loop when unbounded recursion could exhaust the stack.

Multiline expressions

An operator may continue on a following line at one deeper indentation level:

total: I64 -> I64 -> I64 -> I64
total = base, tax, shipping ->
    base
        + tax
        + shipping

main = !->
    result = total 100, 8, 2
    result.println!

The continuation lines remain one expression. Binding intermediate values is often clearer for complicated calls because each type and ownership boundary gets a name.

A method chain on following lines continues the completed call, including all its inline arguments:

as_option = value -> Option::Some value

main = !->
    as_option 42
        .map (+ 1)
        .unwrap_or 0
        .println!

This prints 43. .map acts on the option returned by as_option 42, not on the integer argument. No parentheses around the call are needed. To chain on an argument instead, group that argument explicitly or put it in a multiline argument block with its own more-indented chain.

Common mistakes

• Omitting commas between call arguments.
• Adding parentheses as if Rock used Rust-style function(arguments) calls.
• Calling a ^@ method through a binding that is not marked mut.
• Using a consuming ~@ receiver and then trying to use the consumed value again.

Control Flow

Rock’s control-flow forms are expressions. They decide which work runs and, except for ordinary loop control, can produce a value for the surrounding expression.

if expressions

The multiline form uses indentation:

category: I64 -> &Str
category = temperature ->
    if temperature < 0
        "freezing"
    else if temperature < 20
        "cool"
    else
        "warm"

main = !->
    category 12 .println!

The condition must be Bool. The compiler evaluates conditions from top to bottom and evaluates only the selected branch. Because category returns &Str, every reachable branch must produce a compatible string type.

For short alternatives, then and else fit on one line:

absolute: I64 -> I64
absolute = value ->
    if value >= 0
    then value 
    else -value

main = !->
    absolute -7 .println!

while

Use while when the number of iterations depends on a condition:

sum_to_ten: I64
sum_to_ten = ->
    index = 0
    total = 0
    while index < 10
        total = total + index
        index = index + 1
    total

main = !->
    sum_to_ten! .println!

The condition is checked before each iteration. The body adds the current index, then increments it. When index reaches 10, the body stops and the final total becomes the function result. Plain reassignment is currently permitted, so neither counter needs mut here.

Rock has no built-in ++ or --; write the state transition explicitly.

for

for pattern in expression iterates over a range, fixed array, or slice. start..end excludes the upper bound, while start..=end includes it:

main = !->
    for number in 0..10
        number.println!

Only ranges with both endpoints are finite loop inputs. Open-ended forms such as start.. remain useful for slicing but are rejected as for iterators.

For an inline action instead of a loop body, the prelude also provides for_each 0..10, (!.println!). The unit-returning receiver section (!.println!) means number !-> number.println!. It visits the same integers in order; the FizzBuzz project uses for_each with a pipeline.

The upper bound is exclusive, so this prints 0 through 9. The pattern is bound for each iteration:

main = !->
    values = [10, 20, 30]
    for value in values
        value.println!

The current iteration facilities are smaller than Rust’s iterator ecosystem. A growable Vec is not directly the same as a fixed array; use its as_slice! view, a library traversal helper, or a while loop when a Vec is the source.

This complete example borrows a vector as a slice and iterates over that fixed view:

main = !->
    mut values = Vec::new!
    values.push 4
    values.push 5
    values.push 6

    view = values.as_slice!
    for value in *view
        value.println!

values owns its growable allocation throughout. as_slice! borrows its initialized elements, and *view supplies the slice value accepted by for. The loop prints 4, 5, and 6; the borrow ends after its final use. Slice views and consuming traversal methods are covered in Arrays, Slices, and Tuples and Strings and Collections.

loop, break, and continue

loop repeats until control leaves it. break leaves the nearest loop, and continue starts its next iteration:

main = !->
    index = 0
    loop
        index = index + 1
        if index == 2
            continue
        if index == 4
            break
        index.println!

The output is 1 and 3: the second iteration uses continue, and the fourth uses break before printing. Expressions after break and continue are accepted syntactically, but ordinary control statements have the strongest end-to-end coverage today.

match

match is the natural control flow for enums and structural patterns:

enum Status
    Ready
    Waiting I64

label: Status -> &Str
label = status ->
    match status
        Status::Ready => "ready"
        Status::Waiting seconds if seconds > 10 => "late"
        Status::Waiting _ => "waiting"

main = !->
    label Status::Ready .println!
    label Status::Waiting 20 .println!

Arms are tested from top to bottom. The first Waiting arm handles values over 10; the second handles the remaining Waiting values. The enums chapter explains payload bindings, guards, and exhaustiveness in detail.

Common mistakes

• Returning incompatible branch types from an if expression.
• Forgetting the update in a while, producing a condition that never changes.
• Expecting start..end to include the upper endpoint; use start..=end when it should be included.
• Putting a broad match pattern before a more specific guarded pattern.
• Using break or continue outside the nearest loop.

Structs

Structs combine named fields into a new type. They are useful when several values form one concept and should travel through a function together.

Declaring a struct

struct Point
    < x: I64
    < y: I64

The declaration introduces Point. Each indented line declares one field. The leading < exports a field from its module; an unmarked field is private to that module.

Generic parameters follow the type name:

struct Pair A, B
    < first: A
    < second: B

Pair A, B is one generic struct declaration. Each field uses one of the declared type parameters.

Constructing a value

Write the type name followed by an indented field block:

struct Point
    < x: I64
    < y: I64

main = !->
    origin = Point
        x: 0
        y: 0
    origin.x.println!
    origin.y.println!

The field labels are part of the constructor syntax. Rock checks that every required field is present and that each expression has the declared type. Initialize every field explicitly; default field expressions are not reliably preserved by the current semantic pipeline.

Generic fields can often be inferred from their constructor expressions:

struct Pair A, B
    < first: A
    < second: B

main = !->
    entry = Pair
        first: "answer"
        second: 42
    entry.first.println!
    entry.second.println!

Here the compiler infers A as &Str and B as I64 from the two field values.

Reading and updating fields

Use dot notation to read a field and to select a field assignment target:

struct Point
    < x: I64
    < y: I64

main = !->
    point = Point
        x: 2
        y: 3
    horizontal = point.x
    point.x = 8
    horizontal.println!
    point.x.println!

horizontal keeps the value read before the update, so the output is 2 followed by 8. Whether a field read copies, borrows, or moves depends on the field type and the surrounding ownership context.

Adding behavior

An inherent impl groups associated functions and methods with a type:

struct Point
    < x: I64
    < y: I64

impl Point
    new: I64 -> I64 -> Point
    new = x, y ->
        Point
            x: x
            y: y

    @length_squared: I64
    @length_squared = -> @x * @x + @y * @y

main = !->
    point = Point::new 3, 4
    value = point.length_squared!
    value.println!

Point::new is an associated function because it is called through the type path. length_squared! is a method because it is called through a value. @ marks a shared receiver, and @x is shorthand for reading the receiver’s field.

Mutable and consuming receiver markers are ^@ and ~@:

struct Counter
    < value: I64

impl Counter
    ^@increment = amount ->
        self.value = self.value + amount
        return

    ~@take = -> self.value

main = !->
    mut counter = Counter
        value: 2
    counter.increment 5
    total = counter.take!
    total.println!

The mut binding is required for increment because its receiver is mutable. take! consumes the value, so counter cannot be used afterward.

Visibility

Export a declaration by placing < before it. Exported fields are independently marked:

< struct PublicPoint
    < x: I64
    < y: I64

main = !->
    point = PublicPoint
        x: 1
        y: 2
    point.x.println!

An explicit export path can also assemble a module facade, but inline exports are easiest to read for a small public type.

Common mistakes

• Omitting a required field or using the wrong field type.
• Treating Point::new and point.new as the same call; the former is associated, the latter is a method-style call.
• Forgetting that @, ^@, and ~@ describe different receiver ownership contracts.
• Calling a mutable receiver method without a mut binding.
• Assuming field defaults are reliable in the current compiler.

Enums and Pattern Matching

An enum is a value that can have one of several variants. Each variant may carry a different payload, but every variant belongs to the same enclosing type.

Declaring and constructing variants

enum Message
    Quit
    Move I64, I64
    Write &Str

main = !->
    stop = Message::Quit
    movement = Message::Move 4, -2
    text = Message::Write "hello"
    stop_text = match stop
        Message::Quit => "quit"
        Message::Move x, y => "move"
        Message::Write value => value
    stop_text.println!
    movement_text = match movement
        Message::Quit => "quit"
        Message::Move x, y => "move"
        Message::Write value => value
    movement_text.println!
    text_text = match text
        Message::Quit => "quit"
        Message::Move x, y => "move"
        Message::Write value => value
    text_text.println!

Message::Quit has no payload, Message::Move has two I64 payloads, and Message::Write has one &Str payload. Construction qualifies the variant with the enum path so the compiler knows which type owns it.

Generic enums use the same declaration form:

enum Choice Left, Right
    First Left
    Second Right

main = !->
    choice: Choice &Str, &Str = Choice::First "left"
    label = match choice
        Choice::First value => value
        Choice::Second value => "right"
    label.println!

The prelude’s Option T and Result T, E are ordinary generic enums of this kind. Option has Some T and None; Result has Ok T and Err E.

Matching variants

A constructor pattern checks the variant and binds each payload:

enum Message
    Quit
    Move I64, I64
    Write &Str

describe: Message -> &Str
describe = message ->
    match message
        Message::Quit => "quit"
        Message::Move x, y => "move"
        Message::Write text => text

main = !->
    describe Message::Move 4, -2 .println!
    describe Message::Write "hello" .println!

For a Move, x and y are introduced only in that arm and have type I64. For a Write, text has type &Str. Every arm returns &Str, which satisfies the function signature.

Use _ when a value is deliberately ignored:

enum Message
    Quit
    Move I64, I64
    Write &Str

is_quit: Message -> Bool
is_quit = message ->
    match message
        Message::Quit => true
        _ => false

main = !->
    is_quit Message::Quit .println!
    is_quit Message::Write "hello" .println!

Qualified patterns such as Message::Quit are clearer than unqualified variant names and avoid collisions when several enums have similarly named variants.

Guards

An if guard runs after the structural pattern succeeds:

classify: I64 -> &Str
classify = value ->
    match value
        number if number < 0 => "negative"
        0 => "zero"
        _ => "positive"

main = !->
    classify -3 .println!
    classify 0 .println!
    classify 8 .println!

The first arm binds number, then checks its guard. If the guard is false, matching continues with the next arm. Guards may use names introduced by their pattern.

Current status: A guard cannot currently consume a non-copy enum payload binding, even when matching a borrowed scrutinee. Match without the guard and put the condition inside the arm instead.

Payload bindings and wildcards

An enum payload can contain several values. A constructor pattern binds those values positionally, while _ ignores a payload that the arm does not need:

enum Packet
    Data I64, &Str
    Empty

describe: Packet -> &Str
describe = packet ->
    match packet
        Packet::Data number, text if number > 0 => text
        Packet::Data _, _ => "nonpositive data"
        Packet::Empty => "empty"

main = !->
    describe Packet::Data 3, "three" .println!
    describe Packet::Data -1, "negative" .println!
    describe Packet::Empty .println!

The first arm binds both payloads and checks the guard. If the guard is false, the second arm matches any Data payload without introducing names. Tuple destructuring assignments are covered in the bindings chapter; the current compiler does not yet execute refutable tuple matches.

Matching through a reference

Matching an owned enum by value can move a non-copy payload into an arm binding. Matching through a shared reference borrows the payload instead:

enum Message
    Quit
    Write &Str

show_message: &Message -> ()
show_message = message ->
    match *message
        Message::Write text => text.println!
        Message::Quit => "quit".println!
    return

main = !->
    message = Message::Write "borrowed payload"
    show_message &message

The *message scrutinee is a borrowed match. The original message remains available after show_message returns because the match did not consume the enum.

Exhaustiveness and arm order

List every variant or finish with a wildcard:

enum Color
    Red
    Green
    Blue

name: Color -> &Str
name = color ->
    match color
        Color::Red => "red"
        Color::Green => "green"
        Color::Blue => "blue"

main = !->
    name Color::Blue .println!

The current compiler does not diagnose every incomplete enum match, so exhaustive source is an important programmer responsibility. Put specific patterns before broad ones; a wildcard first would make later arms unreachable in intent even where the compiler does not report it.

Pattern reference

The forms used in this chapter are:

Common mistakes

• Binding a payload name in one arm and trying to use it in another arm.
• Placing _ before a specific variant pattern.
• Treating a guard as a replacement for the structural pattern; the pattern still has to match first.
• Consuming an owned enum when a shared-reference match would preserve it.
• Adding a variant without updating every exhaustive match.

Arrays, Slices, and Tuples

Rock has three useful shapes for a fixed collection of values:

• [T; N] is an owned, fixed-size array. T is the element type and N is part of the type.
• &[T] is a shared borrowed slice. It views contiguous storage without owning it.
• (A, B) and longer tuples are fixed products. Each position can have a different type.

Vec T is the standard library’s growable owned collection. Choose it when the number of elements changes at run time.

Fixed-Size Arrays

An array literal infers one element type and one length. The following program creates an array, annotates another array explicitly, and prints both values.

main = !->
    scores = [10, 20, 30, 40]
    labeled: [I64; 4] = [10, 20, 30, 40]
    scores.println!
    labeled.println!

The inferred type of scores is [I64; 4]: integer literals are inferred as I64 here, and the literal has four elements. The result is:

[10, 20, 30, 40]
[10, 20, 30, 40]

All elements must have the same type. A cast or an annotation can establish a narrower element type.

main = !->
    bytes: [U8; 3] = [97, 98, 99]
    first = bytes[0] as I64
    first.println!

The type of bytes is [U8; 3], and first is I64 because the as I64 cast is explicit. The output is 97.

Repeat Literals

[value; length] evaluates value once and copies the result into a fixed-size array. The initializer therefore must be a value the compiler knows is copyable.

main = !->
    zeros: [U8; 4] = [0; 4]
    zeros[0].println!
    zeros[3].println!

The output is two lines containing 0. A String is owned and is not copyable, so a repeated owned string is rejected. Use a loop and a fresh String::from call when each element must own a separate allocation.

Indexing and Mutation

Reading values[index] selects the standard library’s Index implementation. Assigning values[index] = replacement selects IndexMut and requires a mutable place.

main = !->
    mut values = [10, 20, 30]
    before = values[1]
    values[1] = 99
    after = values[1]
    before.println!
    after.println!

before and after are both inferred as I64; the output is 20 followed by 99. The array remains owned by values before and after the indexing operations. An index below zero or at least the array length terminates the program with an index out of bounds message.

Nested arrays use the same rule at each position.

set_second: &mut [I64] -> ()
set_second = row !->
    row[1] = 7

first_row: &[I64] -> I64
first_row = row -> row[1]

main = !->
    mut row = [1, 0]
    second_row = [0, 1]
    set_second &mut row
    first_row &row .println!
    first_row &second_row .println!
    matrix = [row, second_row]

The output is 7 and 1. Nested fixed-array literals are valid, but the current implementation does not support chained indexing directly on an inner fixed-array value; borrow a row as a slice before indexing when a program needs that operation.

Slices

[T] is a dynamically sized view, not a standalone value type for fields or parameters. In ordinary safe code, write it behind a reference: &[T] for shared access or &mut [T] for exclusive mutable access.

Borrowing a fixed array as a slice does not move the array. The slice points at the same storage, so the owner remains responsible for the array.

sum_three: &[I64] -> I64
sum_three = values ->
    values[0] + values[1] + values[2]

main = !->
    values = [2, 4, 6]
    total = sum_three &values
    total.println!
    values[0].println!

Before the call, values owns [2, 4, 6]. During the call, &values is coerced to &[I64]; sum_three borrows it and does not own it. After the call, values is still available. The output is 12 and 2.

A fixed array value is not coerced to a slice value by itself. Borrow it explicitly at the call site. This keeps the lifetime of the view tied to the array and makes ownership visible.

Mutable slices let a function update the owner’s storage without taking ownership of the array.

write_middle: &mut [I64] -> ()
write_middle = values !->
    values[1] = 42

main = !->
    mut values = [7, 8, 9]
    write_middle &mut values
    values[1].println!

Before the call, values is mutable and owned by main. During the call, &mut values gives write_middle the only active mutable access. After the call, the mutable borrow ends at its last use and values[1] prints 42.

Slices support the same indexing traits as arrays. A slice does not resize, allocate, or own the backing storage; use Vec T for those operations.

Range Slicing

Use a range to borrow a prefix, suffix, or middle portion of an array or slice. Range indexing selects a view through Index or IndexMut; the surrounding & or &mut makes the borrow explicit. No elements are copied or allocated.

> stdlib::slice::slice_len

inspect: &[I64] -> ()
inspect = values !->
    slice_len values .println!
    values[0].println!

main = !->
    values = [10, 20, 30, 40]
    inspect &values[..2]
    inspect &values[1..]
    inspect &values[1..=2]

The example prints lengths and first values for [10, 20], [20, 30, 40], and [20, 30]. slice_len returns an I64 element count without requiring a compiler intrinsic.

For a four-element sequence, the six range forms select these positions:

Ranges are first-class values, so a program can store one before indexing:

main = !->
    values = [10, 20, 30, 40]
    middle = 1..3
    view = &values[middle]
    view[0].println!

These values have the standard library type Range, whose endpoints are I64. Creating a range does not check it against any collection; indexing does.

Bounds and Empty Views

An exclusive range must satisfy 0 <= start <= end <= length. Equal endpoints produce an empty view, including length..length at the end of a sequence. An inclusive endpoint must identify an actual element, so it must be less than the length. ..=length is not a spelling for the whole sequence; use .. instead.

> stdlib::slice::slice_len

main = !->
    values = [10, 20, 30, 40]
    empty = &values[4..4]
    slice_len empty .println!

The output is 0. Do not index element zero of an empty slice. Negative, reversed, or out-of-bounds ranges terminate the process with range out of bounds; slicing does not clamp endpoints or return an Option. Validate a count from untrusted input before constructing its view. A byte count returned by a successful standard-library read already fits the supplied buffer, which makes &buffer[..count] useful for safe I/O.

Mutable Subslices

A mutable range view updates the original storage:

update_middle: &mut [I64] -> ()
update_middle = values !->
    mut middle = &mut values[1..3]
    middle[0] = 77

main = !->
    mut values = [10, 20, 30, 40]
    update_middle &mut values
    values[1].println!
    values[2].println!

The output is 77 and 30. Index zero in middle is index one in values. Shared and mutable views obey ordinary borrowing rules: a view cannot outlive its owner, and conflicting access is rejected while an earlier borrow remains live. Do not assume the borrow checker can prove that two independently written ranges are disjoint.

Range syntax also supports bounded integer loops:

main = !->
    mut total = 0
    for value in 1..=3
        total = total + value
    total.println!

This prints 6; 1..3 would visit only 1 and 2. The current range-loop form requires both endpoints directly in the loop expression; open-ended slicing syntax is not an unbounded iterator API.

Growable Vectors

Vec T owns a heap allocation and can grow with push. Its receiver is mutable for mutation, and len! borrows it to inspect the current length.

main = !->
    mut values = Vec::new!
    values.push 10
    values.push 20
    values.push 30
    values.len!.println!
    values[1].println!

The output is 3 and 20. values owns all three elements before and after push; indexing borrows the selected element for the expression. Vec::get is the checked, non-panicking alternative when an index may be absent.

Vec T also supports the native range forms. A shared range produces &[T], while a mutable range produces &mut [T]; neither operation copies the selected elements.

> stdlib::slice::slice_len

main = !->
    mut values = Vec::new!
    values.push 10
    values.push 20
    values.push 30
    tail = &values[1..]
    slice_len tail .println!
    tail[0].println!

This prints 2 and 20. Do not resize or move the vector while a borrowed view is still in use. For a single optional element rather than a range, use get:

main = !->
    mut values = Vec::new!
    values.push 10
    match values.get 4
        Option::Some value => *value .println!
        Option::None => -1 .println!

The output is -1. get returns Option &I64, so the Some binding is a shared reference and *value reads the integer without moving it.

Tuples

A tuple stores a fixed number of values in a fixed order. Its type records every component.

main = !->
    entry = (7, true, "rock")
    entry.0.println!
    entry.1.println!
    entry.2.println!

The annotation specifies component types I64, Bool, and &Str; the output is 7, true, and rock. .0, .1, and .2 are tuple projections, not array indexes, so their positions are checked statically.

Functions can return tuples and callers can project the result.

swap: I64 -> I64 -> (I64, I64)
swap = left, right -> (right, left)

main = !->
    pair = swap 10, 20
    pair.0.println!
    pair.1.println!

swap returns (20, 10), so the output is 20 and 10. A parenthesized expression such as (7) is grouping; a one-element tuple is not part of the current tuple syntax.

Choosing a Type

Use [T; N] when the length is fixed and the data should be stored inline in the owning value. Use &[T] or &mut [T] when a function needs a temporary view. Use Vec T when the collection owns a variable number of elements. Use (A, B) when the positions have different meanings or types.

The current slice limitations are deliberate and important: a bare [T] is rejected in ordinary struct fields and function parameters, and a fixed array must be borrowed before it can satisfy a slice parameter. The current Vec API is the standard growable sequence; a slice cannot be resized.

Ownership and Moves

Ownership answers one question for every value: which binding is responsible for using and eventually releasing it? Rock uses that information to make moves, borrows, and cleanup explicit without a garbage collector.

Copyable Values

The compiler knows that primitive values such as I64 and Bool can be copied. Assignment creates another independent value, so the original remains usable.

main = !->
    first = 42
    second = first
    first.println!
    second.println!

Both bindings contain 42, and the output is two lines containing 42. first and second do not share an owned allocation.

Rock does not expose a user-defined Copy trait. Repeat-array literals and other operations that duplicate a value use compiler-known copy facts. Do not assume that a generic T is copyable merely because a concrete call later happens to use I64.

Moving Owned Values

Heap-backed values such as String and Vec T own resources. Passing one by value transfers responsibility to the parameter or destination. The source binding cannot be used again after the move.

string_length: String -> I64
string_length = text -> text.len!

main = !->
    name = String::from "Rock"
    length = string_length name
    length.println!

Before the call, name owns the string allocation. The call moves that String into string_length, whose parameter owns it while the function runs. After the call, name is moved and is not referenced again; the returned length is an independent I64. The output is 4.

The common mistake is to use the source after the call. If the caller needs the value afterward, pass a reference or clone it explicitly rather than pretending the move did not happen.

Borrowing Instead of Moving

A reference lets a function inspect an owned value without becoming its owner. Put the reference in the signature so callers can see the ownership contract.

measure: &String -> I64
measure = text -> text.len!

main = !->
    name = String::from "Rock"
    length = measure &name
    length.println!
    name.println!

Before the call, name owns the allocation. &name creates a shared borrow, and measure reads through it. After the borrow’s last use, name is still the owner and can be printed. The output is 4 and Rock.

Use a borrowed parameter when the operation only observes data. Use a by-value parameter when the operation must forward or consume the resource.

Consuming Standard-Library Operations

Many transformations consume an owned receiver. Option::map can move an owned payload into its callback, and Vec::map can move every owned element into a new vector.

string_length: String -> I64
string_length = text -> text.len!

main = !->
    mut words = Vec::new!
    words.push String::from "a"
    words.push String::from "long"
    lengths = words.map string_length
    lengths[0].println!
    lengths[1].println!

Before map, words owns both strings. words.map string_length consumes words; each String moves into string_length, and the new lengths owns the two I64 results. The output is 1 and 4. The old words binding is not used afterward.

Receiver Ownership

Methods state the same contract with a marker:

• @method borrows the receiver shared.
• ^@method borrows the receiver mutably.
• ~@method moves the receiver.

struct Counter
    < value: I64

impl Counter
    @read: I64
    @read = -> @value

    ^@set: I64 -> ()
    ^@set = value !->
        self.value = value

    ~@take: I64
    ~@take = -> self.value

main = !->
    mut counter = Counter
        value: 1
    counter.read!.println!
    counter.set 9
    counter.read!.println!
    counter.take!.println!

read! leaves counter available because it borrows. set 9 requires a mutable binding and changes the owned value in place. take! consumes counter; the final I64 is returned, and counter is not used again. The output is 1, 9, and 9.

Explicit Cloning

Clone requests a second owned value. It is different from compiler-known copying and may allocate or recursively clone fields.

main = !->
    first = String::from "owned"
    second = first.clone!
    first.println!
    second.println!

first.clone! borrows first, allocates a second string, and returns it. Both bindings remain usable, so the output contains owned twice. Clone only when two owners are actually required; a shared borrow is cheaper when the second owner is unnecessary.

Scope and Cleanup

An owned value is cleaned up when its live scope ends. String, Vec, and Box use standard-library ownership and Drop implementations for this purpose.

make_message: () -> String
make_message = -> String::from "temporary"

main = !->
    make_message!.len!.println!

make_message! returns ownership of a String to main. main owns it until the function ends, after printing 9. There is no implicit exception unwinding in Rock; errors are ordinary Result values and cleanup follows explicit control flow.

The Drop trait gives an owned type a cleanup method. Cleanup is automatic at scope end; calling the method explicitly is not required.

struct Resource
    < id: I64

impl Drop for Resource
    ~@drop = -> return

main = !->
    resource = Resource
        id: 7
    resource.id.println!

resource owns a Resource until main ends, when its Drop implementation runs. The output is 7.

Partial Moves and Current Limits

The checker tracks moves through fields, tuple elements, enum payloads, branches, and loops. Moving one non-copy field can leave the rest of an aggregate initialized, but direct cleanup types are intentionally conservative: moving part of a value that owns cleanup may be rejected rather than risk double cleanup. Destructure deliberately or borrow a field when the whole owner must remain usable.

Here, moving first does not prevent using the independent second field:

struct Names
    < first: String
    < second: String

take_length: String -> I64
take_length = text -> text.len!

main = !->
    names = Names
        first: String::from "Ada"
        second: String::from "Lovelace"

    take_length names.first .println!
    names.second.len! .println!

take_length names.first moves only the first String. The second field remains initialized and prints length 8; trying to use names.first or move the complete names value afterward would be rejected. If Names itself implemented Drop, moving out one field could be rejected because cleanup would otherwise receive a partially initialized owner.

The practical rules are simple: after a by-value call, consider the argument moved; after a shared call, the owner remains available; after a mutable or consuming method, follow its marker; and use clone! when independent ownership is required.

References and Borrowing

A reference is a temporary access path to an existing value. &T is shared, while &mut T is exclusive and mutable. References never own the storage they point to.

Shared References

Create a shared borrow with &. Any number of compatible shared borrows can coexist, and a shared receiver cannot mutate or consume the referent while that borrow is live.

length: &String -> I64
length = text -> text.len!

main = !->
    name = String::from "Rock"
    first = length &name
    second = length &name
    first.println!
    second.println!
    name.println!

Before either call, name owns the allocation. Each &name creates a shared view for one call and length only reads it. After both calls, name is still available; the output is 4, 4, and Rock.

A shared reference can be copied as a reference, but every alias keeps the borrow live until its last use.

main = !->
    mut number = 1
    first = &number
    second = first
    *first .println!
    *second .println!
    number = 2
    number.println!

The aliases are shared references to the same number. Once both aliases are last used, the borrow ends and the owner can be assigned. The output is 1, 1, and 2.

Mutable References

Create an exclusive borrow with &mut. The owner binding must be mutable, and no shared or second mutable borrow may overlap it.

increment: &mut I64 -> ()
increment = value !->
    *value = *value + 1

main = !->
    mut count = 4
    increment &mut count
    count.println!

Before the call, count owns 4. During the call, increment has the only mutable access and writes 5 through *value. After the call, the borrow ends and count remains the owner. The output is 5.

The common mistakes are taking &mut from an immutable binding, assigning to the owner while the mutable reference is still used, or creating a second overlapping mutable reference. The compiler reports these as mutability or borrow conflicts.

Dereferencing

*reference accesses the referenced place. A dereference in a value position reads the referent; a dereference on the left side of assignment writes it.

read: &I64 -> I64
read = value -> *value

main = !->
    number = 17
    borrowed = &number
    result = read borrowed
    result.println!

borrowed has type &I64, while result has type I64. The call passes borrowed to read, whose *value expression copies the integer from number because I64 is copyable. The output is 17.

Method lookup performs receiver borrowing and dereferencing for both inherent methods and trait methods. Write the simplest receiver expression first; do not add &* repeatedly unless the signature requires an explicit reference.

A shared receiver method demonstrates automatic borrowing:

struct Counter
    < value: I64

impl Counter
    @read: I64
    @read = -> @value

main = !->
    counter = Counter
        value: 12
    result = counter.read!
    result.println!

read requires a shared receiver, but the call is written counter.read!, not (&counter).read!; method selection creates the shared borrow. Wrapper types that implement Deref use the same selection process to expose target methods. Keep an explicit &value in ordinary function calls, because automatic receiver borrowing applies to method selection rather than every argument position.

Reborrowing

A mutable reference can be temporarily reborrowed. The shorter reborrow must finish before the original mutable reference is used again.

show_and_set: &mut I64 -> ()
show_and_set = value !->
    *value = 2
    *value .println!

main = !->
    mut value = 1
    original = &mut value
    temporary = &mut *original
    show_and_set temporary

original first owns the exclusive access. temporary temporarily borrows through it and is moved into show_and_set, so neither the original reference nor the owner is used while the reborrow is active. The output is 2. Current borrow checking is conservative about using the original reference or owner while a named reborrow remains live; pass the reborrow to a short operation and end it before any later owner use.

Borrow Lifetimes

A reference cannot outlive its referent. Rock ends a borrow after its final use when control flow proves that the access is finished; it does not require every borrow to last until the textual end of the block.

main = !->
    mut number = 1
    view = &number
    *view .println!
    number = 2
    number.println!

The shared borrow is last used by the first print. The assignment is therefore valid, and the output is 1 followed by 2.

References to call temporaries are not valid because the temporary is destroyed before the reference could be safely used. Return a value, borrow a caller-owned value, or bind an owned result before taking a reference.

References in Patterns

Matching through a shared reference borrows enum payloads rather than moving them. This lets a caller inspect an owned Option String repeatedly.

show_option: &Option String -> I64
show_option = option ->
    match *option
        Option::Some text => text.len!
        Option::None => 0

main = !->
    value = Option::Some String::from "hello"
    first = show_option &value
    second = show_option &value
    first.println!
    second.println!

The output is 5 and 5. In each Some arm, text is a shared reference to the payload, so the String remains owned by value.

Receiver Modes

Method receiver markers are reference contracts as well as ownership contracts.

struct Counter
    < value: I64

impl Counter
    @get: I64
    @get = -> @value

    ^@increment: ()
    ^@increment = !->
        self.value = self.value + 1

    ~@finish: I64
    ~@finish = -> self.value

main = !->
    mut counter = Counter
        value: 1
    counter.get!.println!
    counter.increment!
    counter.get!.println!
    counter.finish!.println!

get! creates shared access, increment! creates exclusive mutable access, and finish! moves the receiver. The output is 1, 2, and 2; the binding counter is unavailable after finish!.

Current Limitations

Bare [T] and bare Str are not ordinary standalone parameter or field types; use &[T], &mut [T], or &Str. Mutable references are not copyable. References to temporaries are rejected, and a shared borrow of a non-copy owned value cannot be dereferenced to move that value out. Raw pointers are a separate unsafe interface and are not needed for ordinary borrowing.

Generics

Generics let one declaration work for many concrete types while preserving static checking. A generic declaration is checked once, then specialized for the concrete types used by the program.

Generic Data Types

Type parameters follow the declaration name. A generic struct can store a value of its parameter type, and a generic enum can carry one of several parameter types.

struct Wrapper T
    < value: T

enum Choice A, B
    First A
    Second B

main = !->
    number = Wrapper
        value: 7
    text: Choice I64, &Str = Choice::Second "rock"
    number.value.println!
    match text
        Choice::First value => value.println!
        Choice::Second value => value.println!

The concrete type of number is Wrapper I64, so number.value is I64. The concrete type of text is Choice I64, &Str, and its selected payload is &Str. The annotation on text is needed because Second provides no value from which to infer the First payload type. The output is 7 and rock.

Generic arguments are written with spaces and commas, not angle brackets: Wrapper I64 and Choice I64, &Str.

Generic Functions

An unconstrained type parameter can be passed through a function without the function knowing its concrete representation.

identity: T -> T
identity = value -> value

main = !->
    number = identity 42
    flag = identity true
    number.println!
    flag.println!

At the first call, inference chooses T = I64; at the second, it chooses T = Bool. The output is 42 and true. The signature says that the result has exactly the same type as the argument.

Trait Bounds

A generic body may only use operations promised by its bounds. Put bounds in a where clause.

struct Box T
    < value: T

same_box: Box T -> Box T -> Bool where T: Eq
same_box = left, right -> left.value == right.value

main = !->
    left = Box
        value: 7
    left_again = Box
        value: 7
    equal = Box
        value: 7
    different = Box
        value: 9
    same_box left, equal .println!
    same_box left_again, different .println!

The body uses ==, so T: Eq is required. In both calls inference chooses T = I64; the output is true and false. Without the bound, the generic body would have no promise that == exists.

The same rule applies to named methods. Here T: Show supplies show!, and the concrete argument type must implement that capability.

show_value: &T -> String where T: Show
show_value = value -> value.show!

main = !->
    number = 42
    show_value &number .println!

Here T is inferred as I64; I64 implements Show, and show_value returns a String containing 42.

Generic Implementations

An implementation can itself contain type parameters. This array implementation is selected only for arrays of length three, then its T is specialized from the receiver.

trait EchoArray
    @echo: I64 -> I64

impl EchoArray for [T; 3]
    @echo = value -> value

main = !->
    values = [7, 8, 9]
    values.echo 7 .println!

The receiver establishes T = I64 and matches the required array length of three. The trait declares the argument and result of echo as I64 independently of T; the method returns its argument, so the output is 7. A generic implementation is not a promise that every possible instantiation works; its own bounds and receiver shape still have to match.

Type Aliases

An alias gives an existing type another spelling. It does not create a new nominal type or change ownership.

type Number = I64

identity: Number -> Number
identity = value -> value

main = !->
    identity 42 .println!

Number is an alias for I64, so identity accepts and returns I64. The output is 42. Use a struct or enum when a distinct type is required.

Associated Types

An associated type is chosen by each trait implementation. Callers can use Self::Output in a trait signature without repeating an output type as another generic parameter.

trait Projector
    type Output
    @project: Self::Output -> Self::Output

struct Identity

impl Projector for Identity
    type Output = I64
    @project = value -> value

main = !->
    identity = Identity
    identity.project 13 .println!

The implementation fixes Identity::Output to I64, so the argument and result of project are both I64. The output is 13. An implementation must define every associated type required by its trait.

Constructor Parameters

Ordinary generics abstract over complete types such as I64 or Option I64. Higher-kinded generics abstract over constructors such as Option or Result _, I64; the exact tested syntax is F _ in a where bound. Higher-Kinded Types begins with complete Option, Result, and Vec programs using that syntax. This chapter intentionally does not introduce a second spelling before those examples.

Common Mistakes and Limits

Do not call a method or operator in a generic body without a bound that supplies it. Do not leave a Result error parameter implicit: write Result I64, I64 or another concrete error type. Generic aliases and associated types preserve the underlying ownership rules; they do not make an owned value copyable or a borrowed value owned.

Traits and Methods

A trait names a capability. A type implements the trait by providing the required methods and associated types, and generic callers can require that capability with a bound.

Declaring and Implementing a Trait

This trait says that an implementor can calculate an area through a shared receiver. Two unrelated structs provide different implementations.

struct Circle
    < radius: I64

struct Rectangle
    < width: I64
    < height: I64

trait Shape
    @area: I64

impl Shape for Circle
    @area = -> @radius * @radius * 3

impl Shape for Rectangle
    @area = -> @width * @height

main = !->
    circle = Circle
        radius: 5
    rectangle = Rectangle
        width: 4
        height: 6
    circle.area!.println!
    rectangle.area!.println!

circle.area! selects the Circle implementation and returns 75; rectangle.area! selects the Rectangle implementation and returns 24. The output is 75 and 24.

The @ marker is part of the method contract. The trait signature omits an explicit self parameter because the receiver is implicit; the body can use @radius, @width, or self.

Default Methods

A trait may provide a method body. An implementation can override one method and inherit the others.

struct Dog
    < name: I64

struct Cat
    < name: I64

trait Animal
    @speak: I64
    @speak = -> 0
    @legs: I64
    @legs = -> 4

impl Animal for Dog
    @speak = -> 1

impl Animal for Cat
    @speak = -> 2

main = !->
    dog = Dog
        name: 10
    cat = Cat
        name: 20
    dog.speak!.println!
    cat.speak!.println!
    dog.legs!.println!
    cat.legs!.println!

Dog and Cat override speak! but inherit legs!. The output is 1, 2, 4, and 4.

Inherent Implementations

An inherent implementation adds methods directly to a type without defining a trait. Associated functions have no receiver and are called through the type path.

struct Point
    < x: I64
    < y: I64

impl Point
    new: I64 -> I64 -> Point
    new = x, y ->
        Point
            x: x
            y: y

    @sum: I64
    @sum = -> @x + @y

main = !->
    point = Point::new 3, 4
    point.sum!.println!

Point::new is an associated function and returns a Point; sum! is a shared method. The output is 7.

Receiver Ownership

The receiver marker also controls ownership.

struct Counter
    < value: I64

impl Counter
    @read: I64
    @read = -> @value

    ^@set: I64 -> ()
    ^@set = value !->
        self.value = value

    ~@take: I64
    ~@take = -> self.value

main = !->
    mut counter = Counter
        value: 1
    counter.read!.println!
    counter.set 9
    counter.read!.println!
    counter.take!.println!

@read shared-borrows, ^@set requires a mutable binding and writes in place, and ~@take consumes the receiver. The output is 1, 9, and 9; counter cannot be used after take!.

Associated Types

An associated type lets an implementation choose one output type for a trait.

trait Projector
    type Output
    @project: Self::Output -> Self::Output

struct Identity

impl Projector for Identity
    type Output = I64
    @project = value -> value

main = !->
    identity = Identity
    identity.project 13 .println!

The implementation defines Identity::Output = I64, so project accepts and returns I64. Omitting the required associated type is a compile-time error.

Generic Trait Bounds

A generic function can use a trait method or operator when its signature names the bound.

struct Box T
    < value: T

same_box: Box T -> Box T -> Bool where T: Eq
same_box = left, right -> left.value == right.value

main = !->
    first = Box
        value: 7
    second = Box
        value: 7
    same_box first, second .println!

The call specializes T to I64, and the Eq implementation for I64 supplies ==. The output is true. A bound is checked at the call site as well as in the generic body.

Focused Standard Traits

The standard library uses the same mechanism for Show and Clone. This type implements both: show! creates display text, while clone! creates independent owned data.

struct Label
    < text: String

impl Show for Label
    @show: String
    @show = -> @text.clone!

impl Clone for Label
    @clone: Label
    @clone = ->
        Label
            text: @text.clone!

main = !->
    original = Label
        text: String::from "Rock"
    copy = original.clone!
    original.println!
    copy.println!

The output is Rock twice. Cloning the String gives each Label its own allocation, while Show borrows the receiver. Other focused standard traits follow the same selection model: Arrays, Slices, and Tuples demonstrates Index and IndexMut, and Functions as Values demonstrates Fn, FnMut, and FnOnce with complete callbacks. Keep a trait small; combine bounds only when one operation genuinely needs several capabilities.

Coherence and Current Limits

Rock requires one unambiguous applicable implementation for a trait call. The following exhaustive program is intentionally rejected because Tag has two implementations of the same trait:

trait Named
    @name: &Str

struct Tag

impl Named for Tag
    @name = -> "first"

impl Named for Tag
    @name = -> "second"

main = !->
    tag = Tag
    tag.name!.println!

Rock does not choose first or second by declaration order; remove one implementation to make the call coherent. Missing associated type definitions are rejected for the same reason that missing methods are rejected: an implementation must satisfy its complete trait contract. Trait selection also preserves ownership, so it cannot turn a borrowed receiver into an owned value or make an owned value copyable.

Operators

Rock does not assign permanent meanings to punctuation. The current source program and its explicit dependencies declare operator precedence and provide the function or trait implementation selected for the operand types. The standard library supplies familiar arithmetic, comparison, Boolean, and functional operators through the prelude.

Standard Operators

With the standard library prelude, ordinary operators are selected from the operand types.

main = !->
    sum = 2 + 3
    same = sum == 5
    low = 2
    high = 8
    inside = sum >= low && sum <= high
    sum.println!
    same.println!
    inside.println!

The inferred types of sum, same, and inside are I64, Bool, and Bool; the output is 5, true, and true. Operand and operator constraints determine these types without local annotations. If no implementation matches the operand types, compilation fails instead of applying a hidden built-in conversion.

Declaring Precedence and Defining a Function

An infix declaration gives a symbol a precedence from 0 through 255. The function with the same symbol supplies its meaning.

infix 9 %%

%%: I64 -> I64 -> I64
%% = left, right -> left - right

main = !->
    result = 40 %% 2
    result.println!

The declaration makes %% parse as an infix operator at precedence 9; the function returns left - right, so the output is 38. A dependency can transport its declarations, which is why two dependencies should not assign conflicting precedence to the same symbol.

Trait-Selected Operators

An operator can be a trait method. This example defines a new operator and selects an implementation from the left operand’s type and the right operand’s type.

infix 9 %%

struct Boxed
    < value: I64

trait Combine Rhs
    @%%: Rhs -> I64

impl Combine Boxed for Boxed
    @%% = other -> @value + other.value

main = !->
    left = Boxed
        value: 40
    right = Boxed
        value: 2
    result = left %% right
    result.println!

The receiver is Boxed, the right operand is Boxed, and the selected implementation returns 42. The compiler does not need to know a special meaning for %%; the trait declaration and implementation provide it.

Operators on Borrowed Values

For a method-backed binary operator, the left operand is its receiver. The same receiver borrowing and dereferencing used by ordinary method calls applies during operator lookup.

main = !->
    number = 4
    borrowed = &number
    incremented = borrowed + 1
    even = borrowed % 2 == 0
    incremented.println!
    even.println!
    number.println!

The output is 5, true, and 4. Although borrowed has type &I64, method lookup can select the I64 implementations of + and %. Those implementations use shared receivers (@) and read the integer through self, so the caller does not need to write *borrowed. The original integer remains available.

This also lets operator sections such as (+ 1) work as callbacks receiving &I64, as shown in the collection transformations. Receiver adjustment does not make references and values interchangeable in every argument position; the selected operator’s signature still determines its requirements.

Unary Operators

Prefix operators use the same type-directed model. The standard library provides negation for numeric values and logical not for booleans where an implementation exists.

main = !->
    value = 7
    condition = true
    negative = -value
    opposite = !condition
    negative.println!
    opposite.println!

The output is -7 and false. User-defined types can also implement the Neg and Not traits with @- and @! methods and an associated Output type.

Operator Sections

Parenthesized operator sections create functions. (+ 2) waits for its left operand and then adds 2.

increment: I64 -> I64
increment = (+ 2)

main = !->
    increment 5 .println!

increment has type I64 -> I64, and the output is 7. Use an explicit lambda when the missing side or ownership is not obvious.

Functional Operators

The prelude also exports standard-library operators for function application through a value, mapping, binding, and fallback. The function signatures and values determine the concrete carrier types.

increment: I64 -> I64
increment = value -> value + 1

keep_even: I64 -> Option I64
keep_even = value ->
    if value % 2 == 0
    then Option::Some value
    else Option::None

main = !->
    mapped = Option::Some 4 <&> increment
    bound = Option::Some 4 >>= keep_even
    fallback = Option::None <|> Option::Some 9
    mapped.unwrap_or 0 .println!
    bound.unwrap_or 0 .println!
    fallback.unwrap_or 0 .println!

The output is 5, 4, and 9. <&> maps a function over Option, >>= calls a function that returns another Option, <|> chooses the first present value, and |> passes a value to a function. These meanings are standard-library definitions, not compiler fallbacks.

Parsing and Common Mistakes

Function application has precedence 8. Operators above that precedence become part of the final argument, while operators at or below it operate on the call result. This keeps arithmetic arguments concise and functional composition outside the call.

double: I64 -> I64
double = value -> value * 2

main = !->
    doubled_sum = double 2 + 2
    adjusted_result = (double 2) + 2
    doubled_sum .println!
    adjusted_result .println!
    Option::Some 2 <&> (+ 2) .unwrap_or 0 .println!

+ has precedence 9, so double 2 + 2 means double (2 + 2) and prints 8. Parentheses make (double 2) + 2 apply addition to the call result and print 6. <&> has precedence 8, so it operates on Option::Some 2; the spaced dots then apply unwrap_or and println! to each complete result. A tight dot such as value.method! still binds directly to value.

An adjacent & starts a borrowed call argument: read &value means read (&value), whereas a spaced & can be an infix operator. A trailing ? after that argument applies to the whole call: read &value? means (read (&value))?, not read (&(value?)). See the complete borrowed-call example. Parenthesize an argument explicitly when propagation should happen inside it.

Operators are library design. Use a symbol for a compact operation with a stable, documented reading direction; use a named function for a domain action whose meaning is not obvious from punctuation.

Functions as Values

Functions and lambdas are values. They can be bound to names, passed as arguments, returned from other functions, and stored in generic containers. Their function type lists parameter types followed by the return type.

Lambdas

A lambda has parameters, an arrow, and a body. The following function has the explicit signature I64 -> I64.

double: I64 -> I64
double = value -> value * 2

main = !->
    double 5 .println!

The output is 10. double is a named function value; the expression after the equals sign is still a lambda-shaped function body.

Pass a lambda directly when its purpose is local.

main = !->
    mut values = Vec::new!
    values.push 1
    values.push 2
    mapped = values.map value -> value + 10
    mapped[0].println!
    mapped[1].println!