Narra

Narra

Easy to read, hard to break. Narra is a compiled language that keeps your code clear, for you, your team and your tools.

curl -fsSL https://github.com/lxsmnsyc/narra/releases/latest/download/install.sh | sh
shapes.nra
narra
import * as Int from "std/int"

enum Shape {
  Circle(radius: int)
  Rect(width: int, height: int)
}

function area(shape: Shape): int {
  return match (shape) {
    Shape.Circle(radius) => 3 * radius * radius,
    Shape.Rect(width, height) => width * height,
  }
}

export function run(args: Array<string>): int uses io, alloc {
  for (const shape of [Shape.Circle(3), Shape.Rect(3, 4)]) {
    print(`area ${Int.toString(area(shape))}`)
  }
  return 0
}

01

What you see is what runs.

A + adds numbers. A function call calls a function. Nothing runs behind your back, and nothing turns into another type unless you ask. When you read Narra code, you're reading what the program does.

Narra stops thistax.nra
narra
export function withTax(price: int): f64 {
  return price * 1.12
Error: * needs two numbers of the same type, found int and f64Error: expected f64, found int}
You write thistax.nra
narra
import * as Float from "std/float"

export function withTax(price: int): f64 {
  return Float.fromInt(price) * 1.12
}

02

Change one thing without breaking another.

Two parts of your program can't quietly share the same data. When you want a copy, you write copy. When a function should change something, the call says mutable. A change in one place stays in that place.

Narra stops thisalias.nra
narra
import * as Int from "std/int"

struct Player {
  name: string
  hp: int
}

function damage(mutable player: Player, amount: int) {
  player.hp = player.hp - amount
}

export function run(args: Array<string>): int uses io, alloc {
  let hero = Player { name: "Ana", hp: 100 }
  const saved = hero
Error: saved would be a second name for the struct in hero; use hero, or copy(hero) for a struct of its own  damage(mutable hero, 30)
  print(`${Int.toString(hero.hp)} ${Int.toString(saved.hp)}`)
  return 0
}
You write thisalias.nra
narra
import * as Int from "std/int"

struct Player {
  name: string
  hp: int
}

function damage(mutable player: Player, amount: int) {
  player.hp = player.hp - amount
}

export function run(args: Array<string>): int uses io, alloc {
  let hero = Player { name: "Ana", hp: 100 }
  const saved = copy(hero)
  damage(mutable hero, 30)
  print(`${Int.toString(hero.hp)} ${Int.toString(saved.hp)}`)
  return 0
}
prints70 100saved kept its value

03

See what a function touches before you call it.

Every public function says whether it reads files, talks to the network or uses extra memory. You can tell which parts of a library only compute without opening them.

shop.nra
narra
import * as Fs from "std/fs"
import * as Int from "std/int"

export function total(prices: Array<int>): int {
  let sum = 0
  for (const price of prices) {
    sum = sum + price
  }
  return sum
}

export function receipt(prices: Array<int>): string uses alloc {
  return `total: ${Int.toString(total(prices))}`
}

export function save(path: string, prices: Array<int>): Result<int, string> uses io, alloc {
  return Fs.writeText(path, receipt(prices))
}
  • totalonly computes: same input, same result
  • receiptalloc: builds a new string
  • saveio, alloc: writes a file

04

Errors that tell you how to fix them.

When something's wrong, Narra says what and where, and for many mistakes it shows the exact fix. Your editor and your AI assistant get the same help, so they can fix it too.

$ narrac check --json hello.nra{"code":"E0003","severity":"error", "message":"semicolons are not used; end the statement with a line break", "file":"hello.nra","range":{"start":[2,17],"end":[2,17]}, "fixes":[{"title":"remove the semicolon",   "edits":[{"file":"hello.nra","range":{"start":[2,17],"end":[2,18]},"text":""}]}]}

05

One small program. Nothing else to install.

Narra builds your code into a single native file. A hello world is 34 KB. Copy it to another machine and run it, with no runtime to set up first.

$ narrac build -release -o hello hello.nra$ ./hellohello$ wc -c < hello   34048

06

Learn it one step at a time.

The guide starts with your first program and adds one idea per chapter.

  1. 01Getting started
  2. 02Values and types
  3. 03Functions and closures
  4. 04Structs and enums
  5. 05Pattern matching
  6. 06Option and Result
  7. 07Traits
  8. 08Modules and packages
  9. 09Memory and mutable
  10. 10Effects and testing
  11. 11Files and the system
  12. 12Generators
  13. 13The standard library
  14. 14Async
  15. 15Threads and shared state
  16. 16Unsafe code and C
  17. 17Proofs and compile-time constants
  18. 18Tools
  19. 19Building for other systems
  20. 20Narra for TypeScript programmers