Mica

<p align="center"> <strong>Mica</strong> is an experimental systems language that explores a tiny, expressive core with explicit effects, deterministic concurrency, and predictable performance.<br /> <em>Minimal • Industrial • Composable • Auditable</em> </p>

TL;DR — One small repository contains the full compiler pipeline, runnable examples, and documentation regenerated from real CLI output. Read it in a weekend, extend it on Monday, and rely on the GitHub Pages site for a guided tour.

📚 Docs at a glance: browse the published site at https://mica-lang.github.io/mica/ or open the same content locally under docs/.

Why it exists

Mica is a learning-sized, industrially-inspired language playground. It is designed for readers who want to inspect a full compiler without wading through millions of lines of code. Every subsystem is intentionally compact, documented, and wired together so that you can:

• Study real implementations of lexing, parsing, semantic analysis, lowering, and code generation.
• Experiment with effect systems and deterministic concurrency on small, auditable programs.
• Prototype new ideas quickly while keeping the entire pipeline in view.

The repository doubles as a field guide: runnable examples, snapshot-tested documentation, and a GitHub Pages site stay in sync with the CLI so that what you read is what the compiler actually does. The project is intentionally small enough to read in a weekend while still demonstrating the design patterns required for a production-grade compiler.

Who is Mica for?

• Language tinkerers who want to see how a complete front-end fits together without scaffolding a runtime or building infrastructure from scratch.
• Educators interested in a compact, auditable corpus they can walk through with a class or study group.
• Systems programmers exploring deterministic concurrency, capability tracking, and SSA-based lowering techniques in a familiar Rust codebase.

Highlights at a glance

| Pillar | What it means in practice | | --- | --- | | Tiny but expressive core | Learn the syntax in an afternoon and extend behaviour via standard libraries rather than bespoke keywords. | | Deterministic concurrency | Structured spawn/await with effect tracking ensures reproducible outcomes and debuggable traces. | | Capability-based effects | Explicit using clauses make side effects and resource access auditable for reviews and teaching. | | Ahead-of-time tooling | One CLI binary surfaces every compiler stage, each backed by snapshot tests in docs/snippets.md. | | Interop-friendly ABI | C-compatible calling conventions and hooks for Python/JavaScript “foreign tasks” keep the language ecosystem-friendly. |

Quick facts

| Area | Details | | --- | --- | | Minimum toolchain | Latest stable Rust via rustup | | CLI help | cargo run --bin mica -- --help | | Docs tour | docs/tour.md pairs with examples/ | | GitHub Pages | https://mica-lang.github.io/mica/ mirrors this README with an interactive tour | | Status page | docs/status.md summarises current health | | Roadmap | docs/roadmap/ tracks milestones | | Snapshot upkeep | cargo run --bin gen_snippets -- --check |

---

Table of contents

• Highlights at a glance
• Project status
• Quickstart
• Choose your path
• CLI reference
• Language features
• Example gallery
• Repository layout
• Documentation & resources
• Development workflow
• Roadmap
• Contributing
• FAQ
• License

Project status

Mica is a prototype under active design. Today the repository contains:

• A lexer, parser, resolver, effect checker, lowerer, and pretty-printer wired together behind a single CLI binary (mica).
• Exhaustiveness checking for match expressions, capability tracking, and structured diagnostics with source-code snippets.
• Snapshot-driven documentation for the CLI, plus a tutorial-oriented language tour.
• An executable test suite covering lexing, parsing, resolving, lowering, formatting, and both textual/native backend paths.

See the roadmap for the longer-term build-out and current areas of focus.

Choose your path

Pick the workflow that matches your goal today:

• 🎮 Try the playground — Visit the interactive playground to write and compile Mica code directly in your browser. All 21+ examples are available with one click.
• Skim the architecture — Start with the repository layout and open the corresponding modules in src/ to see how each stage is wired.
• Observe the compiler in motion — Run a program with --tokens, --ast, or --ir flags (see CLI reference) and compare the output against docs/snippets.md.
• Learn the language surface — Read docs/tour.md alongside the programs in examples/; every section links back to runnable code.
• Track project health — Check docs/status.md for the latest verification coverage and roadmap highlights.
• Hack on a feature — Review Development workflow and Roadmap, then open an issue or draft PR with your experiment.

Quickstart

Get started with Mica in minutes—no installation required!

Try Online First

Visit the 🎮 Interactive Playground to write and compile Mica code directly in your browser. Select from 21+ examples, edit the code, and explore different compiler stages instantly.

Local Installation

For local development and the full compiler experience:

1. Install prerequisites

• Install a recent stable Rust toolchain via https://rustup.rs/.
• LLVM ships with Rust, so no additional native dependencies are required for this prototype.

2. Clone, build, and smoke-test

git clone https://github.com/Sir-Teo/mica.git
cd mica
cargo build
cargo test

cargo test exercises lexing, parsing, lowering, the IR pipeline, and snapshot comparisons so you can trust subsequent experiments.

3. Explore the CLI

• Inspect the AST of a demo program:

  cargo run --bin mica -- examples/demo.mica
  

• Compile and execute one of the runnable samples end-to-end:

  cargo run --bin mica -- --run examples/methods.mica
  

Need a refresher on the available stages? Run cargo run --bin mica -- --help for an up-to-date flag list. Prefer to experiment without leaving your editor? Pair the commands above with cargo watch -x "run --bin mica -- --run <file>" for tight feedback loops (install via cargo install cargo-watch).

Troubleshooting

• If builds fail due to an outdated toolchain, run rustup update and retry.
• Regenerate CLI snapshots when golden files drift: cargo run --bin gen_snippets.
• Use cargo clean to clear stale build artifacts when switching toolchains.

CLI reference

The CLI surfaces multiple compiler stages behind feature flags. Combine them as needed:

cargo run --bin mica -- --tokens examples/demo.mica      # Lex the source file
cargo run --bin mica -- --ast examples/demo.mica         # Parse into an AST (default mode)
cargo run --bin mica -- --ast --pretty examples/adt.mica # Pretty-print the AST
cargo run --bin mica -- --resolve examples/adt.mica      # Inspect bindings and capabilities
cargo run --bin mica -- --check examples/adt.mica        # Exhaustiveness checks
cargo run --bin mica -- --lower examples/methods.mica    # Lower to the simple HIR
cargo run --bin mica -- --ir examples/methods.mica       # Dump the typed SSA IR via the backend shim
cargo run --bin mica -- --llvm examples/methods.mica     # Emit the LLVM scaffolding preview
cargo run --bin mica -- --build examples/methods.mica    # Produce a native binary next to the source
cargo run --bin mica -- --run examples/methods.mica      # Compile + run via the native backend
cargo run --bin mica -- --run --trace-json - examples/methods.mica # Run and emit a runtime trace to stdout

CLI output snapshots are maintained in docs/snippets.md.

Editor integration

A dedicated language server is still in development. In the meantime, the pretty-printer, CLI snapshots, and cargo fmt keep code style consistent.

Language features

Quick example

The following snippet demonstrates pattern matching and capability-aware logging. Save it as hello.mica and run cargo run --bin mica -- --run hello.mica:

module hello

capability Console

func main(using Console console) -> Result[Int, Error] {
  let hour = 17
  let message = match hour {
    hour if hour < 12 -> "Good morning"
    hour if hour < 18 -> "Good afternoon"
    _                 -> "Good evening"
  }

  console.println(message)
  Ok(0)
}

The example highlights Mica's explicit capabilities and exhaustive match expressions, even in small standalone modules.

Feature highlights

• Modules & namespaces — module declarations map directly to file system layout, simplifying code navigation.
• Algebraic data types (ADTs) — First-class enums with pattern matching and guard clauses.
• Deterministic concurrency — spawn, await, and effect-scoped using blocks keep asynchronous flows auditable.
• Generics & traits — Zero-cost abstractions with trait-constrained generics and higher-order functions.
• Capabilities & effects — Resources are granted explicitly, keeping IO, logging, and networking opt-in.

Example gallery

The examples/ directory showcases the current surface of th