@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/errors/main.md

@@ -29,6 +29,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import load from errors
 try:
     print(value=load(fail=true))
@@ -37,6 +38,7 @@ catch FileError error:
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import load from errors
 try {
     print(value=load(fail=true))
@@ -54,38 +56,15 @@ catch FileError error {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Startup
 
-### In this file
+It prints [`load`](errors.md#symbol-load) with `fail` `true`. If this work raises `FileError`, it prints `"caught FileError"`.
 
-- Run startup operations with checked error recovery.
+### Dependencies
 
-### Startup, in source order
+It uses [`load`](errors.md#symbol-load) from `errors`.
 
-- Try these operations:
-  - Call `print` with `value` = call [`load`](errors.md#symbol-load) with `fail` = `true`.
-- If they fail with `FileError`, name the failure `error` and recover:
-  - Call `print` with `value` = `"caught FileError"`.
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`load`](errors.md#symbol-load)
-
-Function from `errors`.
-
-- [`load`](errors.md#symbol-load) (`fail`: `bool`) → `string`; can fail with `FileError`.
-
-### 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.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 
 ::::
 

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

@@ -0,0 +1,36 @@
+---
+title: "Checked-error benchmark"
+generated: true
+source: "benchmarks/errors"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Checked-error benchmark
+
+Interleave successful calls and caught checked failures.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+
+## Try this project
+
+[Download this project](/downloads/errors-benchmark.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd errors-benchmark
+aug check .
+aug spec .
+aug run .
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

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

@@ -0,0 +1,92 @@
+---
+title: "main.aug · Checked-error benchmark"
+generated: true
+source: "benchmarks/errors/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Checked-error benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import validate from operations
+int iterations = 20000
+int index = 0
+int checksum = 0
+int failures = 0
+while index < iterations:
+    try:
+        checksum = checksum + validate(value=index)
+    catch FileError error:
+        failures = failures + 1
+    index = index + 1
+print(value=checksum)
+print(value=failures)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import validate from operations
+int iterations = 20000
+int index = 0
+int checksum = 0
+int failures = 0
+while index < iterations {
+    try {
+        checksum = checksum + validate(value=index)
+    }
+    catch FileError error {
+        failures = failures + 1
+    }
+    index = index + 1
+}
+print(value=checksum)
+print(value=failures)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It sets `iterations` to `20000`. It sets `index`, `checksum`, and `failures` separately, each to `0`.
+
+While `index` is less than `iterations`, it tries to increase `checksum` by [`validate`](operations.md#symbol-validate) with `value` from `index`. If this work raises `FileError`, it increases `failures` by `1`. It increases `index` by `1`. After the loop, it prints `checksum`.
+
+It prints `failures`.
+
+### Dependencies
+
+It uses [`validate`](operations.md#symbol-validate) from `operations`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/errors-benchmark/operations.md

@@ -0,0 +1,65 @@
+---
+title: "operations.aug · Checked-error benchmark"
+generated: true
+source: "benchmarks/errors/operations.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `operations.aug`
+
+[Checked-error benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "operations.aug.md" explains this file. Read it before changes; refresh with aug spec.
+validate(int value) returns int unless FileError:
+    if value - value / 16 * 16 == 0:
+        throw FileError()
+    return value
+```
+
+```aug [Braces]
+// aug-spec: "operations.aug.md" explains this file. Read it before changes; refresh with aug spec.
+validate(int value) returns int unless FileError {
+    if value - value / 16 * 16 == 0 {
+        throw FileError()
+    }
+    return value
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `validate` · [source](operations.md#code) {#symbol-validate}
+
+It takes `value` as an integer. Failures can raise `FileError`.
+
+It checks that (`value` minus ((`value` divided by `16`) times `16`)) does not equal `0`. It raises a `FileError` at the first failed check. It returns `value`.
+
+::::
+
+:::::

package/docs/examples/ffi/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Declare a C operation and call it inside an unsafe block.
 
-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.
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
 
 ## Project files
 
@@ -22,12 +22,13 @@ Read a file below to see its highlighted source and the Markdown produced by `au
 
 ## Try this project
 
-From a repository checkout with August installed:
+[Download this project](/downloads/ffi.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
 
 ```sh
-aug check examples/ffi
-aug spec examples/ffi
-aug run examples/ffi
+cd ffi
+aug check .
+aug spec .
+aug run .
 ```
 
 [Browse all examples](../index.md)

package/docs/examples/ffi/main.md

@@ -29,11 +29,13 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import announce from native
 announce()
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import announce from native
 announce()
 ```
@@ -46,29 +48,13 @@ announce()
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Startup
 
-### In this file
+It calls [`announce`](native.md#symbol-announce).
 
-- Run 1 other startup step in source order.
+### Dependencies
 
-### Startup, in source order
-
-- Call [`announce`](native.md#symbol-announce).
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`announce`](native.md#symbol-announce)
-
-Function from `native`.
-
-- [`announce`](native.md#symbol-announce) (no caller inputs) → `void`; uses `C.puts`.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`announce`](native.md#symbol-announce) from `native`.
 
 ::::
 

package/docs/examples/ffi/native.md

@@ -29,15 +29,17 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "native.aug.md" explains this file. Read it before changes; refresh with aug spec.
 extern C puts(string message) returns c_int
-announce() uses C.puts:
+announce():
     unsafe:
         puts(message="hello from C FFI")
 ```
 
 ```aug [Braces]
+// aug-spec: "native.aug.md" explains this file. Read it before changes; refresh with aug spec.
 extern C puts(string message) returns c_int
-announce() uses C.puts {
+announce() {
     unsafe {
         puts(message="hello from C FFI")
     }
@@ -52,41 +54,13 @@ announce() uses C.puts {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `puts` · [source](native.md#code) {#symbol-puts}
 
-### In this file
+It takes `message` as a string. It returns `c_int`. Native C implementation; only its declared contract is visible here.
 
-- [`puts`](native.md#symbol-puts) is a function returning `c_int`.
-- [`announce`](native.md#symbol-announce) is a function.
+### `announce` · [source](native.md#code) {#symbol-announce}
 
-### `puts` {#symbol-puts}
-
-[source](native.md#code)
-
-**Inputs**
-
-- `message` (`string`) — required labeled input.
-
-Returns: `c_int`.
-
-Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.
-
-### `announce` {#symbol-announce}
-
-[source](native.md#code)
-
-Returns: no value.
-
-Capabilities: `C.puts`.
-
-**What it does**
-
-- Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:
-  - Call [`puts`](native.md#symbol-puts) with `message` = `"hello from C FFI"`.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Within an unsafe block, it calls [`puts`](native.md#symbol-puts) with `message` `"hello from C FFI"`. Native operations must satisfy their declared C contracts.
 
 ::::
 

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

@@ -0,0 +1,35 @@
+---
+title: "Floating-point benchmark"
+generated: true
+source: "benchmarks/float"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Floating-point benchmark
+
+Accumulate exact binary fractions and check the final value.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+## Project files
+
+- [`main.aug`](main.md)
+
+
+## Try this project
+
+[Download this project](/downloads/float-benchmark.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd float-benchmark
+aug check .
+aug spec .
+aug run .
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

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

@@ -0,0 +1,75 @@
+---
+title: "main.aug · Floating-point benchmark"
+generated: true
+source: "benchmarks/float/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Floating-point 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]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+int iterations = 1000000
+float sum = 0.0
+int index = 0
+while index < iterations:
+    int remainder = index - index / 8 * 8
+    sum = sum + remainder * 0.125 + 0.5
+    index = index + 1
+print(value=sum == 937500.0)
+print(value=iterations)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+int iterations = 1000000
+float sum = 0.0
+int index = 0
+while index < iterations {
+    int remainder = index - index / 8 * 8
+    sum = sum + remainder * 0.125 + 0.5
+    index = index + 1
+}
+print(value=sum == 937500.0)
+print(value=iterations)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It sets `iterations` to `1000000`. It sets `sum` to `0.0`. It sets `index` to `0`. While `index` is less than `iterations`, it sets `remainder` to `index` minus ((`index` divided by `8`) times `8`); then it sets `sum` to (`sum` plus (`remainder` times `0.125`)) plus `0.5`; then it increases `index` by `1`.
+
+After the loop, it prints `sum` equals `937500.0`. It prints `iterations`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/generic-di/dependencies/august/0.21.0/io/contracts.md

@@ -0,0 +1,178 @@
+---
+title: "august/0.21.0/io/contracts.aug · Generic dependency injection"
+generated: true
+source: "examples/generic-di/.aug-spec/august/0.21.0/io/contracts.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `august/0.21.0/io/contracts.aug`
+
+[Generic dependency injection](../../../../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]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** Permission to write to a console, provided by an explicitly selected adapter. */
+capability Console:
+    /** Write one line of text. @param value Text to display. */
+    write<T>(T value) uses Console.write
+/** The native standard-output adapter. Construction performs no output. */
+SystemConsole() implements Console:
+    write<T>(T value):
+        print(value=value)
+/** Read UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileReader:
+    /** Read text. @param path File path. @throws FileError The file could not be read. */
+    read(string path) returns string uses FileReader.read unless FileError
+/** Write UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileWriter:
+    /** Write text. @param path File path. @param content Text. @throws FileError Writing failed. */
+    write(string path, string content) uses FileWriter.write unless FileError
+/** Native files. Operations are explicit; construction opens no files. */
+LocalFiles() implements FileReader, FileWriter:
+    read(string path):
+        return read_file(path=path)
+    write(string path, string content):
+        write_file(path=path, content=content)
+/** Read command-line input through an explicit dependency. */
+capability Arguments:
+    read() returns List<string> uses Arguments.read
+/** Native command-line arguments. */
+ProcessArguments() implements Arguments:
+    read():
+        return arguments()
+```
+
+```aug [Braces]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** Permission to write to a console, provided by an explicitly selected adapter. */
+capability Console {
+    /** Write one line of text. @param value Text to display. */
+    write<T>(T value) uses Console.write
+}
+/** The native standard-output adapter. Construction performs no output. */
+SystemConsole() implements Console {
+    write<T>(T value) {
+        print(value=value)
+    }
+}
+/** Read UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileReader {
+    /** Read text. @param path File path. @throws FileError The file could not be read. */
+    read(string path) returns string uses FileReader.read unless FileError
+}
+/** Write UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileWriter {
+    /** Write text. @param path File path. @param content Text. @throws FileError Writing failed. */
+    write(string path, string content) uses FileWriter.write unless FileError
+}
+/** Native files. Operations are explicit; construction opens no files. */
+LocalFiles() implements FileReader, FileWriter {
+    read(string path) {
+        return read_file(path=path)
+    }
+    write(string path, string content) {
+        write_file(path=path, content=content)
+    }
+}
+/** Read command-line input through an explicit dependency. */
+capability Arguments {
+    read() returns List<string> uses Arguments.read
+}
+/** Native command-line arguments. */
+ProcessArguments() implements Arguments {
+    read() {
+        return arguments()
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `Console` · capability interface · [source](contracts.md#code) {#symbol-Console}
+
+Permission to write to a console, provided by an explicitly selected adapter.
+
+#### `Console.write` · [source](contracts.md#code) {#symbol-Console.write}
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It can call [`Console.write`](contracts.md#symbol-Console.write).
+
+### `SystemConsole` · class · [source](contracts.md#code) {#symbol-SystemConsole}
+
+The native standard-output adapter. Construction performs no output. It implements [`Console`](contracts.md#symbol-Console).
+
+#### `SystemConsole.write` · [source](contracts.md#code) {#symbol-SystemConsole.write}
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It prints `value`.
+
+### `FileReader` · capability interface · [source](contracts.md#code) {#symbol-FileReader}
+
+Read UTF-8 text through an explicitly selected filesystem adapter.
+
+#### `FileReader.read` · [source](contracts.md#code) {#symbol-FileReader.read}
+
+Read text. It takes `path` as a string (File path).
+
+It returns `string`. It can call [`FileReader.read`](contracts.md#symbol-FileReader.read). Failures can raise `FileError` (The file could not be read).
+
+### `FileWriter` · capability interface · [source](contracts.md#code) {#symbol-FileWriter}
+
+Write UTF-8 text through an explicitly selected filesystem adapter.
+
+#### `FileWriter.write` · [source](contracts.md#code) {#symbol-FileWriter.write}
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). It can call [`FileWriter.write`](contracts.md#symbol-FileWriter.write). Failures can raise `FileError` (Writing failed).
+
+### `LocalFiles` · class · [source](contracts.md#code) {#symbol-LocalFiles}
+
+Native files. Operations are explicit; construction opens no files. It implements [`FileReader`](contracts.md#symbol-FileReader) and [`FileWriter`](contracts.md#symbol-FileWriter).
+
+#### `LocalFiles.read` · [source](contracts.md#code) {#symbol-LocalFiles.read}
+
+Read text. It takes `path` as a string (File path). Failures can raise `FileError` (The file could not be read). It returns `read_file` with `path`.
+
+#### `LocalFiles.write` · [source](contracts.md#code) {#symbol-LocalFiles.write}
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). Failures can raise `FileError` (Writing failed). It calls `write_file` with `path` and `content`.
+
+### `Arguments` · capability interface · [source](contracts.md#code) {#symbol-Arguments}
+
+Read command-line input through an explicit dependency.
+
+#### `Arguments.read` · [source](contracts.md#code) {#symbol-Arguments.read}
+
+It returns `List<string>`. It can call [`Arguments.read`](contracts.md#symbol-Arguments.read).
+
+### `ProcessArguments` · class · [source](contracts.md#code) {#symbol-ProcessArguments}
+
+Native command-line arguments. It implements [`Arguments`](contracts.md#symbol-Arguments).
+
+#### `ProcessArguments.read` · [source](contracts.md#code) {#symbol-ProcessArguments.read}
+
+It returns `arguments`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::