Aura

Docs/Toolchain

Toolchain

Standard library

In-tree std packages — std.io, std.assert, std.collections, and prelude resolution.

Aura’s core stdlib is intentionally small (RFC-007, RFC-000 batteries-included-but-modular). In this repository, packages live under std/.

Packages today (post-alpha C12)

PackagePathRole
std.iostd/ioConsole, file I/O, argv, stdin, exit
std.assertstd/assertAssert helpers for tests
std.collectionsstd/collectionsMap/Set/HashMap/HashMapStr, Iterable, Int·String HOF, join (C12j)

Builtins such as Array<T> and core scalars are part of the language, not a separate import. String methods (indexOf, split, trim, toInt, …) are language surface — see Types and the cheatsheet.

std.io

Console, process, and file helpers (runtime aura_* intrinsics). Strict file APIs throw a String message on failure (missing path, I/O error, oversized file, embedded NUL). Soft tryReadFile returns null instead. Text is treated as a regular-file UTF-8 byte sequence (no embedded NUL); max size 256 MiB.

Console

APIRole
print / printlnstdout (no newline / with newline)
eprint / eprintlnstderr

Process (C12b–e)

APIRole
args(): Array<String>Process argv; [0] = program name; user flags from index 1 (C12b)
readLine(): String?One line without trailing \n / \r\n; null on EOF; empty line is "" (C12d)
readAllStdin(): StringRemainder of stdin (throws on oversize / I/O / embedded NUL)
exit(code: Int)Terminate with status; flushes stdout/stderr first; does not return (C12e)

Pass user args after -- with the CLI (CLI):

bash
aura run my_pkg -- --flag value
cargo run -p aura-cli -- run corpus/std_io/args -- hello
printf 'line\n' | cargo run -p aura-cli -- run corpus/std_io/stdin

Files (C11a / C12p)

APIRole
readFile(path): Stringread entire regular file (throws on error)
tryReadFile(path): String?soft read; null on missing/error (C12p)
writeFile(path, content)create/truncate and write
appendFile(path, content)append (create if needed)
fileExists(path): Boolregular file present
fileSize(path): Intbyte size (throws if missing)

Typical use (explicit import or auto-prelude on package builds):

aura
package main

import std.io as Io

fun main() {
  Io.println("Hello, Aura")
  val argv = Io.args()
  if (argv.len > 1) {
    Io.println(argv.get(1))
  }
  Io.writeFile("out.txt", "hi")
  val s = Io.tryReadFile("out.txt")
  if (s != null) {
    Io.println(s)
  }
}

Corpus:

bash
aura run corpus/std_io/app
aura run corpus/std_io/prelude
aura run corpus/std_io/files
aura run corpus/std_io/try_read_file
aura run corpus/std_io/args -- hello
aura run corpus/std_io/stdin
aura run corpus/std_io/exit
# monorepo: cargo run -p aura-cli -- run corpus/std_io/files

Dogfood CLI that ties args + soft read + String tools: examples/wc (README).

std.assert

Use with aura test and @test functions:

bash
aura run corpus/std_assert/app

Prefer package tests that exercise assert / assert_eq for Int / String / Bool in the current MVP.

std.collections

Type / helperNotes
Map<K, V>Linear map; get → V?; put / remove / clear
Set<T>Generic set (linear)
HashMapString→Int open addressing + auto-resize (C8i/C9b)
HashMapStrString→String open addressing; hash_map_str() (C12n)
Iterable<E>len + get protocol for for-in
map_ints / filter_ints / fold_intsInt array HOF helpers
map_strings / filter_strings / fold_stringsString array HOF helpers (C12o)
join(parts, sep)Array<String> → String with separator (C12j)

Alpha limits: no generic HashMap<K,V> yet (concrete monos: String→Int, String→String). See Arrays for HOF usage and capture limits.

bash
aura run corpus/std_collections/app
aura run corpus/std_collections/hashmap
aura run corpus/std_collections/hashmap_str
aura run corpus/std_collections/hof
aura run corpus/std_collections/hof_str
aura run corpus/std_collections/join

How the CLI finds std.*

  • Auto-prelude std.io for package builds
  • Path resolution for std.* (io / assert / collections):
    1. AURA_STD (directory that contains io/, assert/, …)
    2. Walk-up from the package looking for monorepo std/<pkg>
    3. Release install: share/aura/std/<pkg> next to the toolchain
    4. Embedded copy materialized under ~/.cache/aura/<version>/std/

After a normal install (or cargo install of a recent CLI), you should not need to declare std.io = { path = "..." } in app aura.toml.

What is not in core (by design)

Application frameworks, DI containers, ORM/HTTP stacks stay out of core RFCs. Expect those as ecosystem packages later, not as stdlib defaults.

Next

All docs pages