Hare

https://harelang.org/documentation/
Admin
Hare is a systems programming language designed for simplicity, performance, and reliability with a...
Tokens:19,513
Snippets:172
Trust Score:8.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Hare Type Declarations: Correct Example

Source: https://harelang.org/documentation/usage/style

Provides an example of a correct type declaration in Hare, demonstrating the syntax for defining a type alias.

```Hare
type my_type = int;

```

--------------------------------

### Example Makefile for Installing Hare Modules in Projects

Source: https://harelang.org/documentation/usage/project-structure

This Makefile is for Hare projects that focus on installing Hare modules, specifically 'example1' and 'example2' in this case. It includes targets for running tests ('check'), installing the modules to a conventional third-party source directory ('install'), and removing them ('uninstall'). It respects DESTDIR and PREFIX variables for installation paths.

```makefile
.POSIX:
.SUFFIXES:
HARE=hare
HAREFLAGS=

DESTDIR=
PREFIX=/usr/local
SRCDIR=$(PREFIX)/src
HARESRCDIR=$(SRCDIR)/hare
THIRDPARTYDIR=$(HARESRCDIR)/third-party

check:
	$(HARE) test $(HAREFLAGS)

install:
	install -Dm644 example1/* $(DESTDIR)$(THIRDPARTYDIR)/example1/
	install -Dm644 example2/* $(DESTDIR)$(THIRDPARTYDIR)/example2/

uninstall:
	rm -rf $(DESTDIR)$(THIRDPARTYDIR)/example1
	rm -rf $(DESTDIR)$(THIRDPARTYDIR)/example2

.PHONY: check install uninstall

```

--------------------------------

### Hare Source File Organization: Correct Example

Source: https://harelang.org/documentation/usage/style

Illustrates the correct structure for a Hare source file, including the ordering of imports, declarations, and the use of empty lines for separation.

```Hare
use bar;
use baz;
use foo;

let x: int = 10;
let y: int = 10;

type my_type = struct {
     x: int,
     y: int,
     z: int,
};

fn foobar() void = {
     // ...
};

export fn main() void = {
     // ...
};

```

--------------------------------

### Build and Install Hare Compiler Frontend

Source: https://harelang.org/documentation/install/bootstrap

Builds and installs the Hare compiler frontend. This involves copying a platform-specific configuration file, running the 'make' command, optionally running tests with 'make check', and finally installing with 'make install' as root. The installation prefix can be customized by editing 'config.mk'.

```make
cp configs/$platform.mk config.mk
make
# Optionally run 'make check' to run the test suite
# Then run 'make install' as root.
```

--------------------------------

### Example Makefile for Installing Executables in Hare Projects

Source: https://harelang.org/documentation/usage/project-structure

This Makefile is designed for Hare projects that primarily install executable programs. It defines targets for building the default executable ('all'), running tests ('check'), cleaning build artifacts ('clean'), installing the executable ('install'), and uninstalling it ('uninstall'). It assumes executables are located in 'cmd/<executable_name>/'.

```makefile
.POSIX:
.SUFFIXES:
HARE=hare
HAREFLAGS=

DESTDIR=
PREFIX=/usr/local
BINDIR=$(PREFIX)/bin

HARE_SOURCES != find . -name '*.ha' # This line might not work in all shells or contexts, consider a more robust way to find sources if needed.

all: example-cmd

example-cmd: $(HARE_SOURCES)
	$(HARE) build $(HAREFLAGS) -o $@ cmd/$@/

check:
	$(HARE) test $(HAREFLAGS)

clean:
	rm -f example-cmd

install:
	install -Dm755 example-cmd $(DESTDIR)$(BINDIR)/example-cmd

uninstall:
	rm -f $(DESTDIR)$(BINDIR)/example-cmd

.PHONY: all check clean install uninstall

```

--------------------------------

### Build and Install Hare Compiler

Source: https://harelang.org/documentation/_sources/install/bootstrap

This snippet outlines the steps to build and install the Hare compiler (harec) from source. It involves copying a configuration file, running 'make' to build, and optionally 'make install' to install the compiler.

```shell
cp configs/$platform.mk config.mk
make
# Optionally:
# make check
# make install
```

--------------------------------

### Correct Hare Source File Organization Example

Source: https://harelang.org/documentation/_sources/usage/style

Shows the correct structure for a Hare source file, including the order of imports, declarations, and spacing between them. Uses alphabetical sorting for 'use' statements.

```hare
use bar;
use baz;
use foo;

let x: int = 10;
let y: int = 10;

type my_type = struct {
	x: int,
	y: int,
	z: int,
};

fn foobar() void = {
	// ...
};

export fn main() void = {
	// ...
};
```

--------------------------------

### Example Makefile for Hare Projects with Modules

Source: https://harelang.org/documentation/_sources/usage/project-structure

This Makefile is tailored for Hare projects focused on installing Hare modules (libraries). It provides targets for building, cleaning, and installing modules, facilitating library management for other Hare projects.

```Makefile
# This is an example project which only installs Hare modules, "example1" and "example2":

.PHONY:
all
check
clean
install-lib
uninstall-lib

# Default target: build all modules.
all:
	@echo "Building modules..."

# Run tests.
check:
	@echo "Running tests..."
	hare test

# Remove build artifacts.
clean:
	@echo "Cleaning build artifacts..."
	rm -rf build

# Install Hare modules.
install-lib:
	@echo "Installing modules..."
	# Example: hare install example1 example2

# Uninstall Hare modules.
uninstall-lib:
	@echo "Uninstalling modules..."
	# Example: hare uninstall example1 example2

```

--------------------------------

### Correct Hare Function Declaration Example

Source: https://harelang.org/documentation/_sources/usage/style

Demonstrates correct syntax for declaring Hare functions, including single-line and multi-line declarations with parameters. Shows proper indentation and token placement.

```hare
export fn main() void = {
	do_work(1, 2);
};

fn do_work(x: int, y: int) void = {
	// ...
};

fn many_parameters(
	param_one: int,
	param_two: int,
	param_three: int,
	param_four: int,
	param_five: int,
) void = {
	// ...
};

fn many_variadic(
	param_one: int,
	param_two: int,
	param_three: int,
	param_four: int,
	params: int...
) void = {
	// ...
};
```

--------------------------------

### Example Makefile for Hare Projects with Executables

Source: https://harelang.org/documentation/_sources/usage/project-structure

This Makefile is designed for Hare projects that primarily install executables. It includes standard targets for building, cleaning, and installing binaries. It assumes a typical project layout where executables are managed via the Makefile.

```Makefile
# This is an example Makefile for a project which only installs executables:

.PHONY:
all
check
clean
install-bin
uninstall-bin

# Default target: build all executables.
all:
	@echo "Building executables..."

# Run tests.
check:
	@echo "Running tests..."
	hare test

# Remove build artifacts.
clean:
	@echo "Cleaning build artifacts..."
	rm -rf build

# Install executables.
install-bin:
	@echo "Installing executables..."
	# Example: install -m 755 cmd/myexec $(PREFIX)/bin/myexec

# Uninstall executables.
uninstall-bin:
	@echo "Uninstalling executables..."
	# Example: rm -f $(PREFIX)/bin/myexec

```

--------------------------------

### Hare General Conventions: Correct Example

Source: https://harelang.org/documentation/usage/style

Demonstrates correct formatting for Hare code, including line breaks in function calls and conditional statements, and the placement of the semicolon.

```Hare
let result = frobnicate_the_frobs(scary_frob,
     sporty_frob, baby_frob, ginger_frob, posh_frob);

if (was_frobbed_correctly(frob_context, FROB_RESULT_SUCCESS,
             FROB_STANDARD_IEEE_7553, result)) {
     return true;
};

```

--------------------------------

### Hare Function Declarations: Correct Examples

Source: https://harelang.org/documentation/usage/style

Shows correct formatting for Hare function declarations, including functions fitting on one line, functions with many parameters requiring multiple lines, and variadic functions.

```Hare
export fn main() void = {
     do_work(1, 2);
};

fn do_work(x: int, y: int) void = {
     // ...
};

fn many_parameters(
     param_one: int,
     param_two: int,
     param_three: int,
     param_four: int,
     param_five: int,
) void = {
     // ...
};

fn many_variadic(
     param_one: int,
     param_two: int,
     param_three: int,
     param_four: int,
     params: int...
) void = {
     // ...
};

```

--------------------------------

### Correct Hare Code Formatting Example

Source: https://harelang.org/documentation/_sources/usage/style

Demonstrates correct multi-line code formatting in Hare, including function calls and if statements. It adheres to indentation rules and semicolon placement.

```hare
let result = frobnicate_the_frobs(scary_frob,
	*sporty_frob, baby_frob, ginger_frob, posh_frob);

if (was_frobbed_correctly(frob_context, FROB_RESULT_SUCCESS,
		FROB_STANDARD_IEEE_7553, result)) {
	return true;
};
```

--------------------------------

### Array Value Definitions in HareLang

Source: https://harelang.org/documentation/usage/style

Provides examples of correct single-line and multi-line array initializations in HareLang, including the use of the array initialization shorthand. Rules specify spacing, comma usage, and indentation.

```HareLang
let x = [1, 2, 3, 4, 5];
let x = [
     1,
     2,
     3,
     4,
     5,
];
let x = [
     1, 2, 3, 4, 5,
     1, 2, 3, 4, 5,
     1, 2, 3, 4, 5,
     1, 2, 3, 4, 5,
     1, 2, 3, 4, 5,
];
let x: [10]int = [1, 2, 3, 4, 5...];

```

--------------------------------

### Hare Example: Hello Module Implementation

Source: https://harelang.org/documentation/_sources/usage/modules

Provides the implementation for the 'hello' module used in the main program. It imports 'fmt' and 'io' to format and print a greeting to a specified output handle.

```hare
use fmt;
use io;

export fn greetuser(out: io::handle) void = {
     fmt::fprintln(out, "Hello!")!;
};

```

--------------------------------

### Incorrect Hare Code Formatting Example

Source: https://harelang.org/documentation/_sources/usage/style

Illustrates incorrect multi-line code formatting in Hare, highlighting issues with vertical alignment and indentation that deviate from the style guide.

```hare
let result = frobnicate_the_frobs(scary_frob,
						  sporty_frob,
						  baby_frob,
						  ginger_frob,
						  posh_frob);

if (was_frobbed_correctly(frob_context, FROB_RESULT_SUCCESS,
	FROB_STANDARD_IEEE_7553, result)) {
	return true;
};
```

--------------------------------

### Hare Installation Paths

Source: https://harelang.org/documentation/_sources/install/packaging

Specifies the default installation paths for the Hare build driver, compiler, documentation tool, and standard library source code on a typical Unix-like filesystem.

```plaintext
/usr/bin/hare
/usr/bin/harec
/usr/bin/haredoc
/usr/src/hare/stdlib
/usr/src/hare/third-party
```

--------------------------------

### Hare Installation Paths

Source: https://harelang.org/documentation/install/packaging

Specifies the default installation paths for Hare executables and source code on a Unix-like system. These paths can be customized in `config.mk`.

```text
/usr/bin/hare : The Hare build driver
/usr/bin/harec : The Hare compiler
/usr/bin/haredoc : The Hare documentation tool
/usr/src/hare/stdlib : The standard library source code
/usr/src/hare/third-party : Third-party library source code
```

--------------------------------

### Hare Module Import Example

Source: https://harelang.org/documentation/_sources/usage/modules

Demonstrates how importing a Hare module like 'foo::bar' translates to a directory path 'foo/bar/' which is appended to the search path to locate source files.

```hare
use foo::bar;
```

--------------------------------

### Hare: Postfix Expression Syntax

Source: https://harelang.org/documentation/_sources/usage/style

Provides examples of correct syntax for postfix expressions in Hare, such as function calls, array indexing, and slice indexing. Postfix operators should not be separated from their operands by a space.

```hare
func(x, y, z);
list[10];
slice[2..4];
size(int);
```

--------------------------------

### Hare Example: Hello World Program

Source: https://harelang.org/documentation/_sources/usage/modules

A basic Hare program demonstrating module imports and function exports. The main entry point calls a function from another module, showing inter-module communication.

```hare
use hello;
use os;

export fn main() void = {
     hello::greetuser(os::stdout);
};

```

--------------------------------

### Value Initialization in HareLang

Source: https://harelang.org/documentation/usage/style

Illustrates correct and incorrect ways to initialize values in HareLang. The style guide prefers explicit types that result in shorter programs. It covers basic integer types, arrays with inferred types, and nullable pointer types.

```HareLang
let x = 0z;

let y: [_]u8 = [1, 2, 3];

let z: [_]nullable *size = [&x, null];

```

--------------------------------

### Cross-compile Hare Program for aarch64 Architecture

Source: https://harelang.org/documentation/_sources/usage/cross

Compiles a Hare program named 'example.ha' for the 'aarch64' architecture using the '-a' flag. The output executable is named 'example'. This command assumes the necessary cross-toolchain for aarch64 is installed.

```shell
$ hare build -a aarch64 -o example example.ha
```

--------------------------------

### Represent Values in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Illustrates the preferred style for representing values in Hare, prioritizing explicit or hinted types that result in shorter programs. Includes examples for integers, arrays, and nullable pointers.

```hare
let x = 0z;

let y: [_]u8 = [1, 2, 3];

let z: [_]nullable *size = [&x, null];
```

```hare
let x: size = 0;

let y = [1u8, 2u8, 3u8];

let z = [&x: nullable *size, null: nullable *size];
```

--------------------------------

### Creating Bulleted Lists in Hare Documentation

Source: https://harelang.org/documentation/_sources/usage/documentation

Illustrates the syntax for creating bulleted lists within Hare documentation comments. Each list item should start with a hyphen '-', and the list should be followed by an empty line.

```hare
// This is a list:
//
// - foo
// - bar
// - baz
//
// It has three items.
export fn example() void = {
        // ...
};

```

--------------------------------

### Check Hare Version and Toolchain Configuration

Source: https://harelang.org/documentation/_sources/usage/cross

Displays the installed Hare version, build tags, HAREPATH, and the configured cross-toolchains for various architectures. This is useful for verifying your Hare setup and understanding available cross-compilation targets.

```shell
$ hare version -v
hare 0.24.1
build tags:
	x86_64
	linux
HAREPATH:
	/usr/src/hare/stdlib
	/usr/src/hare/third-party
toolchains:
 aarch64:
	AS=aarch64-alpine-linux-musl-as
	CC=aarch64-alpine-linux-musl-cc
	LD=aarch64-alpine-linux-musl-ld
 riscv64:
	AS=riscv64-alpine-linux-musl-as
	CC=riscv64-alpine-linux-musl-cc
	LD=riscv64-alpine-linux-musl-ld
 x86_64:
	AS=as
	CC=cc
	LD=ld
```

--------------------------------

### Hare Hello World Example

Source: https://harelang.org/documentation/_sources/index

A basic 'Hello, World!' program in Hare that retrieves the current user's name from environment variables and prints a personalized welcome message. This snippet demonstrates basic I/O operations and environment variable access in Hare.

```hare
use fmt;
use os;

export fn main() void = {
	const user = os::getenv("USER") as str;
	fmt::printfln("Welcome to the Hare documentation, {}!", user)!
};

```

--------------------------------

### Define Struct Values in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Provides examples of correct syntax for defining struct values in Hare, covering both single-line and multi-line styles. It specifies rules for spacing, indentation, and field qualification.

```hare
let x = struct { x: int = 10i, y: int = 10i };

let x = struct {
	x: int = 10,
	y: int = 10,
};

let x = my_struct {
	x = 10,
	y = 10,
};
```

--------------------------------

### Hare Basic Program: Print Welcome Message

Source: https://harelang.org/documentation/index

This Hare code snippet demonstrates a basic 'Hello, World!' style program. It imports the 'fmt' and 'os' modules to print a personalized welcome message to the console using an environment variable for the username. This example is suitable for beginners to understand basic Hare syntax and module usage.

```hare
use fmt;
use os;

export fn main() void = {
     const user = os::getenv("USER") as str;
     fmt::printfln("Welcome to the Hare documentation, {}!", user)!;
};

```

--------------------------------

### View Hare Build Toolchains

Source: https://harelang.org/documentation/usage/cross

Displays the cross-toolchains configured for your local Hare installation, including paths for assembler (AS), compiler (CC), and linker (LD) for various architectures. Useful for identifying and installing necessary system toolchains for cross-compilation.

```shell
$ hare version -v
hare 0.24.1
build tags:
     +x86_64
     +linux
HAREPATH:
     /usr/src/hare/stdlib
     /usr/src/hare/third-party
toolchains:
 aarch64:
     AS=aarch64-alpine-linux-musl-as
     CC=aarch64-alpine-linux-musl-cc
     LD=aarch64-alpine-linux-musl-ld
 riscv64:
     AS=riscv64-alpine-linux-musl-as
     CC=riscv64-alpine-linux-musl-cc
     LD=riscv64-alpine-linux-musl-ld
 x86_64:
     AS=as
     CC=cc
     LD=ld

```

--------------------------------

### Build command with pkg-config for C library linking

Source: https://harelang.org/documentation/_sources/usage/system-libraries

This command demonstrates how to link a Hare program with a C library using `pkg-config` to dynamically determine the necessary linker flags. It assumes `pkg-config` is installed and configured for the target library.

```shell
hare build $(pkg-config --libs-only-L --libs-only-l example) ...
```

--------------------------------

### Documenting a Hare Function

Source: https://harelang.org/documentation/_sources/usage/documentation

Demonstrates how to add a documentation comment directly above a Hare function declaration. This comment precedes the function definition and explains its purpose.

```hare
// This is an example function.
export fn example() void = {
        // ...
};

```

--------------------------------

### Hare Example: Platform-Specific Greeting

Source: https://harelang.org/documentation/_sources/usage/modules

An extended version of the 'hello' module that provides a platform-specific greeting for Linux users. This demonstrates how build tags can alter module behavior based on the target environment.

```hare
use fmt;
use io;

export fn greetuser(out: io::handle) void = {
     fmt::fprintln(out, "Hello Linux user!")!;
};

```

--------------------------------

### Hare: Binary and Unary Operator Spacing

Source: https://harelang.org/documentation/usage/style

Demonstrates correct spacing around binary operators (e.g., +, &&) and the absence of space for unary operators (e.g., -, !) and parenthesized expressions.

```Hare
2 + 4 + 5;
2 + (5 * 10);
-10 * 20;
!foobar;
let x: int = 2
     + 2
     + 2
     + 2;

let x = foo
     && (bar || baz);
```

--------------------------------

### Hare: Match and Switch Expression Formatting

Source: https://harelang.org/documentation/usage/style

Outlines preferred formatting for 'match' and 'switch' expressions in Hare, covering alignment, indentation, '=>' usage, default cases, void bodies, and terminal case ordering.

```Hare
match (x) {
case foo =>
     // ...
case foobar =>
     // ...
case foobarbaz =>
     // ...
};

let foobarbaz = match (x) {
case foo =>
     // ...
     yield ...;
case foobar =>
     // ...
     yield ...;
case foobaz =>
     // ...
     yield ...;
};

match (x) {
case (foo | bar) =>
     // ...
case foobar =>
     // ...
case foobaz =>
     // ...
};
```

--------------------------------

### Example Commit Message for User-Facing Command Changes

Source: https://harelang.org/documentation/_sources/process/release

Illustrates the commit message structure for user-facing command modifications in Hare. It references the affected man pages and provides a brief explanation for the change.

```text
build driver: drop -x flags to deps and build

It caused problems and was rarely used. Use -y -z instead.

Breaking-Change: hare-deps(1), hare-build(1)
```

--------------------------------

### Hare: Variable Declaration and Assignment Line Breaks

Source: https://harelang.org/documentation/_sources/usage/style

Demonstrates correct line breaking for long variable declarations and assignments in Hare. Each continuation line must be indented and start with the breaking token.

```hare
let x = 10;
let x: int = 10;
let x: int = 10,
	y: int = 20,
	z: int = 30;
let x: int =
	do_work(lots, of, parameters);
```

--------------------------------

### Calling Hare's greet_user from C

Source: https://harelang.org/documentation/_sources/usage/system-libraries

This example illustrates how to expose a Hare function to C. The Hare function `greet_user` uses C-compatible types and is exported. A C header declaration is provided, followed by a C `main` function that calls the exported Hare function.

```hare
use types::c;

export fn greet_user(user: const *c::char) int = {
	const user = c::tostr(user)!;
	return fmt::printfln("Hello, {}!", user)!: int;
};
```

```c
int greet_user(const char *user);

int main() {
	greet_user("Harriet");
	return 0;
}
```

--------------------------------

### Hare: Match and Switch Expression Formatting

Source: https://harelang.org/documentation/_sources/usage/style

Illustrates preferred formatting for match and switch expressions in Hare. This includes aligning cases, indenting bodies, using `=> void` for empty cases, and ordering terminal cases first.

```hare
match (x) {
case foo =>
	// ...
case foobar =>
	// ...
case foobarbaz =>
	// ...
};

let foobarbaz = match (x) {
case foo =>
	// ...
	yield ...;
case foobar =>
	// ...
	yield ...;
case foobaz =>
	// ...
	yield ...;
};

match (x) {
case (foo | bar) =>
	// ...
case foobar =>
	// ...
case foobaz =>
	// ...
};
```

--------------------------------

### Example Commit Message for Breaking Changes in Strings Module

Source: https://harelang.org/documentation/_sources/process/release

This example demonstrates the required commit message format for introducing breaking changes to the strings module in Hare. It specifies the affected module and lists the renamed functions.

```hare
strings: rename pad functions per convention

The following functions in strings:: have been renamed:

* strings::padstart renamed to strings::lpad
* strings::padend renamed to strings::rpad

Breaking-Change: strings::
```

--------------------------------

### Tuple Value Definitions in HareLang

Source: https://harelang.org/documentation/usage/style

Demonstrates correct single-line and multi-line tuple value definitions in HareLang. Emphasis is placed on spacing around parentheses and commas, and line-breaking conventions.

```HareLang
let x = (1, 2);
let x = (1, 2,
     3, 4, 5);
let x = (foo(), bar());
let x = (foo(),
     bar(), 1337);

```

--------------------------------

### Implementing a Hash Table in Hare

Source: https://harelang.org/documentation/faq

This snippet demonstrates a basic implementation of a hash table in Hare. It utilizes the standard library's hashing algorithms (hash::fnv or hash::siphash) for hashing keys. This example is useful for understanding how to implement common data structures from scratch in Hare.

```hare
const fnv = import("hash::fnv");
const siphash = import("hash::siphash");

// Example usage:
let key = "my_key";
let value = "my_value";

// Using fnv for trusted input
let hash1 = fnv.hash64(key);
// Using siphash for untrusted input
let hash2 = siphash.hash64(key, "my_secret_key");

// Hash table implementation would follow...
```

--------------------------------

### Hare: Branching and Loop Syntax

Source: https://harelang.org/documentation/_sources/usage/style

Demonstrates correct syntax and formatting for branching (if) and looping (for) statements in Hare. This includes spacing around predicates, handling of code blocks, and semicolon usage in for loop predicates.

```hare
if (x == y) {
	// ...
};

for (let x = 0; x < 10; x += 1) {
	// ...
};

for (x < y) {
	// ...
};

if (do_work(x) == y
		&& do_work(y) == z
		&& do_work(z) == q) {
	// ...
};
```

--------------------------------

### Hare Function Declaration Example

Source: https://harelang.org/documentation/usage/conventions

Demonstrates how to declare a Hare function with parameters and return types, following the specified naming conventions. This function is part of the 'sam' module and takes a 'destination' parameter.

```Hare
fn sam::go(to: destination) void;
```

--------------------------------

### Struct Value Definitions in HareLang

Source: https://harelang.org/documentation/usage/style

Shows correct multi-line and single-line struct definitions in HareLang. Rules dictate spacing around tokens, indentation for multi-line definitions, and consistent qualification of fields.

```HareLang
let x = struct { x: int = 10i, y: int = 10i };

let x = struct {
     x: int = 10,
     y: int = 10,
};

let x = my_struct {
     x = 10,
     y = 10,
};

```

--------------------------------

### Define Array Values in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Demonstrates correct syntax for defining array values in Hare, including single-line and multi-line styles. It details spacing rules for elements, commas, and the array initialization shorthand.

```hare
let x = [1, 2, 3, 4, 5];
let x = [
	1,
	2,
	3,
	4,
	5,
];
let x = [
	1, 2, 3, 4, 5,
	1, 2, 3, 4, 5,
	1, 2, 3, 4, 5,
	1, 2, 3, 4, 5,
	1, 2, 3, 4, 5,
];
let x: [10]int = [1, 2, 3, 4, 5...];
```

--------------------------------

### Define Tuple Values in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Illustrates the correct syntax for defining tuple values in Hare, covering single-line and multi-line styles. It specifies rules for spacing around elements, commas, and parentheses.

```hare
let x = (1, 2);
let x = (1, 2,
	3, 4, 5);
let x = (foo(), bar());
let x = (foo(),
	bar(), 1337);
```

--------------------------------

### Struct Type Definition in Hare

Source: https://harelang.org/documentation/usage/style

Illustrates how to define struct types in Hare, supporting both single-line and multi-line styles. It covers field formatting, nested structs, and optional commas.

```hare
struct {
     x: int,
     y: int,
     z: int,

     metadata: struct {
             foo: int,
             bar: int,
             baz: int,
     },
};

```

--------------------------------

### Enum Type Definition in HareLang

Source: https://harelang.org/documentation/usage/style

Demonstrates the correct syntax for defining enum types in HareLang. Enum aliases should be singular, and members must be in all capital letters.

```HareLang
type character_flag = enum {
     BIG,
     FRIENDLY,
     GIANT,
};

```

--------------------------------

### Example Commit Message for Compiler Breaking Changes

Source: https://harelang.org/documentation/_sources/process/release

Shows the commit message format for introducing backwards incompatible changes to the Hare compiler. It lists affected components like 'language' and 'abi' and provides details about the changes.

```text
handle allocation failure by returning nomem

previously, if the result type of an allocation-expression was not a
nullable pointer type, the builtin would abort. this is now handled
by instead returning nomem.

this commit introduces the following breaking changes:

        - nomem cannot be used as a name anymore
        - alloc, insert and append have different return values now
        - harec binary interface has changed.

Breaking-Change: language, abi
```

--------------------------------

### Hare: Branching Expression Formatting (if, for)

Source: https://harelang.org/documentation/usage/style

Details the formatting rules for 'if' and 'for' statements in Hare, including spacing around parentheses, brace handling for expression lists, and semicolon spacing in 'for' predicates.

```Hare
if (x == y) {
     // ...
};

for (let x = 0; x < 10; x += 1) {
     // ...
};

for (x < y) {
     // ...
};

if (do_work(x) == y
             && do_work(y) == z
             && do_work(z) == q) {
     // ...
};
```

--------------------------------

### Define Tuple Types in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Demonstrates the correct syntax for defining tuple types in Hare, including single-line and multi-line declarations. It emphasizes placement of commas and closing parentheses.

```hare
type my_tuple = (int, uint);
type my_tuple = (type_a, type_b, type_c,
	type_d, type_e, type_f);
```

--------------------------------

### Constant Declaration in Hare

Source: https://harelang.org/documentation/usage/style

Defines the syntax for declaring constants in Hare. Constants must be named in UPPER_UNDERSCORE_CASE and require specific spacing around tokens like ':', '=', and type specifiers.

```hare
def MY_CONSTANT: int = 1234;

```

--------------------------------

### Tuple Type Definitions in Hare

Source: https://harelang.org/documentation/usage/style

Explains the syntax for defining tuple types in Hare, covering single-line and multi-line styles. It details spacing rules around commas and parentheses, with a preference for single-line definitions when possible.

```hare
type my_tuple = (int, uint);
type my_tuple = (type_a, type_b, type_c,
     type_d, type_e, type_f);

```

--------------------------------

### Array and Slice Type Definitions in Hare

Source: https://harelang.org/documentation/usage/style

Shows the correct syntax for array and slice types in Hare, emphasizing the absence of spaces between brackets, dimensions, and member types. Arrays are preferred over slices for performance.

```hare
[]int
[5]int
[2 + 2]int
[*]int
[_]int

```

--------------------------------

### Global Variable Declaration in Hare

Source: https://harelang.org/documentation/usage/style

Details the rules for declaring global variables in Hare. Similar to constants, global variables require specific spacing around tokens and type specifiers.

```hare
let my_global: int = 1234;

```

--------------------------------

### Cross-compile Hare Program (Easy Way)

Source: https://harelang.org/documentation/usage/cross

Compiles a Hare program for a target architecture using the '-a' flag with 'hare build' and specifies an output file with '-o'. This method assumes the necessary cross-toolchain is installed on the system. The 'file' command is used to verify the compiled executable's target architecture.

```shell
$ hare build -a aarch64 -o example example.ha
$ file example
example: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV),
statically linked, with debug_info, not stripped

```

--------------------------------

### Define Enum Types in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Shows the syntax for defining enum types in Hare. It follows the rule that enum aliases should be singular and members should be in ALL_CAPS.

```hare
type character_flag = enum {
	BIG,
	FRIENDLY,
	GIANT,
};
```

--------------------------------

### Configure Cross-compilation Toolchain (Hard Way)

Source: https://harelang.org/documentation/usage/cross

Demonstrates setting environment variables for the 'AS' (assembler) and 'LD' (linker) to point to a custom-built cross-toolchain when cross-compiling. The '-a' flag is still required with 'hare build'. This method is used when system toolchains are unavailable or insufficient, and may require additional setup for C libraries.

```shell
# Example for setting environment variables for a custom toolchain
export AS=/path/to/custom/aarch64-linux-gnu-as
export LD=/path/to/custom/aarch64-linux-gnu-ld
# If linking to C libraries, also set CC and LDFLAGS
# export CC=aarch64-linux-gnu-gcc
# export LDFLAGS="-L/path/to/sysroot/usr/lib"

# Then build with the -a flag
hare build -a aarch64 -o example example.ha

```

--------------------------------

### Hare Foreign Symbol Naming: System Library Example (SDL_Init)

Source: https://harelang.org/documentation/usage/conventions

Demonstrates how to name symbols that are forward-declared from system libraries, like SDL. The convention is to use the naming scheme defined by the authoritative source. Optional changes include removing namespace suffixes and Hungarian notation prefixes.

```hare
// Original foreign symbol
// extern fn SDL_Init(flags: u32): i32

// Idiomatic Hare naming (if no foreign specification)
// fn sdl_init(flags: u32): i32

// Convention for foreign symbols:
// Option 1: Keep original name
// extern fn SDL_Init(flags: u32): i32

// Option 2: Remove namespace suffix and adapt capitalization if appropriate
// import sdl "sdl"
// extern fn sdl::Init(flags: u32): i32

// Example showing removal of Hungarian notation (if applicable to enum members)
// export type sdl::BlendFactor = enum
//     | ZERO
//     | ONE
//     // ... other blend factors
```

--------------------------------

### Hare Function Declarations with Parameters and Return Types

Source: https://harelang.org/documentation/usage/conventions

Provides examples of Hare function declarations, illustrating parameter ordering (object acted upon first) and return types that can include values, errors, or EOF conditions. These functions are from libraries like 'bufio', 'io', and 'lex'.

```Hare
fn bufio::scantok(stream: *io::stream, delim: u8) ([]u8 | io::EOF | io::error);

fn io::read(stream: *io::stream, buf: []u8) (size | io::EOF | io::error);

fn lex::init(in: *io::stream, path: str) lexer;
```

--------------------------------

### Handle Type Assertion Failures in Hare

Source: https://harelang.org/documentation/usage/debugging

Illustrates runtime assertion failures when using the 'as' operator on a tagged union with a mismatched type in Hare. Provides an example of the failure and a recommended solution using a 'match' expression.

```Hare
export fn main() void = {
     let x: (int | uint) = 10i;  // value is of type int
     x as int;                   // okay
     x as uint;                  // abort
};

```

```Hare
// Before:
let x: (int | uint) = 10i;
x as uint; // Will fail if x is an int

// After:
let x: (int | uint) = 10i;
match (x) {
case let x: int =>
        // x is an int
case let x: uint =>
        // x is a uint
};

```

--------------------------------

### Variable Declaration and Binding in HareLang

Source: https://harelang.org/documentation/usage/style

Illustrates correct variable naming conventions (lower_underscore_case) and rules for splitting long binding lists across multiple lines in HareLang. The breaking token should be on the first line, with subsequent lines indented.

```HareLang
let x = 10;
let x: int = 10;
let x: int = 10,
     y: int = 20,
     z: int = 30;
let x: int =
     do_work(lots, of, parameters);

```

--------------------------------

### Hare Release Policy: Documenting Compiler Breaking Changes

Source: https://harelang.org/documentation/process/release

Example of documenting backwards incompatible changes to the Hare compiler. It lists affected components like 'abi' and 'language' using a 'Breaking-Change:' trailer and provides details on the change.

```hare
handle allocation failure by returning nomem

previously, if the result type of an allocation-expression was not a
nulllable pointer type, the builtin would abort. this is now handled
by instead returning nomem.

this commit introduces the following breaking changes:

        - nomem cannot be used as a name anymore
        - alloc, insert and append have different return values now
        - harec binary interface has changed.

Breaking-Change: language, abi
```

--------------------------------

### Handle Slice or Array Out of Bounds Errors in Hare

Source: https://harelang.org/documentation/usage/debugging

Demonstrates how accessing an index outside the defined bounds of a slice or array triggers a runtime assertion in Hare. Includes examples of incorrect access and recommended solutions.

```Hare
export fn main() void = {
     let x: [3]int = [1, 2, 3];
     x[0]; // okay
     x[1]; // okay
     x[2]; // okay
     x[3]; // abort

     x[0..2];  // okay
     x[0..10]; // abort
};

```

```Hare
let x: [3]int = [0...];
let ix = 10z;
if (ix < len(x)) {
        x[ix]; // okay
};

```

--------------------------------

### Hare: Type Casting Syntax

Source: https://harelang.org/documentation/_sources/usage/style

Shows the correct syntax for type casting in Hare, emphasizing the spacing rules around the colon token. A space is required between the colon and the type, but not between the operand and the colon.

```hare
let x = y: int;
```

--------------------------------

### Hare Runtime Error Assertion Example

Source: https://harelang.org/documentation/_sources/usage/debugging

Demonstrates the 'error occurred' runtime assertion in Hare using the error assertion operator (!). This code snippet will abort when executed with an error. It requires the `fmt` module for printing.

```hare
use fmt;

// Use `hare run main.ha >/dev/full` to simulate this error
export fn main() void = {
	fmt::println("Hello world!")!;
};

```

--------------------------------

### Tagged Union Type Definitions in Hare

Source: https://harelang.org/documentation/usage/style

Demonstrates the declaration of tagged union types in Hare, supporting single-line and multi-line formats. Rules for spacing around '|' and within parentheses are specified, with a preference for single-line if within 80 columns.

```hare
type my_union = (type_a | type_b | type_d | type_e | type_f | type_g);

type my_result = (result_type_a | result_type_b | result_type_c |
     result_type_d | result_type_e);

type my_error = (error_type_a | error_type_b | error_type_d | error_type_c);

type my_union = (...my_result | ...my_error);

```

--------------------------------

### Referencing Hare Symbols in Documentation

Source: https://harelang.org/documentation/_sources/usage/documentation

Shows how to reference other Hare symbols (like functions or types) within documentation comments by enclosing the symbol name in double square brackets. This helps link related code elements.

```hare
// This is an example function.
//
// See also [[os::exit]]
export fn example() void = {
        // ...
};

```

--------------------------------

### Customizing Toolchain via config.mk

Source: https://harelang.org/documentation/install/packaging

Demonstrates how to configure the Hare toolchain for different architectures and cross-compilation using a `config.mk` file. This includes setting assembler and linker paths.

```makefile
# Example for AArch64 cross-compilation
AARCH64_AS = aarch64-linux-gnu-as
AARCH64_LD = aarch64-linux-gnu-ld

# For native host
AS = as
LD = ld

# Environment variables for linking (e.g., with libc)
LDFLAGS = "-L/path/to/libs"
LDLINKFLAGS = "-L/path/to/linker/libs"
```

--------------------------------

### Including Code Samples in Hare Documentation

Source: https://harelang.org/documentation/_sources/usage/documentation

Explains how to include code samples within Hare documentation comments. Lines of code should be indented with at least two whitespace characters or one tab character relative to the comment's body.

```hare
// This is a code sample:
//
//   let x = 1337;
//   example(x);
//
// It is simply indented from the body of the comment.
export fn example() void = {
        // ...
};

```

--------------------------------

### Define Array and Slice Types in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Array and slice types in Hare have specific formatting rules with no spaces between brackets, length expressions, and member types. Arrays are preferred over slices for performance reasons.

```hare
[]int
[5]int
[2 + 2]int
[*]int
[_]int
```

--------------------------------

### Declare Global Variable in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Global variables in Hare are declared similarly to constants, using let. Spaces are required around the equals sign and after the colon. The use of globals is generally discouraged.

```hare
let my_global: int = 1234;
```

--------------------------------

### Define Tuple Type in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Tuple types in Hare can be single-line or multi-line. The single-line format is preferred if it fits within 80 columns. Spaces are handled specifically around commas and parentheses.

```hare
()
```

--------------------------------

### Hare: Operator Spacing and Line Breaks

Source: https://harelang.org/documentation/_sources/usage/style

Illustrates correct spacing around unary and binary operators, and preferred line breaking for expressions involving binary operators in Hare. Spaces are required around binary operators, but not unary ones or parentheses.

```hare
2 + 4 + 5;
2 + (5 * 10);
-10 * 20;
!foobar;
let x: int = 2
	+ 2
	+ 2
	+ 2;

let x = foo
	&& (bar || baz);
```

--------------------------------

### Define Struct Type in Hare

Source: https://harelang.org/documentation/_sources/usage/style

Structs in Hare can be defined in single-line or multi-line styles. The multi-line style requires specific indentation and newlines. Field names should not be separated from the colon, but a space is needed after the colon.

```hare
struct {
	x: int,
	y: int,
	z: int,

	metadata: struct {
		foo: int,
		bar: int,
		baz: int,
	},
};
```

--------------------------------

### Hare Release Checklist - Initial Steps

Source: https://harelang.org/documentation/_sources/process/release

This checklist outlines the initial steps required for preparing a new Hare release candidate. It includes cutting a release branch and tagging the candidate.

```text
1. Cut X.YY.Q branch
2. Update scripts/version, commit
3. Tag release candidate with changelog (git shortlog)
```

--------------------------------

### Hare: Handling Unreachable Code Execution

Source: https://harelang.org/documentation/_sources/usage/debugging

Explains the 'execution reached unreachable code' runtime assertion in Hare, often caused by non-exhaustive match expressions or invalid values in switch statements. The provided example demonstrates a match expression that may not cover all possible cases, potentially leading to this runtime error.

```hare
export fn main() void = {
	let x: (u8 | u16 | u32 | u64) = 0u64;
	match (x) {
	case u8 => // ...
	case u16 => // ...
	case u32 => // ...
	};
};

```

--------------------------------

### Hare: Slice or Array Out of Bounds Runtime Error Example

Source: https://harelang.org/documentation/_sources/usage/debugging

Demonstrates a 'slice or array out of bounds' runtime assertion in Hare. This occurs when an index or slice operation attempts to access memory outside the defined bounds of an array or slice, indicating a potential programming error. The example shows valid and invalid access attempts.

```hare
export fn main() void = {
	let x: [3]int = [1, 2, 3];
	x[0]; // okay
	x[1]; // okay
	x[2]; // okay
	x[3]; // abort

	x[0..2];  // okay
	x[0..10]; // abort
};
```

--------------------------------

### Hare: Type Assertion Failed Runtime Error Example

Source: https://harelang.org/documentation/_sources/usage/debugging

Shows a 'type assertion failed' runtime error in Hare. This error happens when the 'as' operator is used on a tagged union value, and the stored value's type does not match the type specified in the 'as' operation. The example highlights a successful and a failing type assertion.

```hare
export fn main() void = {
	let x: (int | uint) = 10i;  // value is of type int
	x as int;                   // okay
	x as uint;                  // abort
};
```
Tokens:
Raw