Narra

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

  1. Getting started: install the compiler, run a first program, read an error, split a program into a package.
  2. Values and types: const and let, numbers and division, strings and templates, bool and if, loops, arrays, maps, sized numbers, math, random numbers and hashing, tuples.
  3. Functions and closures: functions, requires, default arguments, recursion, functions as values, arrow functions, generics, closures and escaping.
  4. Structs and enums: structs, copies and spread updates, enums and match, recursive data and Box, generic types, type aliases, typeof, distinct and opaque types, re-exports.
  5. Pattern matching: match with guards and literals, array patterns, destructuring, is and Option, block expressions, if values and ? :, named arguments.
  6. Option and Result: std/option, std/result, errors without exceptions.
  7. Traits: declarations, implement, constraints, derives, equality, ordering and hashing, Dynamic values, saving values as JSON with Shape.
  8. Modules and packages: imports, aliases, exports, the standard modules, packages from git, workspaces.
  9. Memory and mutable: reference counting, copies, writes to shared values, mutable parameters and their rules, Cell, leaks and hidden copies.
  10. Effects and testing: uses, effect checking, std/test, narrac test and golden files.
  11. Files and the system: reading and writing files, paths, folders, standard input and output, the command line and the environment, other programs, bytes, time.
  12. Generators: function*, yield, the effects of a generator, resuming by hand, coroutines.
  13. The standard library: the modules larger programs are built on: std/iterator for lazy and eager operations over generators, std/set for distinct values, std/arena for graphs of values, std/args for command lines, std/toml for configuration files, std/terminal for colors and terminal detection, std/regex for patterns and std/unicode for text as people see it.
  14. Async: async functions, await, waiting for all or the first, cancelling, files and the network in async code, async generators.
  15. Threads and shared state: threads and scopes, Parallel.map, channels, Shared and Atomic, Sendable, threads or async tasks.
  16. Unsafe code and C: calling C, the unsafe effect and @trusted, C types and strings, pointers, linking, narrac audit.
  17. Proofs and compile-time constants: requires between parameters, ensures, fixed-size arrays, refinement types, constant type parameters, @const functions, tagged templates.
  18. Tools: narrac emit and narrac targets, narrac check and its JSON output, narrac explain, narrac apply-fix, narrac fmt and its options, narrac query, narrac test, and narrac lsp for editors.
  19. Building for other systems: std/build conditions, @target, --target and --all-targets, WebAssembly, Windows, debug and release builds, std/simd.
  20. 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:

narra
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:

narra
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 @layout for structs shared with C (chapter 16).