1---
  2name: writing-roc-lang
  3description: 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.
  4license: GPL-3.0-or-later
  5metadata:
  6  author: Amolith <amolith@secluded.site>
  7---
  8
  9Write code in Roc, a functional language with strong types, helpful compiler errors, and no runtime. Compiles to standalone binaries.
 10
 11## Reference documentation
 12
 13- **Language guide**: See [llms.md](references/llms.md) for comprehensive tutorial
 14- **Standard library**: See [builtins-llms.md](references/builtins-llms.md) for all builtin modules
 15- **CLI scripting**: See [scripting.md](references/scripting.md) for executable scripts with shebang
 16
 17## Language fundamentals
 18
 19### Functions
 20
 21```roc
 22# Lambda syntax
 23add = |a, b| a + b
 24
 25# Multi-line with indentation
 26process = |text|
 27    trimmed = Str.trim(text)
 28    Str.to_upper(trimmed)
 29
 30# Type signatures (optional but helpful)
 31greet : Str -> Str
 32greet = |name| "Hello, ${name}!"
 33```
 34
 35### Pattern matching
 36
 37```roc
 38when value is
 39    Ok(content) -> process(content)
 40    Err(NotFound) -> "not found"
 41    Err(_) -> "other error"
 42```
 43
 44### Records and tags
 45
 46```roc
 47# Records
 48user = { name: "Alice", age: 30 }
 49user.name  # Access field
 50
 51# Tags (algebraic data types)
 52Color : [Red, Green, Blue, Custom Str]
 53my_color = Custom("purple")
 54```
 55
 56## Error handling
 57
 58Roc uses `Result` types, not exceptions. Use `?` to short-circuit:
 59
 60```roc
 61main! = |_args|
 62    content = File.read_utf8!(path)?  # Returns early if error
 63    Stdout.line!("Success!")
 64```
 65
 66Or explicit pattern matching:
 67
 68```roc
 69when result is
 70    Ok(content) -> Stdout.line!("Read: ${content}")
 71    Err(err) -> Err(Exit(1, "Failed: ${Inspect.to_str(err)}"))
 72```
 73
 74## Common patterns
 75
 76### Working with lists
 77
 78```roc
 79numbers = [1, 2, 3, 4, 5]
 80evens = List.keep_if(numbers, |n| n % 2 == 0)
 81doubled = List.map(evens, |n| n * 2)
 82sum = List.walk(doubled, 0, Num.add)
 83```
 84
 85### String manipulation
 86
 87```roc
 88text = Str.concat("Hello", " World")
 89words = Str.split(text, " ")
 90trimmed = Str.trim("  spaces  ")
 91replaced = Str.replace_each(text, "World", "Roc")
 92```
 93
 94## Code quality tools
 95
 96```bash
 97roc format script.roc  # Auto-format code
 98roc check script.roc   # Type check without running
 99roc test script.roc    # Run expect expressions
100```
101
102### Tests with expect
103
104```roc
105add = |a, b| a + b
106
107expect add(2, 3) == 5
108expect add(0, 0) == 0
109```
110
111## Key concepts
112
113- **Immutable**: All values immutable; operations return new values
114- **Type inference**: Types inferred but signatures help clarity
115- **Helpful errors**: Compiler provides detailed, friendly messages
116- **No exceptions**: Use `Result` for errors; no try/catch
117- **No runtime**: Compiled binaries are standalone
118- **Functional**: Functions are first-class; use `|param| expression` syntax
119
120## Maturity caveat
121
122Roc is pre-1.0. Core features work well, but expect:
123- Breaking changes between versions
124- Smaller community/fewer examples
125- Excellent for learning; use production caution