@greenpandastudios/aug-cli 0.19.0

package/examples/generic-di/.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/generic-di/.aug-spec/manifest.json

@@ -0,0 +1,10 @@
+{
+  "format": 1,
+  "files": [
+    ".aug-spec/august/0.19.0/io/contracts.aug",
+    ".aug-spec/august/0.19.0/io/contracts.aug.md",
+    "main.aug.md",
+    "types.aug.md"
+  ],
+  "digest": "b17af6b6608d47ed145c9647c531e9a58d8300656c50b63e31de9574fa62244a"
+}

package/examples/generic-di/main.aug

@@ -0,0 +1,9 @@
+import Console and SystemConsole from august.io
+implement Console with SystemConsole
+import Repository from types
+import NumberRepository from types
+import Program from types
+implement Repository<int> with NumberRepository
+implement app with Program
+resolve app to program
+program.start()

package/examples/generic-di/main.aug.md

@@ -0,0 +1,49 @@
+<!-- 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 3 dependency providers before startup.
+- 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 [`NumberRepository`](types.aug.md#symbol-NumberRepository) when `Repository<int>` is requested. Reuse one instance.
+- Provide [`Program`](types.aug.md#symbol-Program) when `app` is requested. Reuse one instance. Required dependencies: `Repository<int>`.
+
+## Startup, in source order
+
+- Set `program` to the instance provided for `app`.
+- Call [`Program.start`](types.aug.md#symbol-Program.start) on `program`; inject `console` from `Console`.
+
+## 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.
+
+### [`NumberRepository`](types.aug.md#symbol-NumberRepository)
+
+Class from `types`.
+
+Used as a type or provider.
+
+### [`Program`](types.aug.md#symbol-Program)
+
+Class from `types`.
+
+- [`Program.start`](types.aug.md#symbol-Program.start) (no caller inputs) → `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/generic-di/types.aug

@@ -0,0 +1,17 @@
+import Console from august.io
+interface Repository<T> {
+    get() returns T
+}
+NumberRepository() implements Repository<int> {
+    get() returns int {
+        return 7
+    }
+}
+Program(resolve Repository<int> repository) implements IProgram {
+    start(resolve Console console) uses Console.write {
+        console.write(value=repository.get())
+    }
+}
+interface IProgram {
+    start(resolve Console console) uses Console.write
+}

package/examples/generic-di/types.aug.md

@@ -0,0 +1,124 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `types.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Repository`](types.aug.md#symbol-Repository) is an interface.
+- [`NumberRepository`](types.aug.md#symbol-NumberRepository) is a class implementing `Repository<int>`.
+- [`Program`](types.aug.md#symbol-Program) is a class implementing `IProgram`.
+- [`IProgram`](types.aug.md#symbol-IProgram) is an interface.
+
+<a id="symbol-Repository"></a>
+
+## `Repository`
+
+[source](types.aug#L2)
+
+Interface.
+
+Type parameters: `T`.
+
+<a id="symbol-Repository.get"></a>
+
+### `Repository.get`
+
+[source](types.aug#L3)
+
+Returns: `T`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-NumberRepository"></a>
+
+## `NumberRepository`
+
+[source](types.aug#L5)
+
+Behavioral class.
+
+Satisfies [`Repository`](types.aug.md#symbol-Repository).
+
+<a id="symbol-NumberRepository.get"></a>
+
+### `NumberRepository.get`
+
+[source](types.aug#L6)
+
+Returns: `int`.
+
+**What it does**
+
+- Return `7`.
+
+<a id="symbol-Program"></a>
+
+## `Program`
+
+[source](types.aug#L10)
+
+Behavioral class.
+
+Satisfies [`IProgram`](types.aug.md#symbol-IProgram).
+
+**Inputs**
+
+- `repository` ([`Repository<int>`](types.aug.md#symbol-Repository)) — injected; callers omit it — stored as `repository` and read-only after initialization.
+
+<a id="symbol-Program.start"></a>
+
+### `Program.start`
+
+[source](types.aug#L11)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+
+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` = call [`Repository.get`](types.aug.md#symbol-Repository.get) on `repository`.
+
+<a id="symbol-IProgram"></a>
+
+## `IProgram`
+
+[source](types.aug#L15)
+
+Interface.
+
+<a id="symbol-IProgram.start"></a>
+
+### `IProgram.start`
+
+[source](types.aug#L16)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+
+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`.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/generics/.aug-spec/manifest.json

@@ -0,0 +1,8 @@
+{
+  "format": 1,
+  "files": [
+    "main.aug.md",
+    "types.aug.md"
+  ],
+  "digest": "48c09c80b967fb33cac28f4e8ea6ebfb7ad51c57a08e7e0ded24cc2336c1f7aa"
+}

package/examples/generics/main.aug

@@ -0,0 +1,9 @@
+import Formatter from types
+import TextFormatter from types
+import Box from types
+implement Formatter with TextFormatter
+resolve Formatter to formatter
+print(value=formatter.title())
+print(value=formatter.format<int>(value=42))
+box = Box<string>(value="inside a generic box")
+print(value=box.get())

package/examples/generics/main.aug.md

@@ -0,0 +1,58 @@
+<!-- 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 1 dependency provider 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 [`TextFormatter`](types.aug.md#symbol-TextFormatter) when `Formatter` is requested. Reuse one instance.
+
+## Startup, in source order
+
+- Set `formatter` to the instance provided for `Formatter`.
+- Call `print` with `value` = call [`Formatter.title`](types.aug.md#symbol-Formatter.title) on `formatter`.
+- Call `print` with `value` = call [`Formatter.format`](types.aug.md#symbol-Formatter.format) on `formatter` with type arguments `int` with `value` = `42`.
+- Set `box` to call [`Box`](types.aug.md#symbol-Box) with type arguments `string` with `value` = `"inside a generic box"`.
+- Call `print` with `value` = call [`Box.get`](types.aug.md#symbol-Box.get) on `box`.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`Box`](types.aug.md#symbol-Box)
+
+Class from `types`.
+
+- Construct with `value`: `T` → [`Box`](types.aug.md#symbol-Box).
+- [`Box.get`](types.aug.md#symbol-Box.get) (no caller inputs) → `T`.
+
+### [`Formatter`](types.aug.md#symbol-Formatter)
+
+Interface from `types`.
+
+- [`Formatter.format`](types.aug.md#symbol-Formatter.format)<`T`> (`value`: `T`) → `string`.
+- [`Formatter.title`](types.aug.md#symbol-Formatter.title) (no caller inputs) → `string`.
+
+### [`TextFormatter`](types.aug.md#symbol-TextFormatter)
+
+Class from `types`.
+
+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/generics/types.aug

@@ -0,0 +1,19 @@
+interface Formatter {
+    format<T>(T value) returns string
+    title() returns string {
+        return "formatted"
+    }
+}
+TextFormatter() implements Formatter {
+    format<T>(T value) returns string {
+        return "generic method called"
+    }
+}
+Box<T>(T value) implements IBox<T> {
+    get() returns T {
+        return value
+    }
+}
+interface IBox<T> {
+    get() returns T
+}