@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/interceptors/dependencies/august/0.21.0/io/contracts.md

@@ -0,0 +1,178 @@
+---
+title: "august/0.21.0/io/contracts.aug · Function and constructor middleware"
+generated: true
+source: "examples/interceptors/.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`
+
+[Function and constructor middleware](../../../../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).
+
+::::
+
+:::::

package/docs/examples/interceptors/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Layer interceptors, map inputs, and keep logging dependencies explicit.
 
-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
 
@@ -24,12 +24,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/interceptors.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/interceptors
-aug spec examples/interceptors
-aug run examples/interceptors
+cd interceptors
+aug check .
+aug spec .
+aug run .
 ```
 
 [Browse all examples](../index.md)

package/docs/examples/interceptors/interceptors.md

@@ -31,6 +31,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "interceptors.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 import Logger from logging
 /** Raised when a numeric input fails validation. */
@@ -43,7 +44,7 @@ ValidationError(string message) implements Error:
 */
 interceptor Audit<T>(resolve Logger logger):
     /** Wrap a call without changing its result. */
-    around(resolve Console console) returns T uses Console.write:
+    around(resolve Console console):
         logger.log(message="before")
         T result = next()
         logger.log(message="after")
@@ -54,7 +55,7 @@ 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:
+    around(int y) returns T:
         if y < 0:
             throw ValidationError(message="value must be nonnegative")
         return next()
@@ -66,6 +67,7 @@ interceptor AddOne<T>():
 ```
 
 ```aug [Braces]
+// aug-spec: "interceptors.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 import Logger from logging
 /** Raised when a numeric input fails validation. */
@@ -79,7 +81,7 @@ ValidationError(string message) implements Error {
 */
 interceptor Audit<T>(resolve Logger logger) {
     /** Wrap a call without changing its result. */
-    around(resolve Console console) returns T uses Console.write {
+    around(resolve Console console) {
         logger.log(message="before")
         T result = next()
         logger.log(message="after")
@@ -92,7 +94,7 @@ 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 {
+    around(int y) returns T {
         if y < 0 {
             throw ValidationError(message="value must be nonnegative")
         }
@@ -116,168 +118,42 @@ interceptor AddOne<T>() {
 
 ## 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.
+### `ValidationError` · class · [source](interceptors.md#code) {#symbol-ValidationError}
 
-Type parameters: `T`.
+Raised when a numeric input fails validation. It implements `Error`. It takes `message` as a string, kept read-only.
 
-**Author documentation**
+### `Audit` · interceptor · [source](interceptors.md#code) {#symbol-Audit}
 
 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`.
+Generic T is inferred from the annotated function or constructor. The type parameters are `T`.
 
-**What it does**
+The `logger` dependency is injected as [`Logger`](logging.md#symbol-Logger) and stored read-only. Creates one interceptor per invocation. Its around operation may delegate once or finish early.
 
-- Return call `next` with `y` = (`y` plus `1`).
+#### `Audit.around` · [source](interceptors.md#code) {#symbol-Audit.around}
 
-**Author documentation**
+Wrap a call without changing its result. It gets `console` ([`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection.
 
-**Parameters**
-- `y`: The input to increment.
+It passes `"before"` to [`logger.log`](logging.md#symbol-Logger.log), using injected `console`. It sets `result` of type `T` to `next`. It passes `"after"` to [`logger.log`](logging.md#symbol-Logger.log), using injected `console`. It returns `result`.
 
-### Dependencies used by this file
+### `Positive` · interceptor · [source](interceptors.md#code) {#symbol-Positive}
 
-Only referenced types and operations appear here. Each name links to its complete specification.
+Rejects negative numbers before the target executes. The type parameters are `T`. Creates one interceptor per invocation. Its around operation may delegate once or finish early.
 
-#### [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)
+#### `Positive.around` · [source](interceptors.md#code) {#symbol-Positive.around}
 
-Capability interface from `august.io`.
+It takes `y` as an integer (the target argument selected by a mapping such as y=x). Failures can raise [`ValidationError`](interceptors.md#symbol-ValidationError) (when the selected value is negative). If `y` is negative, it raises a [`ValidationError`](interceptors.md#symbol-ValidationError) with `message` `"value must be nonnegative"`. It returns `next`.
 
-- [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+### `AddOne` · interceptor · [source](interceptors.md#code) {#symbol-AddOne}
 
-#### [`Logger`](logging.md#symbol-Logger)
+Adds one to the selected input before forwarding the call. The type parameters are `T`. Creates one interceptor per invocation. Its around operation may delegate once or finish early.
 
-Interface from `logging`.
+#### `AddOne.around` · [source](interceptors.md#code) {#symbol-AddOne.around}
 
-- [`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).
+It takes `y` as an integer (the input to increment). It returns `next` with `y` from `y` plus `1`.
 
-### Shared language rules
+### Dependencies
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console) ([`write`](dependencies/august/0.21.0/io/contracts.md#symbol-Console.write)) from `august.io`. It uses [`Logger`](logging.md#symbol-Logger) ([`log`](logging.md#symbol-Logger.log)) from `logging`.
 
 ::::
 

package/docs/examples/interceptors/logging.md

@@ -31,6 +31,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "logging.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 /** Writes a message to the application log. */
 interface Logger:
@@ -38,11 +39,12 @@ interface Logger:
     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:
+    log(resolve Console console, string message):
         console.write(value=message)
 ```
 
 ```aug [Braces]
+// aug-spec: "logging.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 /** Writes a message to the application log. */
 interface Logger {
@@ -51,7 +53,7 @@ interface Logger {
 }
 /** Console logger shared by interceptor instances and the application. */
 ConsoleLogger() implements Logger {
-    log(resolve Console console, string message) uses Console.write {
+    log(resolve Console console, string message) {
         console.write(value=message)
     }
 }
@@ -65,90 +67,25 @@ ConsoleLogger() implements Logger {
 
 ## 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**
+### `Logger` · interface · [source](logging.md#code) {#symbol-Logger}
 
 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.
+#### `Logger.log` · [source](logging.md#code) {#symbol-Logger.log}
 
-### Dependencies used by this file
+It takes `message` as a string (Text to display). It gets `console` ([`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It can call [`Console.write`](dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
-Only referenced types and operations appear here. Each name links to its complete specification.
+### `ConsoleLogger` · class · [source](logging.md#code) {#symbol-ConsoleLogger}
 
-#### [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)
+Console logger shared by interceptor instances and the application. It implements [`Logger`](logging.md#symbol-Logger).
 
-Capability interface from `august.io`.
+#### `ConsoleLogger.log` · [source](logging.md#code) {#symbol-ConsoleLogger.log}
 
-- [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+It takes `message` as a string (Text to display). It gets `console` ([`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It passes `message` to [`console.write`](dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
-### Shared language rules
+### Dependencies
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console) ([`write`](dependencies/august/0.21.0/io/contracts.md#symbol-Console.write)) from `august.io`.
 
 ::::