@greenpandastudios/aug-cli 0.19.0

package/docs/examples/packages-app/dependencies/packages/@example/aug-math/0.1.0/arithmetic.md

@@ -0,0 +1,117 @@
+---
+title: "packages/@example/aug-math/0.1.0/arithmetic.aug · Use a package"
+generated: true
+source: "examples/packages/app/.aug-spec/packages/@example/aug-math/0.1.0/arithmetic.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `packages/@example/aug-math/0.1.0/arithmetic.aug`
+
+[Use a package](../../../../../index.md) · Dependency source and specification
+
+This is the exact dependency version used by this example.
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+/** Add two integers. @param left First value. @param right Second value. @return Their sum. */
+add(int left, int right) returns int:
+    return left + right
+test add:
+    when "addition":
+        it "adds_two_integers":
+            assert(add(left=2, right=3) == 5)
+```
+
+```aug [Braces]
+/** Add two integers. @param left First value. @param right Second value. @return Their sum. */
+add(int left, int right) returns int {
+    return left + right
+}
+test add {
+    when "addition" {
+        it "adds_two_integers" {
+            assert(add(left=2, right=3) == 5)
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: 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
+
+- [`add`](arithmetic.md#symbol-add) is a function returning `int`.
+- [`test add`](arithmetic.md#symbol-test-20-add) is a same-file test suite.
+
+### `add` {#symbol-add}
+
+[source](arithmetic.md#code)
+
+**Inputs**
+
+- `left` (`int`) — required labeled input.
+- `right` (`int`) — required labeled input.
+
+Returns: `int`.
+
+**What it does**
+
+- Return `left` plus `right`.
+
+**Author documentation**
+
+Add two integers.
+
+**Returns** Their sum.
+
+**Parameters**
+- `left`: First value.
+- `right`: Second value.
+
+### `test add` {#symbol-test-20-add}
+
+[source](arithmetic.md#code)
+
+Same-file function tests for [`add`](arithmetic.md#symbol-add). Each case gets isolated setup and dependency bindings.
+
+#### Group `addition`
+
+##### `adds_two_integers`
+
+[source](arithmetic.md#code)
+
+- Call `assert` with (call [`add`](arithmetic.md#symbol-add) with `left` = `2`; `right` = `3` equals `5`).
+
+### Built-in operations used by this file
+
+- `assert` (`condition`: `bool`) → `void`: Assert a bool in a test case or its setup. Catching an assertion failure cannot make the case pass; every case must execute an assertion.
+
+[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/packages-app/index.md

@@ -0,0 +1,34 @@
+---
+title: "Use a package"
+generated: true
+source: "examples/packages/app"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Use a package
+
+Install the neighboring arithmetic package and import it through a local alias.
+
+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)
+
+- [`main.yaml`](main-yaml.md)
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug install examples/packages/app --offline
+aug check examples/packages/app
+aug spec examples/packages/app
+aug run examples/packages/app
+```
+
+[Browse all examples](../index.md)

package/docs/examples/packages-app/main-yaml.md

@@ -0,0 +1,18 @@
+---
+title: "main.yaml · Use a package"
+generated: true
+source: "examples/packages/app/main.yaml"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# `main.yaml`
+
+[Use a package](index.md) · Project configuration
+
+```yaml
+packages:
+  math: "../math"
+```

package/docs/examples/packages-app/main.md

@@ -0,0 +1,80 @@
+---
+title: "main.aug · Use a package"
+generated: true
+source: "examples/packages/app/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Use a package](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import add from math
+print(value=add(left=20, right=22))
+```
+
+```aug [Braces]
+import add from math
+print(value=add(left=20, right=22))
+```
+
+:::
+
+::::
+
+:::: 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 1 other startup step in source order.
+
+### Startup, in source order
+
+- Call `print` with `value` = call [`add`](dependencies/packages/%40example/aug-math/0.1.0/arithmetic.md#symbol-add) with `left` = `20`; `right` = `22`.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`add`](dependencies/packages/%40example/aug-math/0.1.0/arithmetic.md#symbol-add)
+
+Function from `math`.
+
+- [`add`](dependencies/packages/%40example/aug-math/0.1.0/arithmetic.md#symbol-add) (`left`: `int`, `right`: `int`) → `int`.
+
+### 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.
+
+::::
+
+:::::

package/docs/examples/packages-math/aug-package-json.md

@@ -0,0 +1,24 @@
+---
+title: "aug-package.json · Create a package"
+generated: true
+source: "examples/packages/math/aug-package.json"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# `aug-package.json`
+
+[Create a package](index.md) · Project configuration
+
+```json
+{
+  "format": 1,
+  "name": "@example/aug-math",
+  "version": "0.1.0",
+  "compiler": "0.19.0",
+  "source": "src",
+  "dependencies": {}
+}
+```

package/docs/examples/packages-math/index.md

@@ -0,0 +1,36 @@
+---
+title: "Create a package"
+generated: true
+source: "examples/packages/math"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Create a package
+
+Publish a small arithmetic library through export.aug and test its public surface.
+
+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
+
+- [`src/arithmetic.aug`](src/arithmetic.md)
+- [`src/export.aug`](src/export.md)
+
+- [`aug-package.json`](aug-package-json.md)
+- [`package.json`](package-json.md)
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check examples/packages/math
+aug spec examples/packages/math
+aug test examples/packages/math
+aug pack examples/packages/math
+```
+
+[Browse all examples](../index.md)

package/docs/examples/packages-math/package-json.md

@@ -0,0 +1,25 @@
+---
+title: "package.json · Create a package"
+generated: true
+source: "examples/packages/math/package.json"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# `package.json`
+
+[Create a package](index.md) · Project configuration
+
+```json
+{
+  "name": "@example/aug-math",
+  "version": "0.1.0",
+  "description": "An August package authoring example",
+  "license": "MIT",
+  "files": ["src", "aug-package.json", "README.md"],
+  "exports": { "./aug-package.json": "./aug-package.json" },
+  "dependencies": {}
+}
+```

package/docs/examples/packages-math/src/arithmetic.md

@@ -0,0 +1,121 @@
+---
+title: "src/arithmetic.aug · Create a package"
+generated: true
+source: "examples/packages/math/src/arithmetic.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `src/arithmetic.aug`
+
+[Create a package](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`src/arithmetic.aug`](arithmetic.md)
+- [`src/export.aug`](export.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+/** Add two integers. @param left First value. @param right Second value. @return Their sum. */
+add(int left, int right) returns int:
+    return left + right
+test add:
+    when "addition":
+        it "adds_two_integers":
+            assert(add(left=2, right=3) == 5)
+```
+
+```aug [Braces]
+/** Add two integers. @param left First value. @param right Second value. @return Their sum. */
+add(int left, int right) returns int {
+    return left + right
+}
+test add {
+    when "addition" {
+        it "adds_two_integers" {
+            assert(add(left=2, right=3) == 5)
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: 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
+
+- [`add`](arithmetic.md#symbol-add) is a function returning `int`.
+- [`test add`](arithmetic.md#symbol-test-20-add) is a same-file test suite.
+
+### `add` {#symbol-add}
+
+[source](arithmetic.md#code)
+
+**Inputs**
+
+- `left` (`int`) — required labeled input.
+- `right` (`int`) — required labeled input.
+
+Returns: `int`.
+
+**What it does**
+
+- Return `left` plus `right`.
+
+**Author documentation**
+
+Add two integers.
+
+**Returns** Their sum.
+
+**Parameters**
+- `left`: First value.
+- `right`: Second value.
+
+### `test add` {#symbol-test-20-add}
+
+[source](arithmetic.md#code)
+
+Same-file function tests for [`add`](arithmetic.md#symbol-add). Each case gets isolated setup and dependency bindings.
+
+#### Group `addition`
+
+##### `adds_two_integers`
+
+[source](arithmetic.md#code)
+
+- Call `assert` with (call [`add`](arithmetic.md#symbol-add) with `left` = `2`; `right` = `3` equals `5`).
+
+### Built-in operations used by this file
+
+- `assert` (`condition`: `bool`) → `void`: Assert a bool in a test case or its setup. Catching an assertion failure cannot make the case pass; every case must execute an assertion.
+
+[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/packages-math/src/export.md

@@ -0,0 +1,63 @@
+---
+title: "src/export.aug · Create a package"
+generated: true
+source: "examples/packages/math/src/export.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `src/export.aug`
+
+[Create a package](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`src/arithmetic.aug`](arithmetic.md)
+- [`src/export.aug`](export.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+export add from arithmetic
+```
+
+```aug [Braces]
+export add from arithmetic
+```
+
+:::
+
+::::
+
+:::: 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
+
+- Export `add` from this folder.
+
+### Folder exports
+
+- Export the declaration `add` from [`arithmetic.aug`](arithmetic.md#symbol-add).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

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

@@ -0,0 +1,34 @@
+---
+title: "Startup benchmark"
+generated: true
+source: "benchmarks/startup"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Startup benchmark
+
+The small program used to measure process startup.
+
+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/startup
+aug spec benchmarks/startup
+aug run benchmarks/startup
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

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

@@ -0,0 +1,68 @@
+---
+title: "main.aug · Startup benchmark"
+generated: true
+source: "benchmarks/startup/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Startup 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]
+print(value=7)
+```
+
+```aug [Braces]
+print(value=7)
+```
+
+:::
+
+::::
+
+:::: 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 1 other startup step in source order.
+
+### Startup, in source order
+
+- Call `print` with `value` = `7`.
+
+### 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.
+
+::::
+
+:::::