ag - A Rust-Inspired Functional Language

ag is a Rust-inspired functional programming language that compiles to native machine code. The project emphasizes clarity, correctness, and learning through incremental development.

🎯 Project Goals

• Educational: Learn compiler construction through hands-on implementation
• Incremental: Build features phase-by-phase, achieving milestones along the way
• Observable: Every compilation stage produces human-readable visualizations
• Test-Driven: Comprehensive test coverage from day one
• Documented: Living documentation that evolves with the language

🚀 Quick Start

# Build the compiler
cargo build --release

# Compile an ag program (once implemented)
./target/release/ag examples/hello.ag -o hello

# View compilation stages
./target/release/ag examples/hello.ag --stage 1  # Lexer
./target/release/ag examples/hello.ag --stage 2  # Parser

📊 Development Status

See ROADMAP.md for the complete development plan.

🔧 What's Working Now

Phase 0: Foundation ✅

• ✅ Project structure and build system
• ✅ CLI with argument parsing
• ✅ Error handling with beautiful diagnostics
• ✅ HTML/SVG visualization framework
• ✅ Test infrastructure and utilities
• ✅ Documentation generation system

Coming in Phase 1: Lexical Analysis

• Tokenization of source code
• Keywords, operators, identifiers, literals
• Syntax-highlighted token visualization
• Line/column error reporting

🎨 Language Preview

Here's what ag will look like (Phase 2+):

// Factorial function
fn factorial(n: i32) -> i32 {
    let result = 1;
    let i = 1;
    while i <= n {
        result = result * i;
        i = i + 1;
    }
    return result;
}

fn main() -> i32 {
    let x = factorial(5);
    print_i32(x);  // Phase 8: stdlib
    return 0;
}

📚 Documentation

• ROADMAP.md - Complete development roadmap
• docs/ARCHITECTURE.md - Compiler design and architecture
• docs/current-spec.md - Language specification (generated)
• man/current-guide.md - User guide (generated)
• CHANGELOG.md - Version history

🧪 Testing

# Run all tests
cargo test

# Run tests for a specific phase
cargo test phase_01

# Run with verbose output
cargo test -- --nocapture

# Update snapshot tests
cargo insta review

🛠️ Development

Prerequisites

• Rust 1.70 or later
• Basic understanding of compilers (helpful but not required!)

Project Structure

ag-compiler/
├── src/           # Compiler implementation
├── tests/         # Test suites by phase
├── docs/          # Technical documentation
├── man/           # User manual
├── examples/      # Example programs
└── scripts/       # Build and documentation scripts

Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run clippy (linter)
cargo clippy

# Format code
cargo fmt

Contributing

We welcome contributions! Please:

1. Read the current phase in ROADMAP.md
2. Check open issues for tasks
3. Write tests for new features
4. Update documentation
5. Submit a pull request

🎓 Learning Resources

The ag compiler is designed as a learning project. Here are resources that inspired it:

• Crafting Interpreters by Robert Nystrom
• Engineering a Compiler
• Rust Compiler Development Guide
• Writing an Interpreter in Go by Thorsten Ball

📖 Core Principles

Test-Driven Development

Every feature comes with comprehensive tests. Tests accumulate across phases to ensure backward compatibility.

Incremental Complexity

The language grows one feature at a time. Each phase is complete and working before moving forward.

Visualization First

Every compilation stage produces a human-readable visualization for debugging and learning.

Living Documentation

Documentation is written as features are implemented and locked at phase completion.

🎯 Milestones

• Phase 5 Complete: Language achieves Turing-completeness 🎉
• Phase 7 Complete: First working compiler producing executables 🚀
• Phase 10 Complete: Version 1.0 - Feature-complete language ⭐

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

🤝 Acknowledgments

• The Rust community for excellent tooling and documentation
• Cranelift for providing a fantastic code generation backend
• All contributors who help build ag

Let's build a compiler together! 🚀

For questions or discussions, open an issue on GitHub.