Guide
The Narra guide
The Narra guide
This guide teaches Narra to someone who has programmed before, in any language. Read the chapters in order: each one builds a small program step by step and uses what the earlier chapters taught.
A test compiles and runs every program in the guide. Each one works with the compiler as it is today and prints exactly the output shown under it.
Chapters
- Getting started: install the compiler, run a first program, read an error, split a program into a package.
- Values and types:
constandlet, numbers and division, strings and templates,boolandif, loops, arrays, maps, sized numbers, math, random numbers and hashing, tuples. - Functions and closures: functions,
requires, default arguments, recursion, functions as values, arrow functions, generics, closures andescaping. - Structs and enums: structs, copies and spread updates, enums and
match, recursive data andBox, generic types, type aliases,typeof, distinct and opaque types, re-exports. - Pattern matching:
matchwith guards and literals, array patterns, destructuring,isandOption, block expressions,ifvalues and? :, named arguments. - Option and Result:
std/option,std/result, errors without exceptions. - Traits: declarations,
implement, constraints,derives, equality, ordering and hashing,Dynamicvalues, saving values as JSON withShape. - Modules and packages: imports, aliases, exports, the standard modules, packages from git, workspaces.
- Memory and
mutable: reference counting, copies, writes to shared values,mutableparameters and their rules,Cell, leaks and hidden copies. - Effects and testing:
uses, effect checking,std/test,narrac testand golden files. - Files and the system: reading and writing files, paths, folders, standard input and output, the command line and the environment, other programs, bytes, time.
- Generators:
function*,yield, the effects of a generator, resuming by hand, coroutines. - The standard library: the modules larger programs are built on:
std/iteratorfor lazy and eager operations over generators,std/setfor distinct values,std/arenafor graphs of values,std/argsfor command lines,std/tomlfor configuration files,std/terminalfor colors and terminal detection,std/regexfor patterns andstd/unicodefor text as people see it. - Async: async functions,
await, waiting for all or the first, cancelling, files and the network in async code, async generators. - Threads and shared state: threads and scopes,
Parallel.map, channels,SharedandAtomic,Sendable, threads or async tasks. - Unsafe code and C: calling C, the
unsafeeffect and@trusted, C types and strings, pointers, linking,narrac audit. - Proofs and compile-time constants:
requiresbetween parameters,ensures, fixed-size arrays, refinement types, constant type parameters,@constfunctions, tagged templates. - Tools:
narrac emitandnarrac targets,narrac checkand its JSON output,narrac explain,narrac apply-fix,narrac fmtand its options,narrac query,narrac test, andnarrac lspfor editors. - Building for other systems:
std/buildconditions,@target,--targetand--all-targets, WebAssembly, Windows, debug and release builds,std/simd. - Narra for TypeScript programmers: optional reading that compares Narra with TypeScript, topic by topic.
Reading the samples
A program in the guide is a whole file that exports run, followed by what it prints:
export function run(args: Array<string>): int {
print("hello")
return 0
}
hello
A program that does not compile starts with a comment that holds the message the compiler prints. The line and column in it count the comment as line 1:
export function run(args: Array<string>): int {
return "hello"
Error: expected int, found string}
Save a sample to a file and run it with narrac run file.nra to try your own changes.
Planned
The language is meant to have these features, and the compiler does not have them yet. The guide does not teach them.
- Functions that C programs can call, and
@layoutfor structs shared with C (chapter 16).