MiniC

MiniC is a small C-like programming language implemented in Rust. It is designed as a teaching tool: the entire pipeline — parser, type checker, and interpreter — is intentionally small so you can read and understand every part of it. A complete MiniC program looks like this:

intfactorial(intn) {
ifn <= 1 { return1; }
returnn*factorial(n-1);
}
voidmain() {
intresult=factorial(10);
print(result);
}

---

Quick Start

cargo build # compile the project
cargo test# run the Rust library tests
shelltest tests/cli/ # run the CLI tests (requires cargo build first)

---

Nix Development Environment

This project ships a Nix flake that pins every tool to a reproducible version. If you have Nix installed you never need to manage Rust, Clippy, or shelltestrunner yourself — the flake does it for you.

What is Nix?

Nix is a package manager (and optionally a full OS) built around one idea: every package is a pure function of its inputs. The same inputs always produce the same output, on any machine. A flake is a self-contained Nix project that declares its own dependencies in flake.nix and locks them to exact hashes in flake.lock, giving you fully reproducible builds.

A devShell is a temporary shell that provides a curated set of tools without touching your normal environment. When you exit the shell those tools disappear.

Prerequisites

1. Install Nix (single-user or multi-user).

2. Enable flakes and the nix-command experimental feature. Add the following to ~/.config/nix/nix.conf (or /etc/nix/nix.conf):

   experimental-features = nix-command flakes
   

3. (Optional but recommended) Install direnv and nix-direnv. The .envrc file at the root of this repo will then activate the dev shell automatically whenever you cd into the project directory.

Entering the dev shell

nix develop # enter the shell manually

Or, if you use direnv:

direnv allow # run once; the shell activates on every cd after that

The dev shell provides:

Tool	Purpose
cargo / rustc	Compile and run Rust code
rustfmt	Auto-format source files
clippy	Lint Rust code
rust-analyzer	LSP backend for editors
shelltest	Run the CLI test suite

Building and testing inside the dev shell

Once inside nix develop (or with direnv active), the standard workflow is:

# 1. Compile
cargo build
# 2. Run unit and integration tests
cargo test# 3. Run the CLI (shelltestrunner) tests# These require the binary to be built first (step 1).
shelltest tests/cli/
# 4. Check formatting
cargo fmt --check
# 5. Run the linter
cargo clippy -- -D warnings

All commands above use the exact tool versions pinned in flake.lock, so results are identical regardless of what is installed on the host system.

The binary accepts two commands:

minic --check <file.minic> # parse + type-check only
minic --run <file.minic> # parse + type-check + interpret

---

CLI Usage

Running a valid program

Save the following as hello.minic:

voidmain() {
strname="Alice";
print(name)
}

$ minic --run hello.minic
Alice

Checking a program without running it

--check stops after the type checker. Useful for validating a program before committing to run it:

$ minic --check hello.minic
'hello.minic' is well-typed.

Malformed programs

The MiniC parser is lenient by design: it uses a many0 combinator that collects as many valid function declarations as it can and stops silently on anything it cannot recognise. This means most malformed programs do not produce a parse error — they produce an empty (or partial) function list, and the type checker then reports the problem.

Using an unknown keyword instead of a type:

defgreet(strname) {
print(name)
}

The parser skips the unrecognised def line and finds no functions. The type checker then rejects the result:

$ minic --check bad_keyword.minic
Type error: program must have a main function

Assigning the wrong type to a variable:

voidmain() {
intx="hello"
}

This parses successfully but is rejected by the type checker:

$ minic --check type_mismatch.minic
Type error: declaration of x: expected Int, got Str

Type errors

Type errors are caught after parsing, before any code runs.

Assigning a string to an int variable:

voidmain() {
intx="hello"
}

$ minic --check type_mismatch.minic
Type error: declaration of x: expected Int, got Str

Calling a function with the wrong argument type:

intdouble(intn) {
returnn*2
}
voidmain() {
intresult=double("hello")
}

$ minic --check wrong_arg.minic
Type error: argument 1 to double: expected Int, got Str

Using a boolean where an integer is expected:

voidmain() {
intx=10;
inty=x+ true
}

$ minic --check bool_in_arithmetic.minic
Type error: arithmetic operands must be Int or Float

Exit codes

Situation	Exit code
Success	0
Parse error, type error, or runtime error	1
Wrong arguments or missing file	1

---

Documentation

Read the documents in order for a complete picture of the project, or jump directly to the topic you need.

#	File	What you will learn
1	Language reference	What you can write in MiniC: types, statements, operators
2	Pipeline overview	How source code travels from text to execution
3	The AST	How a MiniC program is represented in memory
4	The parser	How source text is turned into an AST
5	The type checker	How type errors are caught before running
6	The interpreter	How a type-checked program is executed
7	The standard library	Built-in functions and how to add new ones
8	Testing	How the test suite is organised and how to add tests

---

Project Layout

src/
├── ir/ # AST node definitions
├── parser/ # Source text → unchecked AST
├── semantic/ # Type checker: unchecked AST → checked AST
├── environment/ # Shared symbol table used by type checker and interpreter
├── interpreter/ # Tree-walking interpreter
└── stdlib/ # Built-in functions (print, sqrt, pow, …)
tests/ # Integration tests (all tests live here)
docs/ # This documentation