@greenpandastudios/aug-cli 0.19.0

package/examples/new-syntax/.aug-spec/august/0.19.0/io/contracts.aug.md

@@ -0,0 +1,316 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Console`](contracts.aug.md#symbol-Console) is a capability interface.
+- [`SystemConsole`](contracts.aug.md#symbol-SystemConsole) is a class implementing `Console`.
+- [`FileReader`](contracts.aug.md#symbol-FileReader) is a capability interface.
+- [`FileWriter`](contracts.aug.md#symbol-FileWriter) is a capability interface.
+- [`LocalFiles`](contracts.aug.md#symbol-LocalFiles) is a class implementing `FileReader`, `FileWriter`.
+- [`Arguments`](contracts.aug.md#symbol-Arguments) is a capability interface.
+- [`ProcessArguments`](contracts.aug.md#symbol-ProcessArguments) is a class implementing `Arguments`.
+
+<a id="symbol-Console"></a>
+
+## `Console`
+
+[source](contracts.aug#L3)
+
+Capability interface.
+
+**Author documentation**
+
+Permission to write to a console, provided by an explicitly selected adapter.
+
+<a id="symbol-Console.write"></a>
+
+### `Console.write`
+
+[source](contracts.aug#L5)
+
+Type parameters: `T`.
+
+**Inputs**
+
+- `value` (`T`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Write one line of text.
+
+**Parameters**
+- `value`: Text to display.
+
+<a id="symbol-SystemConsole"></a>
+
+## `SystemConsole`
+
+[source](contracts.aug#L8)
+
+Behavioral class.
+
+Satisfies [`Console`](contracts.aug.md#symbol-Console).
+
+**Author documentation**
+
+The native standard-output adapter. Construction performs no output.
+
+<a id="symbol-SystemConsole.write"></a>
+
+### `SystemConsole.write`
+
+[source](contracts.aug#L9)
+
+Type parameters: `T`.
+
+**Inputs**
+
+- `value` (`T`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+**What it does**
+
+- Call `print` with `value` = `value`.
+
+**Author documentation**
+
+Write one line of text.
+
+**Parameters**
+- `value`: Text to display.
+
+<a id="symbol-FileReader"></a>
+
+## `FileReader`
+
+[source](contracts.aug#L13)
+
+Capability interface.
+
+**Author documentation**
+
+Read UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileReader.read"></a>
+
+### `FileReader.read`
+
+[source](contracts.aug#L15)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+
+Returns: `string`.
+
+Capabilities: [`FileReader.read`](contracts.aug.md#symbol-FileReader.read).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Read text.
+
+**Parameters**
+- `path`: File path.
+
+**Throws**
+- `FileError`: The file could not be read.
+
+<a id="symbol-FileWriter"></a>
+
+## `FileWriter`
+
+[source](contracts.aug#L18)
+
+Capability interface.
+
+**Author documentation**
+
+Write UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileWriter.write"></a>
+
+### `FileWriter.write`
+
+[source](contracts.aug#L20)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+- `content` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Write text.
+
+**Parameters**
+- `path`: File path.
+- `content`: Text.
+
+**Throws**
+- `FileError`: Writing failed.
+
+<a id="symbol-LocalFiles"></a>
+
+## `LocalFiles`
+
+[source](contracts.aug#L23)
+
+Behavioral class.
+
+Satisfies [`FileReader`](contracts.aug.md#symbol-FileReader), [`FileWriter`](contracts.aug.md#symbol-FileWriter).
+
+**Author documentation**
+
+Native files. Operations are explicit; construction opens no files.
+
+<a id="symbol-LocalFiles.read"></a>
+
+### `LocalFiles.read`
+
+[source](contracts.aug#L24)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+
+Returns: `string`.
+
+Capabilities: [`FileReader.read`](contracts.aug.md#symbol-FileReader.read).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Return call `read_file` with `path` = `path`.
+
+**Author documentation**
+
+Read text.
+
+**Parameters**
+- `path`: File path.
+
+**Throws**
+- `FileError`: The file could not be read.
+
+<a id="symbol-LocalFiles.write"></a>
+
+### `LocalFiles.write`
+
+[source](contracts.aug#L26)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+- `content` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Call `write_file` with `path` = `path`; `content` = `content`.
+
+**Author documentation**
+
+Write text.
+
+**Parameters**
+- `path`: File path.
+- `content`: Text.
+
+**Throws**
+- `FileError`: Writing failed.
+
+<a id="symbol-Arguments"></a>
+
+## `Arguments`
+
+[source](contracts.aug#L30)
+
+Capability interface.
+
+**Author documentation**
+
+Read command-line input through an explicit dependency.
+
+<a id="symbol-Arguments.read"></a>
+
+### `Arguments.read`
+
+[source](contracts.aug#L31)
+
+Returns: `List<string>`.
+
+Capabilities: [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-ProcessArguments"></a>
+
+## `ProcessArguments`
+
+[source](contracts.aug#L34)
+
+Behavioral class.
+
+Satisfies [`Arguments`](contracts.aug.md#symbol-Arguments).
+
+**Author documentation**
+
+Native command-line arguments.
+
+<a id="symbol-ProcessArguments.read"></a>
+
+### `ProcessArguments.read`
+
+[source](contracts.aug#L35)
+
+Returns: `List<string>`.
+
+Capabilities: [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+**What it does**
+
+- Return call `arguments`.
+
+## Built-in operations used by this file
+
+- `arguments` (no inputs) → `List<string>`: Composition arguments. Other callables receive the Arguments capability.
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+- `read_file` (`path`: `string`) → `string`: Root-only UTF-8 text input. Other callables receive FileReader. Invalid Unicode and NUL raise FileError. Can fail with `FileError`.
+- `write_file` (`path`: `string`, `content`: `string`) → `void`: Root-only UTF-8 text output. Other callables receive FileWriter. Can fail with `FileError`.
+
+[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/manifest.json

@@ -0,0 +1,13 @@
+{
+  "format": 1,
+  "files": [
+    ".aug-spec/august/0.19.0/io/contracts.aug",
+    ".aug-spec/august/0.19.0/io/contracts.aug.md",
+    "console.aug.md",
+    "greeter.aug.md",
+    "logger.aug.md",
+    "main.aug.md",
+    "math.aug.md"
+  ],
+  "digest": "2cf8231cb76a18e70e28c9ac46d35892c904328c98f186dbf7544e0e04333dbd"
+}

package/examples/new-syntax/console.aug

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

package/examples/new-syntax/console.aug.md

@@ -0,0 +1,63 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `console.aug` 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.aug.md#symbol-ConsoleLogger) is a class implementing `Logger`.
+
+<a id="symbol-ConsoleLogger"></a>
+
+## `ConsoleLogger`
+
+[source](console.aug#L3)
+
+Behavioral class.
+
+Satisfies [`Logger`](logger.aug.md#symbol-Logger).
+
+<a id="symbol-ConsoleLogger.log"></a>
+
+### `ConsoleLogger.log`
+
+[source](console.aug#L4)
+
+**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`.
+
+### [`Logger`](logger.aug.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.

package/examples/new-syntax/greeter.aug

@@ -0,0 +1,10 @@
+import Console from august.io
+import Logger from logger
+Greeter(resolve Logger logger, int x) implements IGreeter {
+    greet(resolve Console console, string name) uses Console.write {
+        logger.log(message="Hello, " + name + "!")
+    }
+}
+interface IGreeter {
+    greet(resolve Console console, string name) uses Console.write
+}

package/examples/new-syntax/greeter.aug.md

@@ -0,0 +1,89 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `greeter.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Greeter`](greeter.aug.md#symbol-Greeter) is a class implementing `IGreeter`.
+- [`IGreeter`](greeter.aug.md#symbol-IGreeter) is an interface.
+
+<a id="symbol-Greeter"></a>
+
+## `Greeter`
+
+[source](greeter.aug#L3)
+
+Behavioral class.
+
+Satisfies [`IGreeter`](greeter.aug.md#symbol-IGreeter).
+
+**Inputs**
+
+- `logger` ([`Logger`](logger.aug.md#symbol-Logger)) — injected; callers omit it — stored as `logger` and read-only after initialization.
+- `x` (`int`) — required labeled input — stored as `x` and read-only after initialization.
+
+<a id="symbol-Greeter.greet"></a>
+
+### `Greeter.greet`
+
+[source](greeter.aug#L4)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+- `name` (`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 [`Logger.log`](logger.aug.md#symbol-Logger.log) on `logger` with `message` = (text formed by joining `"Hello, "`, `name`, `"!"` in order); inject `console` from `console`.
+
+<a id="symbol-IGreeter"></a>
+
+## `IGreeter`
+
+[source](greeter.aug#L8)
+
+Interface.
+
+<a id="symbol-IGreeter.greet"></a>
+
+### `IGreeter.greet`
+
+[source](greeter.aug#L9)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+- `name` (`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.
+
+## 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`](logger.aug.md#symbol-Logger)
+
+Interface from `logger`.
+
+- [`Logger.log`](logger.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/new-syntax/logger.aug

@@ -0,0 +1,6 @@
+import Console from august.io
+/** Displays application messages. */
+interface Logger {
+    /** @param message Text to display. */
+    log(resolve Console console, string message) uses Console.write
+}

package/examples/new-syntax/logger.aug.md

@@ -0,0 +1,57 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `logger.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`](logger.aug.md#symbol-Logger) is an interface.
+
+<a id="symbol-Logger"></a>
+
+## `Logger`
+
+[source](logger.aug#L3)
+
+Interface.
+
+**Author documentation**
+
+Displays application messages.
+
+<a id="symbol-Logger.log"></a>
+
+### `Logger.log`
+
+[source](logger.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.
+
+## 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/new-syntax/main.aug

@@ -0,0 +1,12 @@
+import Console and SystemConsole from august.io
+implement Console with SystemConsole
+import Logger from logger
+import ConsoleLogger from console
+import Greeter from greeter
+import increment from math
+implement Logger with ConsoleLogger
+greeter = Greeter(x=4)
+greeter.greet(name="AugScript")
+int count = 7
+count = increment(value=count)
+print(value=count)

package/examples/new-syntax/main.aug.md

@@ -0,0 +1,64 @@
+<!-- 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 5 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`](console.aug.md#symbol-ConsoleLogger) when `Logger` is requested. Reuse one instance.
+
+## Startup, in source order
+
+- Set `greeter` to call [`Greeter`](greeter.aug.md#symbol-Greeter) with `x` = `4`; inject `logger` from `Logger`.
+- Call [`Greeter.greet`](greeter.aug.md#symbol-Greeter.greet) on `greeter` with `name` = `"AugScript"`; inject `console` from `Console`.
+- Set `count` of type `int` to `7`.
+- Set `count` to call [`increment`](math.aug.md#symbol-increment) with `value` = `count`.
+- Call `print` with `value` = `count`.
+
+## 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.
+
+### [`ConsoleLogger`](console.aug.md#symbol-ConsoleLogger)
+
+Class from `console`.
+
+Used as a type or provider.
+
+### [`Greeter`](greeter.aug.md#symbol-Greeter)
+
+Class from `greeter`.
+
+- Construct with `x`: `int` → [`Greeter`](greeter.aug.md#symbol-Greeter).
+- [`Greeter.greet`](greeter.aug.md#symbol-Greeter.greet) (`name`: `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).
+
+### [`increment`](math.aug.md#symbol-increment)
+
+Function from `math`.
+
+- [`increment`](math.aug.md#symbol-increment) (`value`: `int`) → `int`.
+
+## 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/math.aug

@@ -0,0 +1,3 @@
+increment(int value) returns int {
+    return value + 1
+}

package/examples/new-syntax/math.aug.md

@@ -0,0 +1,29 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `math.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`increment`](math.aug.md#symbol-increment) is a function returning `int`.
+
+<a id="symbol-increment"></a>
+
+## `increment`
+
+[source](math.aug#L1)
+
+**Inputs**
+
+- `value` (`int`) — required labeled input.
+
+Returns: `int`.
+
+**What it does**
+
+- Return `value` plus `1`.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.