@greenpandastudios/aug-cli 0.19.0

package/docs/examples/cli-args/index.md

@@ -0,0 +1,32 @@
+---
+title: "Command-line arguments"
+generated: true
+source: "examples/cli-args"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Command-line arguments
+
+Read arguments, inspect collections, and return a process exit status.
+
+Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+
+## Project files
+
+- [`main.aug`](main.md)
+
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check examples/cli-args
+aug spec examples/cli-args
+aug run examples/cli-args
+```
+
+[Browse all examples](../index.md)

package/docs/examples/cli-args/main.md

@@ -0,0 +1,107 @@
+---
+title: "main.aug · Command-line arguments"
+generated: true
+source: "examples/cli-args/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Command-line arguments](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+try:
+    args = arguments()
+    print(value=args.length())
+    if args.length() > 0:
+        print(value=args.get(index=0))
+    numbers = List<int>(1, 2)
+    borrow numbers:
+        numbers.append(value=3)
+    print(value=numbers.get(index=2))
+catch IndexError error:
+    print(value="unexpected index failure")
+```
+
+```aug [Braces]
+try {
+    args = arguments()
+    print(value=args.length())
+    if args.length() > 0 {
+        print(value=args.get(index=0))
+    }
+    numbers = List<int>(1, 2)
+    borrow numbers {
+        numbers.append(value=3)
+    }
+    print(value=numbers.get(index=2))
+}
+catch IndexError error {
+    print(value="unexpected index failure")
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Run startup operations with checked error recovery.
+
+### Startup, in source order
+
+- Try these operations:
+  - Set `args` to call `arguments`.
+  - Call `print` with `value` = call `length` on `args`.
+  - If call `length` on `args` is greater than `0`:
+    - Call `print` with `value` = call `get` on `args` with `index` = `0`.
+  - Set `numbers` to a list of `int` containing `1`, `2`.
+  - Grant exclusive mutable access to `numbers` for this block, then end the borrow:
+    - Call `append` on `numbers` with `value` = `3`.
+  - Call `print` with `value` = call `get` on `numbers` with `index` = `2`.
+- If they fail with `IndexError`, name the failure `error` and recover:
+  - Call `print` with `value` = `"unexpected index failure"`.
+
+### Built-in operations used by this file
+
+- `List<int>.append` (`value`: `int`) → `void`: Append an element with exclusive mutable access. Read-only and owned aliases cannot be stored here. Changes the receiver.
+- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
+- `List<string>.get` (`index`: `int`) → `string`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
+- `List<string>.length` (no inputs) → `int`: Read the number of elements.
+- `arguments` (no inputs) → `List<string>`: Composition arguments. Other callables receive the Arguments capability.
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+
+[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/collections/index.md

@@ -0,0 +1,32 @@
+---
+title: "Lists, tuples, sets, and maps"
+generated: true
+source: "examples/collections"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Lists, tuples, sets, and maps
+
+Create typed collections and update them through checked mutable access.
+
+Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+
+## Project files
+
+- [`main.aug`](main.md)
+
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check examples/collections
+aug spec examples/collections
+aug run examples/collections
+```
+
+[Browse all examples](../index.md)

package/docs/examples/collections/main.md

@@ -0,0 +1,118 @@
+---
+title: "main.aug · Lists, tuples, sets, and maps"
+generated: true
+source: "examples/collections/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Lists, tuples, sets, and maps](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+try:
+    numbers = List<int>(2, 4)
+    borrow numbers:
+        numbers.append(value=6)
+    print(value=numbers.length())
+    print(value=numbers.get(index=1))
+    scores = Map<string, int>()
+    borrow scores:
+        scores.set(value=42, key="ada")
+    print(value=scores.contains(key="ada"))
+    print(value=scores.get(key="ada"))
+    print(value=scores.length())
+catch IndexError error:
+    print(value="unexpected index failure")
+```
+
+```aug [Braces]
+try {
+    numbers = List<int>(2, 4)
+    borrow numbers {
+        numbers.append(value=6)
+    }
+    print(value=numbers.length())
+    print(value=numbers.get(index=1))
+    scores = Map<string, int>()
+    borrow scores {
+        scores.set(value=42, key="ada")
+    }
+    print(value=scores.contains(key="ada"))
+    print(value=scores.get(key="ada"))
+    print(value=scores.length())
+}
+catch IndexError error {
+    print(value="unexpected index failure")
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Run startup operations with checked error recovery.
+
+### Startup, in source order
+
+- Try these operations:
+  - Set `numbers` to a list of `int` containing `2`, `4`.
+  - Grant exclusive mutable access to `numbers` for this block, then end the borrow:
+    - Call `append` on `numbers` with `value` = `6`.
+  - Call `print` with `value` = call `length` on `numbers`.
+  - Call `print` with `value` = call `get` on `numbers` with `index` = `1`.
+  - Set `scores` to an empty map from `string` to `int`.
+  - Grant exclusive mutable access to `scores` for this block, then end the borrow:
+    - Call `set` on `scores` with `value` = `42`; `key` = `"ada"`.
+  - Call `print` with `value` = call `contains` on `scores` with `key` = `"ada"`.
+  - Call `print` with `value` = call `get` on `scores` with `key` = `"ada"`.
+  - Call `print` with `value` = call `length` on `scores`.
+- If they fail with `IndexError`, name the failure `error` and recover:
+  - Call `print` with `value` = `"unexpected index failure"`.
+
+### Built-in operations used by this file
+
+- `List<int>.append` (`value`: `int`) → `void`: Append an element with exclusive mutable access. Read-only and owned aliases cannot be stored here. Changes the receiver.
+- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
+- `List<int>.length` (no inputs) → `int`: Read the number of elements.
+- `Map<string, int>.contains` (`key`: `string`) → `bool`: Check for a key, including entries whose value is null.
+- `Map<string, int>.get` (`key`: `string`) → `optional int`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
+- `Map<string, int>.length` (no inputs) → `int`: Read the number of elements.
+- `Map<string, int>.set` (`key`: `string`, `value`: `int`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+
+[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/collections-benchmark/index.md

@@ -0,0 +1,34 @@
+---
+title: "Map and Set benchmark"
+generated: true
+source: "benchmarks/collections"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Map and Set benchmark
+
+Insert, find, and iterate over 20,000 collection entries.
+
+Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+
+## Project files
+
+- [`main.aug`](main.md)
+
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check benchmarks/collections
+aug spec benchmarks/collections
+aug run benchmarks/collections
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

package/docs/examples/collections-benchmark/main.md

@@ -0,0 +1,115 @@
+---
+title: "main.aug · Map and Set benchmark"
+generated: true
+source: "benchmarks/collections/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Map and Set benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+own Map<int,int> values = {}
+own Set<int> unique = {}
+int index = 0
+while index < 20000:
+    values.set(key=index, value=index * 3)
+    unique.add(value=index)
+    index = index + 1
+int checksum = 0
+for (key, value) in values:
+    if unique.contains(value=key):
+        checksum = checksum + value
+print(value=checksum)
+print(value=values.length() == unique.length())
+```
+
+```aug [Braces]
+own Map<int,int> values = {}
+own Set<int> unique = {}
+int index = 0
+while index < 20000 {
+    values.set(key=index, value=index * 3)
+    unique.add(value=index)
+    index = index + 1
+}
+int checksum = 0
+for (key, value) in values {
+    if unique.contains(value=key) {
+        checksum = checksum + value
+    }
+}
+print(value=checksum)
+print(value=values.length() == unique.length())
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Run 8 other startup steps in source order.
+
+### Startup, in source order
+
+- Set `values` of type `Map<int,int>` to a context-typed empty collection with no items.
+- This variable owns the value.
+- Set `unique` of type `Set<int>` to a context-typed empty collection with no items.
+- This variable owns the value.
+- Set `index` of type `int` to `0`.
+- While `index` is less than `20000`, repeat:
+  - Call `set` on `values` with `key` = `index`; `value` = (`index` times `3`).
+  - Call `add` on `unique` with `value` = `index`.
+  - Set `index` to `index` plus `1`.
+  - Check the condition again before the next iteration.
+- Set `checksum` of type `int` to `0`.
+- For each `key` and `value` in a snapshot of `values`, in iteration order:
+  - If call `contains` on `unique` with `value` = `key` is true:
+    - Set `checksum` to `checksum` plus `value`.
+- Call `print` with `value` = `checksum`.
+- Call `print` with `value` = (call `length` on `values` equals call `length` on `unique`).
+
+### Built-in operations used by this file
+
+- `Map<int, int>.length` (no inputs) → `int`: Read the number of elements.
+- `Map<int, int>.set` (`key`: `int`, `value`: `int`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
+- `Set<int>.add` (`value`: `int`) → `void`: Insert a unique element with exclusive mutable access. Changes the receiver.
+- `Set<int>.contains` (`value`: `int`) → `bool`: Test structural or identity equality with a stored element.
+- `Set<int>.length` (no inputs) → `int`: Read the number of elements.
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+
+[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/cpu-benchmark/index.md

@@ -0,0 +1,34 @@
+---
+title: "CPU benchmark"
+generated: true
+source: "benchmarks/cpu"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# CPU benchmark
+
+Two million dependent integer steps with a checked result.
+
+Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+
+## Project files
+
+- [`main.aug`](main.md)
+
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check benchmarks/cpu
+aug spec benchmarks/cpu
+aug run benchmarks/cpu
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

package/docs/examples/cpu-benchmark/main.md

@@ -0,0 +1,90 @@
+---
+title: "main.aug · CPU benchmark"
+generated: true
+source: "benchmarks/cpu/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[CPU benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// A loop-carried dependency prevents removal of the computation.
+int state = 123
+int index = 0
+while index < 2000000:
+    int product = state * 48271
+    state = product - product / 2147483647 * 2147483647
+    index = index + 1
+print(value=state)
+```
+
+```aug [Braces]
+// A loop-carried dependency prevents removal of the computation.
+int state = 123
+int index = 0
+while index < 2000000 {
+    int product = state * 48271
+    state = product - product / 2147483647 * 2147483647
+    index = index + 1
+}
+print(value=state)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Run 4 other startup steps in source order.
+
+### Startup, in source order
+
+- Set `state` of type `int` to `123`.
+- Set `index` of type `int` to `0`.
+- While `index` is less than `2000000`, repeat:
+  - Set `product` of type `int` to `state` times `48271`.
+  - Set `state` to `product` minus ((`product` divided by `2147483647`) times `2147483647`).
+  - Set `index` to `index` plus `1`.
+  - Check the condition again before the next iteration.
+- Call `print` with `value` = `state`.
+
+### Built-in operations used by this file
+
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+
+[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::