Amber

Amber Skills Reference Guide

This guide helps contributors to Amber understand the various skills and knowledge areas needed to effectively contribute to the project. Whether you're working on the compiler, standard library, documentation, or tooling, this reference will help you navigate the ecosystem.

Table of Contents

• Compiler Development
• Standard Library
• Language Syntax
• Testing
• Tooling

Compiler Development

The Amber compiler is written in Rust and follows a multi-stage compilation pipeline. Understanding the compiler architecture is essential for any significant contributions.

Core Compiler Modules

Compilation Pipeline

Lexer → Parser → TypeChecker → Translator → Optimizer → Renderer

1. Tokenization: Converts source code into tokens using rules.rs
2. Parsing: Builds AST using Heraclitus framework
3. Type Checking: Validates and infers types
4. Translation: Converts AST to FragmentKind IR
5. Optimization: Removes redundant code
6. Rendering: Generates final Bash script

Key Compiler Concepts

Syntax Modules

Syntax modules implement the SyntaxModule<T> trait with methods:

• parse(): Parses tokens into AST nodes (returns SyntaxResult)
• typecheck(): Validates types (returns SyntaxResult)
• translate(): Converts to FragmentKind IR

Parsing Helpers (Heraclitus Framework)

Failure Handling

• Quiet Error: "This doesn't match, try another module" - caught and backtracked
• Loud Error: "This matches but code is invalid" - halts compilation

Fragments (IR)

Compiler Flags

Compiler flags can customize behavior per function:

#[allow_nested_if_else]
fun foo() {
    // ...
}

#[allow_generic_return]
fun bar(): Text? {
    // ...
}

#[allow_absurd_cast]
fun baz() {
    // ...
}

Available flags:

• allow_nested_if_else: Disable if-chain warnings
• allow_generic_return: Suppress generic return type warnings
• allow_absurd_cast: Disable absurd cast warnings

Environment Variables

Standard Library

The standard library is written in Amber itself and located in src/std/. Each module provides utilities for common tasks.

Standard Library Modules

Standard Library Patterns

Importing

// Single function
import { capitalize } from "std/text"

// All functions
import * from "std/http"

// Aliasing (not supported - use full module path)

Failable Functions

Many stdlib functions are failable (return Type?):

// Before (0.4.x)
if dir_create("mydir") {
    // success
} else {
    // failure
}

// After (0.5.x)
dir_create("mydir") exited(code) {
    if code == 0 {
        echo "Success"
    } else {
        echo "Failed with code {code}"
    }
}

Text Module (std/text)

Array Module (std/array)

File System Module (std/fs)

Language Syntax

Data Types

Type System

Union Types

Functions can accept multiple types:

fun process(data: [Bool] | [Int]) {
    // ...
}

Type Casting

// Valid cast
let num = true as Int  // 0 or 1

// Absurd cast (warning)
let num = "123" as Int  // Use parse_int() instead

Type Condition

Runtime type checking:

fun getObject(value) {
    if {
        value is Text: getByName(value)
        value is Num: getById(value)
    }
}

Variables

// Declaration
let name = "John"
let age: Int = 30

// Reassignment
name = "Rob"

// Constant
const PI = 3.14159

// Type inference with empty arrays
let arr = []  // Type inferred later
arr += [1]    // Now [Int]

Functions

// Basic function
fun myFunction(arg1, arg2) {
    return arg1 + arg2
}

// Typed function
fun add(a: Int, b: Int): Int {
    return a + b
}

// Default parameters
fun greet(name: Text = "World"): Text {
    return "Hello {name}"
}

// Failable function
fun mightFail(): Text? {
    fail 1  // Explicit failure
    return "success"?
}

// Reference parameter
fun push(ref array, value) {
    array += [value]
}

Control Flow

If Statements

if age < 18 {
    echo "Minor"
} else if age < 65 {
    echo "Adult"
} else {
    echo "Senior"
}

Loops

// For loop
for fruit in ["apple", "banana"] {
    echo fruit
}

// Range
for i in 0..3 {
    echo i  // 0, 1, 2
}

// While loop
while condition {
    // ...
}

Switch-like with Type Condition

if {
    value is Text: handleText(value)
    value is Int: handleInt(value)
}

Commands

// Command statement
$ mv file.txt dest.txt $ failed(code) {
    echo "Failed with code {code}"
}

// Command expression
let result = $ cat file.txt $ succeeded {
    echo "Success: {result}"
}

// Modifiers
sudo trust $ apt update $  // Privilege escalation + no failure check
silent $ apt update $      // Suppress output

Command Modifiers

Testing

Test Blocks

import { assert } from "std/test"

test "can multiply numbers" {
    let result = 10 * 2
    assert(result == 20)
}

test {
    let sum = 1 + 2
    assert(sum == 3)
}

Running Tests

# Run all tests
amber test

# Filter by filename/test name
amber test "variable"

# Run specific file
amber test main.ab

# Filter specific file
amber test main.ab "zip"

Test File Organization

Tests are in src/tests/:

• validity/: Expected success cases
• erroring/: Expected compilation errors
• stdlib/: Standard library functionality

Tooling

CLI Commands

Global Options

Postprocessors

Editor Integrations

LSP Support

Amber LSP provides:

• Autocompletion
• Real-time error checking
• Smart suggestions
• Go-to definition
• Hover documentation

Available for VS Code, Zed, and Helix.

Contributing Guide

PR Process

1. Create an issue discussing the proposed changes
2. Fork the repository and create a branch
3. Implement changes following project conventions
4. Add tests in src/tests/
5. Open a PR targeting the staging branch
6. Await review (minimum 2 maintainer approvals)

Development Setup

# Clone and build
git clone https://github.com/amber-lang/amber
cd amber
cargo build

# Run Amber code
cargo run run script.ab

# Build to Bash
cargo run build input.ab output.sh

# Debug
AMBER_DEBUG_PARSER=true cargo run run script.ab
AMBER_DEBUG_TIME=true cargo run run script.ab

# Profile
cargo flamegraph -- script.ab

Testing in Codebase

# All tests
cargo test

# Specific module
cargo test stdlib

# Single test
cargo test function_with_wrong_typed_return

Code Style

• Follow existing patterns in src/modules/
• Use Heraclitus macros (syntax_name!, parse_statement!, etc.)
• Add tests for new features
• Ensure shellcheck compliance in generated Bash

Migration Notes

0.4.0-alpha → 0.5.0-alpha

Resources

Official Documentation

• Amber Website
• Documentation
• GitHub Repository
• Amber LSP

Community

• Discord
• Discussions

Key Files for Reference

Quick Reference

Common Tasks

Troubleshooting

Last updated: 2026-02-18 Version: 0.5.1-alpha