@greenpandastudios/aug-cli 0.19.0

package/examples/interceptors/app.aug.md

@@ -0,0 +1,162 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `app.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`describe`](app.aug.md#symbol-describe) is a function returning `string`.
+- [`IGreeter`](app.aug.md#symbol-IGreeter) is an interface.
+- [`Greeter`](app.aug.md#symbol-Greeter) is a class implementing `IGreeter`.
+
+<a id="symbol-describe"></a>
+
+## `describe`
+
+[source](app.aug#L14)
+
+**Inputs**
+
+- `logger` ([`Logger`](logging.aug.md#symbol-Logger)) — injected; callers omit it.
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+- `x` (`int`) — required labeled input.
+- `label` (`string`) — required labeled input.
+
+Returns: `string`.
+
+Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+Can fail with `ValidationError`. Callers must catch or propagate these errors.
+
+**Interceptors, in execution order**
+
+1. Call [`Audit.around`](interceptors.aug.md#symbol-Audit.around). It can call the next layer or finish with its own result or failure. Unselected inputs pass through.
+2. Call [`Positive.around`](interceptors.aug.md#symbol-Positive.around). It can call the next layer or finish with its own result or failure. Map `x` to `y`. Unselected inputs pass through.
+3. Call [`AddOne.around`](interceptors.aug.md#symbol-AddOne.around). It can call the next layer or finish with its own result or failure. Map `x` to `y`. Unselected inputs pass through.
+
+The first layer wraps the remaining layers. HTTP policies run before wire decoding; custom interceptors run after decoding. Follow linked behavior to see its conditions, input changes, and calls to the next layer.
+
+**What it does**
+
+- Call [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write) on `console` with `value` = `x`.
+- Return `label`.
+
+**Author documentation**
+
+Prints a number and returns its label.
+
+**Parameters**
+- `x`: The numeric input, validated and incremented by the chain.
+- `label`: Text forwarded through each layer unchanged.
+
+<a id="symbol-IGreeter"></a>
+
+## `IGreeter`
+
+[source](app.aug#L18)
+
+Interface.
+
+<a id="symbol-IGreeter.greet"></a>
+
+### `IGreeter.greet`
+
+[source](app.aug#L19)
+
+**Inputs**
+
+- `logger` ([`Logger`](logging.aug.md#symbol-Logger)) — injected; callers omit it.
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+
+Returns: `string`.
+
+Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-Greeter"></a>
+
+## `Greeter`
+
+[source](app.aug#L22)
+
+Behavioral class.
+
+Satisfies [`IGreeter`](app.aug.md#symbol-IGreeter).
+
+**Author documentation**
+
+Construction stores its inputs; startup is visible in the greet call.
+
+**Inputs**
+
+- `logger` ([`Logger`](logging.aug.md#symbol-Logger)) — injected; callers omit it — stored as `_logger` (private) and read-only after initialization.
+- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
+
+<a id="symbol-Greeter.greet"></a>
+
+### `Greeter.greet`
+
+[source](app.aug#L25)
+
+**Inputs**
+
+- `logger` ([`Logger`](logging.aug.md#symbol-Logger)) — injected; callers omit it.
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+
+Returns: `string`.
+
+Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+**Interceptors, in execution order**
+
+1. Call [`Audit.around`](interceptors.aug.md#symbol-Audit.around). It can call the next layer or finish with its own result or failure. Unselected inputs pass through.
+
+The first layer wraps the remaining layers. HTTP policies run before wire decoding; custom interceptors run after decoding. Follow linked behavior to see its conditions, input changes, and calls to the next layer.
+
+**What it does**
+
+- Return text formed by joining `"Hello, "`, `name`, `"!"` in order.
+
+**Author documentation**
+
+Method annotations wrap each method invocation separately.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)
+
+Capability interface from `august.io`.
+
+- [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+
+### [`AddOne`](interceptors.aug.md#symbol-AddOne)
+
+Interceptor from `interceptors`.
+
+- [`AddOne.around`](interceptors.aug.md#symbol-AddOne.around) (`y`: `int`) → `T`.
+
+### [`Audit`](interceptors.aug.md#symbol-Audit)
+
+Interceptor from `interceptors`.
+
+- [`Audit.around`](interceptors.aug.md#symbol-Audit.around) (no caller inputs) → `T`; inject `console`: [`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console); uses [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+### [`Positive`](interceptors.aug.md#symbol-Positive)
+
+Interceptor from `interceptors`.
+
+- [`Positive.around`](interceptors.aug.md#symbol-Positive.around) (`y`: `int`) → `T`; can fail with `ValidationError`.
+
+### [`Logger`](logging.aug.md#symbol-Logger)
+
+Interface from `logging`.
+
+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.

package/examples/interceptors/interceptors.aug

@@ -0,0 +1,40 @@
+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)
+    }
+}

package/examples/interceptors/interceptors.aug.md

@@ -0,0 +1,180 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `interceptors.aug` 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.aug.md#symbol-ValidationError) is a class implementing `Error`.
+- [`Audit`](interceptors.aug.md#symbol-Audit) is an interceptor.
+- [`Positive`](interceptors.aug.md#symbol-Positive) is an interceptor.
+- [`AddOne`](interceptors.aug.md#symbol-AddOne) is an interceptor.
+
+<a id="symbol-ValidationError"></a>
+
+## `ValidationError`
+
+[source](interceptors.aug#L4)
+
+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.
+
+<a id="symbol-Audit"></a>
+
+## `Audit`
+
+[source](interceptors.aug#L12)
+
+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.aug.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.
+
+<a id="symbol-Audit.around"></a>
+
+### `Audit.around`
+
+[source](interceptors.aug#L14)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+
+Returns: `T`.
+
+Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+**What it does**
+
+- Call [`Logger.log`](logging.aug.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.aug.md#symbol-Logger.log) on `logger` with `message` = `"after"`; inject `console` from `console`.
+- Return `result`.
+
+**Author documentation**
+
+Wrap a call without changing its result.
+
+<a id="symbol-Positive"></a>
+
+## `Positive`
+
+[source](interceptors.aug#L22)
+
+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.
+
+<a id="symbol-Positive.around"></a>
+
+### `Positive.around`
+
+[source](interceptors.aug#L27)
+
+**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.aug.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.
+
+<a id="symbol-AddOne"></a>
+
+## `AddOne`
+
+[source](interceptors.aug#L35)
+
+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.
+
+<a id="symbol-AddOne.around"></a>
+
+### `AddOne.around`
+
+[source](interceptors.aug#L37)
+
+**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`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)
+
+Capability interface from `august.io`.
+
+- [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+
+### [`Logger`](logging.aug.md#symbol-Logger)
+
+Interface from `logging`.
+
+- [`Logger.log`](logging.aug.md#symbol-Logger.log) (`message`: `string`) → `void`; inject `console`: [`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console); uses [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.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/examples/interceptors/logging.aug

@@ -0,0 +1,12 @@
+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)
+    }
+}

package/examples/interceptors/logging.aug.md

@@ -0,0 +1,96 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `logging.aug` 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.aug.md#symbol-Logger) is an interface.
+- [`ConsoleLogger`](logging.aug.md#symbol-ConsoleLogger) is a class implementing `Logger`.
+
+<a id="symbol-Logger"></a>
+
+## `Logger`
+
+[source](logging.aug#L3)
+
+Interface.
+
+**Author documentation**
+
+Writes a message to the application log.
+
+<a id="symbol-Logger.log"></a>
+
+### `Logger.log`
+
+[source](logging.aug#L5)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+- `message` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+**Parameters**
+- `message`: Text to display.
+
+<a id="symbol-ConsoleLogger"></a>
+
+## `ConsoleLogger`
+
+[source](logging.aug#L8)
+
+Behavioral class.
+
+Satisfies [`Logger`](logging.aug.md#symbol-Logger).
+
+**Author documentation**
+
+Console logger shared by interceptor instances and the application.
+
+<a id="symbol-ConsoleLogger.log"></a>
+
+### `ConsoleLogger.log`
+
+[source](logging.aug#L9)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+- `message` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+**What it does**
+
+- Call [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.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`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)
+
+Capability interface from `august.io`.
+
+- [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.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/examples/interceptors/main.aug

@@ -0,0 +1,22 @@
+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")
+}

package/examples/interceptors/main.aug.md

@@ -0,0 +1,76 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug` 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`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
+- Provide [`ConsoleLogger`](logging.aug.md#symbol-ConsoleLogger) when `Logger` is requested. Reuse one instance.
+
+## Startup, in source order
+
+- Try these operations:
+  - Call `print` with `value` = call [`describe`](app.aug.md#symbol-describe) with `label` = `"value"`; `x` = `6`; inject `logger` from `Logger`, `console` from `Console`.
+- If they fail with [`ValidationError`](interceptors.aug.md#symbol-ValidationError), name the failure `error` and recover:
+  - Call `print` with `value` = `"rejected"`.
+- Set `greeter` to call [`Greeter`](app.aug.md#symbol-Greeter) with `name` = `"AugScript"`; inject `_logger` from `Logger`.
+- Call `print` with `value` = call [`Greeter.greet`](app.aug.md#symbol-Greeter.greet) on `greeter`; inject `logger` from `Logger`, `console` from `Console`.
+- Try these operations:
+  - Call [`describe`](app.aug.md#symbol-describe) with `x` = `-1`; `label` = `"invalid"`; inject `logger` from `Logger`, `console` from `Console`.
+- If they fail with [`ValidationError`](interceptors.aug.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`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole)
+
+Class from `august.io`.
+
+Used as a type or provider.
+
+### [`Greeter`](app.aug.md#symbol-Greeter)
+
+Class from `app`.
+
+- Construct with `name`: `string` → [`Greeter`](app.aug.md#symbol-Greeter).
+- [`Greeter.greet`](app.aug.md#symbol-Greeter.greet) (no caller inputs) → `string`; inject `logger`: [`Logger`](logging.aug.md#symbol-Logger), `console`: [`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console); uses [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+### [`describe`](app.aug.md#symbol-describe)
+
+Function from `app`.
+
+- [`describe`](app.aug.md#symbol-describe) (`x`: `int`, `label`: `string`) → `string`; inject `logger`: [`Logger`](logging.aug.md#symbol-Logger), `console`: [`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console); uses [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write); can fail with `ValidationError`.
+
+### [`ValidationError`](interceptors.aug.md#symbol-ValidationError)
+
+Class from `interceptors`.
+
+Used as a type or provider.
+
+### [`ConsoleLogger`](logging.aug.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/examples/new-syntax/.aug-spec/august/0.19.0/io/contracts.aug

@@ -0,0 +1,36 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+/** 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) returns string unless FileError:
+        return read_file(path=path)
+    write(string path, string content) unless FileError:
+        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() returns List<string>:
+        return arguments()