Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@ it somewhere on your `PATH`.

```sh
# macOS on Apple silicon; swap the version and platform for yours
curl -LO https://github.com/kryptamine/rune/releases/download/v0.1.0/rune-0.1.0-darwin-arm64.tar.gz
tar -xzf rune-0.1.0-darwin-arm64.tar.gz
sudo mv rune-0.1.0-darwin-arm64/rune /usr/local/bin/
curl -LO https://github.com/kryptamine/rune/releases/download/v0.3.0/rune-0.3.0-darwin-arm64.tar.gz
tar -xzf rune-0.3.0-darwin-arm64.tar.gz
sudo mv rune-0.3.0-darwin-arm64/rune /usr/local/bin/
rune version
```

Expand Down
33 changes: 26 additions & 7 deletions docs/src/contributing/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,36 @@

```sh
make test # all tests
make test filter=arrays # scripts under test/arrays
make test filter=arrays # only the scripts under test/arrays
make update # rewrite golden files after an intended change
make cover # coverage
make fuzz FUZZTIME=1m # fuzz the whole pipeline
```

Each `test/**/*.rn` script runs in-process, in parallel, with a 5s timeout. Directives in comments:
## Script tests

- `// expect: <line>` — next line of stdout;
- `// [line: N] Error...` — compile error, in order; without `[line: N]` it is the comment's line;
- `// expect runtime error: [line: N] <message>` — uncaught runtime error.
Most tests are Rune scripts, `test/**/*.rn`. Each runs in-process, in
parallel with the others, with a 5 second timeout. Comments in the script
say what it must do:

`foo.stderr` next to `foo.rn` holds the full error report (snippet, caret, trace); a missing file means empty stderr.
`testdata/<command>/*.rn` are run through the CLI command (`run`, `disasm`, `fmt`) and compared with `.golden` files: exit code, stdout and stderr.
- `// expect: <text>` — the next line of stdout.
- `// Error...` — a compile error on this line. Compile errors are
checked in order; `// [line: N] Error...` puts one on line `N`.
- `// expect runtime error: [line: N] <message>` — the uncaught runtime
error the script ends with.

```rune
let prices = [30, 120];
print(prices.len()); // expect: 2
print(prices[5]); // expect runtime error: [line: 3] IndexError: Index out of bounds: 5 of 2
```

A file `name.stderr` next to `name.rn` holds the full error report the
script prints: the snippet, the caret and the trace. No such file means
stderr must be empty. `make update` writes these files.

## CLI tests

`testdata/<command>/*.rn` run through the CLI command of their directory,
`run`, `disasm` or `fmt`. Each is compared with its `.golden` file, which
holds the exit code, stdout and stderr.
196 changes: 141 additions & 55 deletions docs/src/data/arrays.md
Original file line number Diff line number Diff line change
@@ -1,36 +1,55 @@
# Arrays

An array is an ordered list of values of any type. `xs[i]` reads element
`i`, counting from `0`, and `xs.len()` is the number of elements.
An array is an ordered list of values. Write one with square brackets; the
elements may be of any type, mixed freely.

```rune
let langs = ["go", "rust", "rune"];
print(langs[0]); // go
print(langs.len()); // 3
print(langs); // ["go", "rust", "rune"]
print(langs.len()); // 3

let row = [1, 2.5, "three", true, nil, [4]];
print(row); // [1, 2.5, "three", true, nil, [4]]
print(row); // [1, 2.5, "three", true, nil, [4]]
```

## Indexing

`xs[i]` reads the element at index `i`, counting from `0`. A negative index
counts from the end, so `xs[-1]` is the last element. Arrays nest, and
indexes chain.

```rune
let langs = ["go", "rust", "rune"];
print(langs[0]); // go
print(langs[-1]); // rune

let grid = [[1, 2], [3, 4]];
print(grid[1][0]); // 3
print(grid[1][0]); // 3
```

An index must be an integer from `-xs.len()` to `xs.len() - 1`; a negative one
counts from the end, as in strings, bytes, slices and `remove`. One out of
bounds is an `IndexError`, for reading and writing alike. To grow an array,
`push` to it.
An index must be an integer from `-xs.len()` to `xs.len() - 1`. Anything
outside is an `IndexError`, for reading and writing alike:

```rune
let langs = ["go", "rust", "rune"];
print(langs[-1]); // rune
print(langs[3]); // IndexError: Index out of bounds: 3 of 3
print(langs[3]); // IndexError: Index out of bounds: 3 of 3
```

`xs[a..b]` is a new array of the elements from `a` up to `b`, `xs[a..=b]`
up to `b` included; either bound may be left out, and a negative one
counts from the end. Bounds past either end are clamped, so a slice is
never an error but may be empty. `x in xs` tests for an element (see
[Membership](../language/values.md#membership)).
When an element may be missing, read it with `?.[i]`, which gives `nil`
instead, and pick a fallback with `??` (see [Nil Safety](../language/nil-safety.md)):

```rune
let args = ["report.csv"];
print(args?.[0] ?? "stdin"); // report.csv
print(args?.[1] ?? "out.txt"); // out.txt
```

## Slices

`xs[a..b]` is a new array of the elements from index `a` up to, but not
including, `b`; `xs[a..=b]` includes `b`. Either bound may be left out,
and a negative bound counts from the end. Bounds past either end are
clamped, so a slice is never an error, though it may be empty.

```rune
let xs = [10, 20, 30, 40, 50];
Expand All @@ -40,82 +59,149 @@ print(xs[..2]); // [10, 20]
print(xs[-2..]); // [40, 50]
print(xs[..-1]); // [10, 20, 30, 40]
print(xs[3..99]); // [40, 50]
print(30 in xs); // true
```

Writing an element needs a mutable variable (see [Variables](../language/variables.md)):
`x in xs` tests whether an element is in the array, comparing with `==`
(see [Membership](../language/values.md#membership)):

```rune
let admins = ["ann", "bob"];
print("ann" in admins); // true
print("eve" in admins); // false
```

## Changing an Array

Changing an array needs a mutable variable (see
[Variables](../language/variables.md)). Assign to an index to replace an
element, and `push` to add one at the end; an index cannot grow the array.

```rune
let mut scores = [70, 85, 90];
scores[0] = 75;
scores[1] += 5;
scores.push(100);
print(scores); // [75, 90, 90, 100]
print(scores); // [75, 90, 90, 100]
print(scores.pop()); // 100
print(scores); // [75, 90, 90]
```

`for x in xs` walks the elements, `for i, x in xs` the indices too. The
elements are taken when the loop starts, so pushing inside the loop does not
extend it.
`insert`, `remove`, `sort`, `reverse` and the other
[array methods](../stdlib/array.md) are listed in the standard library.

## Iterating

`for x in xs` walks the elements; `for i, x in xs` gives the index too.

```rune
let todo = ["write docs", "fix bug"];
let todo = ["write docs", "fix bug", "release"];
for i, task in todo {
print("{i + 1}. {task}");
}
// 1. write docs
// 2. fix bug
// 3. release
```

`==` compares arrays element by element:
The loop walks the array as it was when the loop began, so pushing inside
the body does not make it run longer:

```rune
print([1, [2, 3]] == [1, [2, 3]]); // true
print([1, 2] == [2, 1]); // false
let mut queue = ["build"];
for job in queue {
queue.push("after " + job);
}
print(queue); // ["build", "after build"]
```

Arrays are values, like numbers and strings: assigning one, passing it to
a function, returning it or storing it in an element or a property gives
an independent copy. `push`, `pop` and index assignment change only the
array they are called on.
## Equality

`==` compares arrays element by element, nested ones included. Order
matters.

```rune
print([1, [2, 3]] == [1, [2, 3]]); // true
print([1, 2] == [2, 1]); // false
```

## Arrays Are Values

An array behaves like a number or a string: assigning it, passing it to a
function, returning it or storing it somewhere gives an independent copy.
Changing the copy never changes the original.

```rune
let defaults = ["read"];
let mut perms = defaults;
perms.push("write");
print(defaults); // ["read"]
print(perms); // ["read", "write"]
```

So a function cannot change the caller's array by accident. It works on
its own copy and returns the result:

```rune
let a = [1, 2];
let mut b = a;
b.push(3);
print(a); // [1, 2]
print(b); // [1, 2, 3]

fun grow(xs) { let mut ys = xs; ys.push(0); return ys; }
print(grow(a)); // [1, 2, 0]
print(a); // [1, 2]
fun withTax(prices) {
let mut out = prices;
for i, p in out {
out[i] = p * 1.2;
}
out
}

let prices = [10, 25];
print(withTax(prices)); // [12, 30]
print(prices); // [10, 25]
```

When a function should change the caller's array, mark the parameter
[`mut`](../language/functions.md#mut-parameters):

```rune
fun addTag(mut tags, tag) {
if !(tag in tags) {
tags.push(tag);
}
}

let mut tags = ["new"];
addTag(tags, "sale");
addTag(tags, "sale");
print(tags); // ["new", "sale"]
```

A copy costs nothing until it is written: the array is copied on its first
change, and only if something else still holds it.
Copies are cheap: an array is copied only when it is written and something
else still holds it, so passing a large array around costs nothing.

A write along a path, as in `grid[0][1] = 9` or `grid[0].push(9)`, changes
only the array at the end of it: a copy taken earlier of any array on the
way keeps its value.
only the array it goes through. Copies taken earlier of any part keep their
values:

```rune
let mut grid = [[0, 0], [0, 0]];
let row = grid[0];
let before = grid;
grid[0][1] = 9;
print(row); // [0, 0]
print(before); // [[0, 0], [0, 0]]
print(grid); // [[0, 9], [0, 0]]
print(grid); // [[0, 9], [0, 0]]
print(row); // [0, 0]
print(before); // [[0, 0], [0, 0]]
```

A function changes the caller's array only through a
[`mut` parameter](../language/functions.md#mut-parameters).
## Transforming

`map`, `filter`, `sort`, `join` and the rest are
[array methods](../stdlib/array.md).
`map`, `filter`, `reduce` and friends return new arrays, which makes
chains of them read like a pipeline. All of them are in
[Array Methods](../stdlib/array.md).

```rune
let prices = [12, 5, 30, 8];
print(prices.map(p => p * 2)); // [24, 10, 60, 16]
print(prices.filter(p => p > 10)); // [12, 30]
print(prices.reduce((a, b) => a + b)); // 55
let orders = [
{ id: 1, total: 30 },
{ id: 2, total: 120 },
{ id: 3, total: 75 },
];

let big = orders.filter(o => o.total > 50).map(o => o.id);
print(big); // [2, 3]
print(orders.reduce((sum, o) => sum + o.total, 0)); // 225
```
Loading
Loading