@greenpandastudios/aug-cli 0.19.0

package/docs/examples/interceptors/interceptors.md

@@ -0,0 +1,284 @@
+---
+title: "interceptors.aug · Function and constructor middleware"
+generated: true
+source: "examples/interceptors/interceptors.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `interceptors.aug`
+
+[Function and constructor middleware](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`app.aug`](app.md)
+- [`interceptors.aug`](interceptors.md)
+- [`logging.aug`](logging.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import Console from august.io
+import Logger from logging
+/** Raised when a numeric input fails validation. */
+ValidationError(string message) implements Error:
+    pass
+/**
+* Logs before and after a successful call.
+* Generic T is inferred from the annotated function or constructor.
+* @param logger Shared application logger, injected for each fresh instance.
+*/
+interceptor Audit<T>(resolve Logger logger):
+    /** Wrap a call without changing its result. */
+    around(resolve Console console) returns T uses Console.write:
+        logger.log(message="before")
+        T result = next()
+        logger.log(message="after")
+        return result
+/** Rejects negative numbers before the target executes. */
+interceptor Positive<T>():
+    /**
+    * @param y The target argument selected by a mapping such as y=x.
+    * @throws ValidationError When the selected value is negative.
+    */
+    around(int y) returns T unless ValidationError:
+        if y < 0:
+            throw ValidationError(message="value must be nonnegative")
+        return next()
+/** Adds one to the selected input before forwarding the call. */
+interceptor AddOne<T>():
+    /** @param y The input to increment. */
+    around(int y) returns T:
+        return next(y=y + 1)
+```
+
+```aug [Braces]
+import Console from august.io
+import Logger from logging
+/** Raised when a numeric input fails validation. */
+ValidationError(string message) implements Error {
+    pass
+}
+/**
+* Logs before and after a successful call.
+* Generic T is inferred from the annotated function or constructor.
+* @param logger Shared application logger, injected for each fresh instance.
+*/
+interceptor Audit<T>(resolve Logger logger) {
+    /** Wrap a call without changing its result. */
+    around(resolve Console console) returns T uses Console.write {
+        logger.log(message="before")
+        T result = next()
+        logger.log(message="after")
+        return result
+    }
+}
+/** Rejects negative numbers before the target executes. */
+interceptor Positive<T>() {
+    /**
+    * @param y The target argument selected by a mapping such as y=x.
+    * @throws ValidationError When the selected value is negative.
+    */
+    around(int y) returns T unless ValidationError {
+        if y < 0 {
+            throw ValidationError(message="value must be nonnegative")
+        }
+        return next()
+    }
+}
+/** Adds one to the selected input before forwarding the call. */
+interceptor AddOne<T>() {
+    /** @param y The input to increment. */
+    around(int y) returns T {
+        return next(y=y + 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
+
+- [`ValidationError`](interceptors.md#symbol-ValidationError) is a class implementing `Error`.
+- [`Audit`](interceptors.md#symbol-Audit) is an interceptor.
+- [`Positive`](interceptors.md#symbol-Positive) is an interceptor.
+- [`AddOne`](interceptors.md#symbol-AddOne) is an interceptor.
+
+### `ValidationError` {#symbol-ValidationError}
+
+[source](interceptors.md#code)
+
+Behavioral class.
+
+Satisfies `Error`.
+
+**Author documentation**
+
+Raised when a numeric input fails validation.
+
+**Inputs**
+
+- `message` (`string`) — required labeled input — stored as `message` and read-only after initialization.
+
+### `Audit` {#symbol-Audit}
+
+[source](interceptors.md#code)
+
+Function or constructor middleware.
+
+Type parameters: `T`.
+
+**Author documentation**
+
+Logs before and after a successful call.
+Generic T is inferred from the annotated function or constructor.
+
+**Parameters**
+- `logger`: Shared application logger, injected for each fresh instance.
+
+**Inputs**
+
+- `logger` ([`Logger`](logging.md#symbol-Logger)) — injected; callers omit it — stored as `logger` and read-only after initialization.
+
+Create a fresh interceptor for each invocation. Its around operation can delegate once, change selected inputs, or short-circuit with a compatible result or failure.
+
+#### `Audit.around` {#symbol-Audit.around}
+
+[source](interceptors.md#code)
+
+**Inputs**
+
+- `console` ([`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
+
+Returns: `T`.
+
+Capabilities: [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
+
+**What it does**
+
+- Call [`Logger.log`](logging.md#symbol-Logger.log) on `logger` with `message` = `"before"`; inject `console` from `console`.
+- Set `result` of type `T` to call `next`.
+- Call [`Logger.log`](logging.md#symbol-Logger.log) on `logger` with `message` = `"after"`; inject `console` from `console`.
+- Return `result`.
+
+**Author documentation**
+
+Wrap a call without changing its result.
+
+### `Positive` {#symbol-Positive}
+
+[source](interceptors.md#code)
+
+Function or constructor middleware.
+
+Type parameters: `T`.
+
+**Author documentation**
+
+Rejects negative numbers before the target executes.
+
+Create a fresh interceptor for each invocation. Its around operation can delegate once, change selected inputs, or short-circuit with a compatible result or failure.
+
+#### `Positive.around` {#symbol-Positive.around}
+
+[source](interceptors.md#code)
+
+**Inputs**
+
+- `y` (`int`) — required labeled input.
+
+Returns: `T`.
+
+Can fail with `ValidationError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- If `y` is less than `0`:
+  - Fail with call [`ValidationError`](interceptors.md#symbol-ValidationError) with `message` = `"value must be nonnegative"`. Transfer control to a matching catch or propagate the failure.
+- Return call `next`.
+
+**Author documentation**
+
+**Parameters**
+- `y`: The target argument selected by a mapping such as y=x.
+
+**Throws**
+- `ValidationError`: When the selected value is negative.
+
+### `AddOne` {#symbol-AddOne}
+
+[source](interceptors.md#code)
+
+Function or constructor middleware.
+
+Type parameters: `T`.
+
+**Author documentation**
+
+Adds one to the selected input before forwarding the call.
+
+Create a fresh interceptor for each invocation. Its around operation can delegate once, change selected inputs, or short-circuit with a compatible result or failure.
+
+#### `AddOne.around` {#symbol-AddOne.around}
+
+[source](interceptors.md#code)
+
+**Inputs**
+
+- `y` (`int`) — required labeled input.
+
+Returns: `T`.
+
+**What it does**
+
+- Return call `next` with `y` = (`y` plus `1`).
+
+**Author documentation**
+
+**Parameters**
+- `y`: The input to increment.
+
+### 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`](logging.md#symbol-Logger)
+
+Interface from `logging`.
+
+- [`Logger.log`](logging.md#symbol-Logger.log) (`message`: `string`) → `void`; inject `console`: [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console); uses [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/interceptors/logging.md

@@ -0,0 +1,155 @@
+---
+title: "logging.aug · Function and constructor middleware"
+generated: true
+source: "examples/interceptors/logging.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `logging.aug`
+
+[Function and constructor middleware](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`app.aug`](app.md)
+- [`interceptors.aug`](interceptors.md)
+- [`logging.aug`](logging.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import Console from august.io
+/** Writes a message to the application log. */
+interface Logger:
+    /** @param message Text to display. */
+    log(resolve Console console, string message) uses Console.write
+/** Console logger shared by interceptor instances and the application. */
+ConsoleLogger() implements Logger:
+    log(resolve Console console, string message) uses Console.write:
+        console.write(value=message)
+```
+
+```aug [Braces]
+import Console from august.io
+/** Writes a message to the application log. */
+interface Logger {
+    /** @param message Text to display. */
+    log(resolve Console console, string message) uses Console.write
+}
+/** Console logger shared by interceptor instances and the application. */
+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
+
+- [`Logger`](logging.md#symbol-Logger) is an interface.
+- [`ConsoleLogger`](logging.md#symbol-ConsoleLogger) is a class implementing `Logger`.
+
+### `Logger` {#symbol-Logger}
+
+[source](logging.md#code)
+
+Interface.
+
+**Author documentation**
+
+Writes a message to the application log.
+
+#### `Logger.log` {#symbol-Logger.log}
+
+[source](logging.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).
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+**Parameters**
+- `message`: Text to display.
+
+### `ConsoleLogger` {#symbol-ConsoleLogger}
+
+[source](logging.md#code)
+
+Behavioral class.
+
+Satisfies [`Logger`](logging.md#symbol-Logger).
+
+**Author documentation**
+
+Console logger shared by interceptor instances and the application.
+
+#### `ConsoleLogger.log` {#symbol-ConsoleLogger.log}
+
+[source](logging.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`.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/interceptors/main.md

@@ -0,0 +1,162 @@
+---
+title: "main.aug · Function and constructor middleware"
+generated: true
+source: "examples/interceptors/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Function and constructor middleware](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`app.aug`](app.md)
+- [`interceptors.aug`](interceptors.md)
+- [`logging.aug`](logging.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import Console and SystemConsole from august.io
+implement Console with SystemConsole
+import Logger from logging
+import ConsoleLogger from logging
+import Greeter from app
+import describe from app
+import ValidationError from interceptors
+implement Logger with ConsoleLogger
+try:
+    print(value=describe(label="value", x=6))
+catch ValidationError error:
+    print(value="rejected")
+greeter = Greeter(name="AugScript")
+print(value=greeter.greet())
+try:
+    describe(x=-1, label="invalid")
+catch ValidationError error:
+    print(value="rejected")
+```
+
+```aug [Braces]
+import Console and SystemConsole from august.io
+implement Console with SystemConsole
+import Logger from logging
+import ConsoleLogger from logging
+import Greeter from app
+import describe from app
+import ValidationError from interceptors
+implement Logger with ConsoleLogger
+try {
+    print(value=describe(label="value", x=6))
+}
+catch ValidationError error {
+    print(value="rejected")
+}
+greeter = Greeter(name="AugScript")
+print(value=greeter.greet())
+try {
+    describe(x=-1, label="invalid")
+}
+catch ValidationError error {
+    print(value="rejected")
+}
+```
+
+:::
+
+::::
+
+:::: 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
+
+- Register 2 dependency providers before startup.
+- Run startup operations with checked error recovery.
+- Run 2 other startup steps in source order.
+
+### Dependency providers
+
+Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+
+- Provide [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
+- Provide [`ConsoleLogger`](logging.md#symbol-ConsoleLogger) when `Logger` is requested. Reuse one instance.
+
+### Startup, in source order
+
+- Try these operations:
+  - Call `print` with `value` = call [`describe`](app.md#symbol-describe) with `label` = `"value"`; `x` = `6`; inject `logger` from `Logger`, `console` from `Console`.
+- If they fail with [`ValidationError`](interceptors.md#symbol-ValidationError), name the failure `error` and recover:
+  - Call `print` with `value` = `"rejected"`.
+- Set `greeter` to call [`Greeter`](app.md#symbol-Greeter) with `name` = `"AugScript"`; inject `_logger` from `Logger`.
+- Call `print` with `value` = call [`Greeter.greet`](app.md#symbol-Greeter.greet) on `greeter`; inject `logger` from `Logger`, `console` from `Console`.
+- Try these operations:
+  - Call [`describe`](app.md#symbol-describe) with `x` = `-1`; `label` = `"invalid"`; inject `logger` from `Logger`, `console` from `Console`.
+- If they fail with [`ValidationError`](interceptors.md#symbol-ValidationError), name the failure `error` and recover:
+  - Call `print` with `value` = `"rejected"`.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole)
+
+Class from `august.io`.
+
+Used as a type or provider.
+
+#### [`Greeter`](app.md#symbol-Greeter)
+
+Class from `app`.
+
+- Construct with `name`: `string` → [`Greeter`](app.md#symbol-Greeter).
+- [`Greeter.greet`](app.md#symbol-Greeter.greet) (no caller inputs) → `string`; inject `logger`: [`Logger`](logging.md#symbol-Logger), `console`: [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console); uses [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
+
+#### [`describe`](app.md#symbol-describe)
+
+Function from `app`.
+
+- [`describe`](app.md#symbol-describe) (`x`: `int`, `label`: `string`) → `string`; inject `logger`: [`Logger`](logging.md#symbol-Logger), `console`: [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console); uses [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write); can fail with `ValidationError`.
+
+#### [`ValidationError`](interceptors.md#symbol-ValidationError)
+
+Class from `interceptors`.
+
+Used as a type or provider.
+
+#### [`ConsoleLogger`](logging.md#symbol-ConsoleLogger)
+
+Class from `logging`.
+
+Used as a type or provider.
+
+### 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/json-benchmark/data.md

@@ -0,0 +1,71 @@
+---
+title: "data.aug · JSON benchmark"
+generated: true
+source: "benchmarks/json/data.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `data.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]
+record Payload(int id, string message, List<int> values)
+```
+
+```aug [Braces]
+record Payload(int id, string message, List<int> values)
+```
+
+:::
+
+::::
+
+:::: 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
+
+- [`Payload`](data.md#symbol-Payload) is an immutable record.
+
+### `Payload` {#symbol-Payload}
+
+[source](data.md#code)
+
+Immutable record.
+
+**Inputs**
+
+- `id` (`int`) — required labeled input — stored as `id` and read-only after initialization.
+- `message` (`string`) — required labeled input — stored as `message` and read-only after initialization.
+- `values` (`List<int>`) — required labeled input — stored as `values` and read-only after initialization.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::