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 | shimport * 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.
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}
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.
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
}
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
}
70 100saved kept its value03
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.
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 resultreceiptalloc: builds a new stringsaveio, 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.
- 01Getting started
- 02Values and types
- 03Functions and closures
- 04Structs and enums
- 05Pattern matching
- 06Option and Result
- 07Traits
- 08Modules and packages
- 09Memory and mutable
- 10Effects and testing
- 11Files and the system
- 12Generators
- 13The standard library
- 14Async
- 15Threads and shared state
- 16Unsafe code and C
- 17Proofs and compile-time constants
- 18Tools
- 19Building for other systems
- 20Narra for TypeScript programmers