writing-roc-lang

name: writing-roc-lang
description: Writes Roc code with strong static types, helpful compiler errors, and functional programming. Use when the user wants Roc code, mentions Roc, functional programming with types, or needs .roc files. Covers both full applications and one-off Roc scripts with shebangs.
license: AGPL-3.0-or-later
metadata:
author: Amolith [email protected]

Write code in Roc, a functional language with strong types, helpful compiler errors, and no runtime. Compiles to standalone binaries.

Reference documentation

• Language guide: See llms.md for comprehensive tutorial
• Standard library: See builtins-llms.md for all builtin modules
• CLI scripting: See scripting.md for executable scripts with shebang

Language fundamentals

Functions

# Lambda syntax
add = |a, b| a + b

# Multi-line with indentation
process = |text|
    trimmed = Str.trim(text)
    Str.to_upper(trimmed)

# Type signatures (optional but helpful)
greet : Str -> Str
greet = |name| "Hello, ${name}!"

Pattern matching

when value is
    Ok(content) -> process(content)
    Err(NotFound) -> "not found"
    Err(_) -> "other error"

Records and tags

# Records
user = { name: "Alice", age: 30 }
user.name  # Access field

# Tags (algebraic data types)
Color : [Red, Green, Blue, Custom Str]
my_color = Custom("purple")

Error handling

Roc uses Result types, not exceptions. Use ? to short-circuit:

main! = |_args|
    content = File.read_utf8!(path)?  # Returns early if error
    Stdout.line!("Success!")

Or explicit pattern matching:

when result is
    Ok(content) -> Stdout.line!("Read: ${content}")
    Err(err) -> Err(Exit(1, "Failed: ${Inspect.to_str(err)}"))

Common patterns

Working with lists

numbers = [1, 2, 3, 4, 5]
evens = List.keep_if(numbers, |n| n % 2 == 0)
doubled = List.map(evens, |n| n * 2)
sum = List.walk(doubled, 0, Num.add)

String manipulation

text = Str.concat("Hello", " World")
words = Str.split(text, " ")
trimmed = Str.trim("  spaces  ")
replaced = Str.replace_each(text, "World", "Roc")

Code quality tools

roc format script.roc  # Auto-format code
roc check script.roc   # Type check without running
roc test script.roc    # Run expect expressions

Tests with expect

add = |a, b| a + b

expect add(2, 3) == 5
expect add(0, 0) == 0

Key concepts

• Immutable: All values immutable; operations return new values
• Type inference: Types inferred but signatures help clarity
• Helpful errors: Compiler provides detailed, friendly messages
• No exceptions: Use Result for errors; no try/catch
• No runtime: Compiled binaries are standalone
• Functional: Functions are first-class; use |param| expression syntax

Maturity caveat

Roc is pre-1.0. Core features work well, but expect:
- Breaking changes between versions
- Smaller community/fewer examples
- Excellent for learning; use production caution