hare-lang

Hare

Purpose

Guide agents through the Hare programming language: design philosophy (simple, stable, compiled), hare build/test/run workflows, stdlib overview, C FFI with @extern, the type system (tagged unions, slices), error handling with (T | error!), and comparison with C and Zig for systems utilities.

When to Use

• Writing small system utilities with C-like control and modern safety
• Building CLI tools or daemons with minimal dependencies
• Calling C libraries from Hare or exporting Hare functions to C
• Preferring explicit error handling over exceptions
• Evaluating Hare vs C or Zig for a new project
• Needing a stable, auditable codebase without heavy runtime

Workflow

1. Install Hare

# Linux/macOS — build from source
git clone https://git.sr.ht/~sircmpwn/hare
cd hare
make check   # builds and runs tests
sudo make install

hare version

# Create project (Hare has no project generator — lay out manually)
mkdir -p mytool && cd mytool
cat > hare.mod << 'EOF'
module mytool
EOF

2. Hello world and build

// main.ha
use fmt;

export fn main() void = {
	fmt::println("Hello, Hare!")!;
};

hare build -o mytool
./mytool

hare run .        # build and run
hare test         # run tests

3. Stdlib overview

Module	Purpose
fmt	Formatted I/O (printf, println)
io	Reader/writer interfaces
os	Files, environment, args
strings	String manipulation
bufio	Buffered I/O
encoding	JSON, hex, etc.
net	TCP/UDP networking
time	Dates and durations
mem	Memory helpers
types	Platform integer types

use os;
use fmt;
use strings;

export fn main() void = {
	const args = os::args;
	for (let i = 0z; i < len(args); i += 1) {
		fmt::println(args[i])!;
	};
};

4. Error handling

// Errors are tagged union values — explicit propagation with !
fn read_file(path: str) (str | os::error) = {
	const file = os::open(path)?;
	defer os::close(file);
	let buf: []u8 = [];
	io::readall(file, &buf)?;
	return strings::fromutf8(buf)!;
};

export fn main() void = {
	match (read_file("config.txt")) {
	case let s: str =>
		fmt::println(s)!;
	case let err: os::error =>
		fmt::fatalf("error: {}", err)!;
	};
};