@greenpandastudios/aug-cli 0.19.0

package/docs/examples/json-benchmark/dependencies/august/0.19.0/json/contracts.md

@@ -0,0 +1,103 @@
+---
+title: "august/0.19.0/json/contracts.aug · JSON benchmark"
+generated: true
+source: "benchmarks/json/.aug-spec/august/0.19.0/json/contracts.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `august/0.19.0/json/contracts.aug`
+
+[JSON benchmark](../../../../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]
+extern C value pure _aug_json_parse(string input) returns Json unless JsonError
+/** Parse strict UTF-8 JSON. Duplicate keys, invalid Unicode, oversized integers, and nesting beyond 64 levels raise JsonError. */
+parse(string input) returns Json unless JsonError:
+    unsafe:
+        return _aug_json_parse(input)
+```
+
+```aug [Braces]
+extern C value pure _aug_json_parse(string input) returns Json unless JsonError
+/** Parse strict UTF-8 JSON. Duplicate keys, invalid Unicode, oversized integers, and nesting beyond 64 levels raise JsonError. */
+parse(string input) returns Json unless JsonError {
+    unsafe {
+        return _aug_json_parse(input)
+    }
+}
+```
+
+:::
+
+::::
+
+:::: 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
+
+- [`_aug_json_parse`](contracts.md#symbol-_aug_json_parse) is a function returning `Json`.
+- [`parse`](contracts.md#symbol-parse) is a function returning `Json`.
+
+### `parse` {#symbol-parse}
+
+[source](contracts.md#code)
+
+**Inputs**
+
+- `input` (`string`) — required labeled input.
+
+Returns: `Json`.
+
+Can fail with `JsonError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:
+  - Return call [`_aug_json_parse`](contracts.md#symbol-_aug_json_parse) with `input` = `input`.
+
+**Author documentation**
+
+Parse strict UTF-8 JSON. Duplicate keys, invalid Unicode, oversized integers, and nesting beyond 64 levels raise JsonError.
+
+### `_aug_json_parse` {#symbol-_aug_json_parse}
+
+[source](contracts.md#code)
+
+Private to its defining scope.
+
+**Inputs**
+
+- `input` (`string`) — required labeled input.
+
+Returns: `Json`.
+
+Can fail with `JsonError`. Callers must catch or propagate these errors.
+
+Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

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

@@ -0,0 +1,35 @@
+---
+title: "JSON benchmark"
+generated: true
+source: "benchmarks/json"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# JSON benchmark
+
+Parse, decode, and serialize a typed record 5,000 times.
+
+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)
+- [`data.aug`](data.md)
+
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check benchmarks/json
+aug spec benchmarks/json
+aug run benchmarks/json
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

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

@@ -0,0 +1,131 @@
+---
+title: "main.aug · JSON benchmark"
+generated: true
+source: "benchmarks/json/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[JSON benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`data.aug`](data.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import parse from august.json
+import Payload from data
+int checksum = 0
+int index = 0
+try:
+    while index < 5000:
+        document = parse(input="{\"id\":7,\"message\":\"hello\",\"values\":[1,2,3]}")
+        payload = document.decode<Payload>()
+        encoded = Json(value=payload).stringify()
+        checksum = checksum + payload.id + encoded.length()
+        index = index + 1
+    print(value=checksum)
+catch JsonError error:
+    exit(status=1)
+```
+
+```aug [Braces]
+import parse from august.json
+import Payload from data
+int checksum = 0
+int index = 0
+try {
+    while index < 5000 {
+        document = parse(input="{\"id\":7,\"message\":\"hello\",\"values\":[1,2,3]}")
+        payload = document.decode<Payload>()
+        encoded = Json(value=payload).stringify()
+        checksum = checksum + payload.id + encoded.length()
+        index = index + 1
+    }
+    print(value=checksum)
+}
+catch JsonError error {
+    exit(status=1)
+}
+```
+
+:::
+
+::::
+
+:::: 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.
+- Run 2 other startup steps in source order.
+
+### Startup, in source order
+
+- Set `checksum` of type `int` to `0`.
+- Set `index` of type `int` to `0`.
+- Try these operations:
+  - While `index` is less than `5000`, repeat:
+    - Set `document` to call [`parse`](dependencies/august/0.19.0/json/contracts.md#symbol-parse) with `input` = `"{\"id\":7,\"message\":\"hello\",\"values\":[1,2,3]}"`.
+    - Set `payload` to call `decode` on `document` with type arguments [`Payload`](data.md#symbol-Payload).
+    - Set `encoded` to call `stringify` on call `Json` with `value` = `payload`.
+    - Set `checksum` to (`checksum` plus `id` of `payload`) plus call `length` on `encoded`.
+    - Set `index` to `index` plus `1`.
+    - Check the condition again before the next iteration.
+  - Call `print` with `value` = `checksum`.
+- If they fail with `JsonError`, name the failure `error` and recover:
+  - Call `exit` with `status` = `1`.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`parse`](dependencies/august/0.19.0/json/contracts.md#symbol-parse)
+
+Function from `august.json`.
+
+- [`parse`](dependencies/august/0.19.0/json/contracts.md#symbol-parse) (`input`: `string`) → `Json`; can fail with `JsonError`.
+
+#### [`Payload`](data.md#symbol-Payload)
+
+Record from `data`.
+
+- Read `id` (`int`).
+
+### Built-in operations used by this file
+
+- `Json.decode` (no inputs) → `Payload`: Decode a checked record or data type: json.decode<Profile>(). Unknown fields, type mismatches, and validation errors are rejected. Can fail with `JsonError`.
+- `Json.stringify` (no inputs) → `string`: Serialize this JSON value with checked UTF-8 escaping and exact int64 values. Can fail with `JsonError`.
+- `exit` (`status`: `int`) → `void`: Exit from main with a status from 0 to 255 after cancellation and cleanup.
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+- `string.length` (no inputs) → `int`: Read the number of UTF-8 bytes. Unicode text is preserved losslessly.
+
+[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/new-syntax/console.md

@@ -0,0 +1,118 @@
+---
+title: "console.aug · Labeled calls and injection"
+generated: true
+source: "examples/new-syntax/console.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `console.aug`
+
+[Labeled calls and injection](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`console.aug`](console.md)
+- [`greeter.aug`](greeter.md)
+- [`logger.aug`](logger.md)
+- [`math.aug`](math.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import Console from august.io
+import Logger from logger
+ConsoleLogger() implements Logger:
+    log(resolve Console console, string message) uses Console.write:
+        console.write(value=message)
+```
+
+```aug [Braces]
+import Console from august.io
+import Logger from logger
+ConsoleLogger() implements Logger {
+    log(resolve Console console, string message) uses Console.write {
+        console.write(value=message)
+    }
+}
+```
+
+:::
+
+::::
+
+:::: 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
+
+- [`ConsoleLogger`](console.md#symbol-ConsoleLogger) is a class implementing `Logger`.
+
+### `ConsoleLogger` {#symbol-ConsoleLogger}
+
+[source](console.md#code)
+
+Behavioral class.
+
+Satisfies [`Logger`](logger.md#symbol-Logger).
+
+#### `ConsoleLogger.log` {#symbol-ConsoleLogger.log}
+
+[source](console.md#code)
+
+**Inputs**
+
+- `console` ([`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
+- `message` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
+
+**What it does**
+
+- Call [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write) on `console` with `value` = `message`.
+
+**Author documentation**
+
+**Parameters**
+- `message`: Text to display.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)
+
+Capability interface from `august.io`.
+
+- [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+
+#### [`Logger`](logger.md#symbol-Logger)
+
+Interface from `logger`.
+
+Used as a type or provider.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::