@greenpandastudios/aug-cli 0.19.0

package/examples/developer-workflow/logging/export.aug.md

@@ -0,0 +1,19 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `export.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- Export `Logger` from this folder.
+- Export `ConsoleLogger` from this folder.
+
+## Folder exports
+
+- Export the declaration `Logger` from [`logger.aug`](logger.aug.md#symbol-Logger).
+- Export the declaration `ConsoleLogger` from [`console.aug`](console.aug.md#symbol-ConsoleLogger).
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/developer-workflow/logging/logger.aug

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

package/examples/developer-workflow/logging/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**
+
+Receives a message describing an application operation.
+
+<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 write.
+
+## 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/developer-workflow/main.aug

@@ -0,0 +1,25 @@
+import Console and SystemConsole from august.io
+implement Console with SystemConsole
+import Logger and ConsoleLogger from logging
+import Arithmetic and Calculator and load from calculator
+implement Logger with ConsoleLogger
+try {
+    List<int> numbers = [1, 2]
+    Tuple<int,string> pair = (1, "apple")
+    Set<int> unique = {1, 2, 1}
+    Map<int,string> fruit = {1: "apples", 2: "pears"}
+    calculator = Calculator()
+    print(value=calculator.add(right=numbers.get(index=1), left=numbers.get(index=0)))
+    print(value=pair.get(index=1))
+    print(value=unique.length())
+    print(value=fruit.get(key=2))
+    try {
+        print(value=load(fail=true))
+    }
+    catch FileError error {
+        print(value="load failed as expected")
+    }
+}
+catch IndexError error {
+    print(value="unexpected index failure")
+}

package/examples/developer-workflow/main.aug.md

@@ -0,0 +1,79 @@
+<!-- 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.
+
+## 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/console.aug.md#symbol-ConsoleLogger) when `Logger` is requested. Reuse one instance.
+
+## Startup, in source order
+
+- Try these operations:
+  - Set `numbers` of type `List<int>` to a list containing `1`, `2`.
+  - Set `pair` of type `Tuple<int,string>` to a tuple containing `1`, `"apple"`.
+  - Set `unique` of type `Set<int>` to a set containing `1`, `2`, `1`.
+  - Set `fruit` of type `Map<int,string>` to a map with `1` mapped to `"apples"`; `2` mapped to `"pears"`.
+  - Set `calculator` to call [`Calculator`](calculator.aug.md#symbol-Calculator); inject `_logger` from `Logger`.
+  - Call `print` with `value` = call [`Calculator.add`](calculator.aug.md#symbol-Calculator.add) on `calculator` with `right` = call `get` on `numbers` with `index` = `1`; `left` = call `get` on `numbers` with `index` = `0`; inject `console` from `Console`.
+  - Call `print` with `value` = call `get` on `pair` with `index` = `1`.
+  - Call `print` with `value` = call `length` on `unique`.
+  - Call `print` with `value` = call `get` on `fruit` with `key` = `2`.
+  - Try these operations:
+    - Call `print` with `value` = call [`load`](calculator.aug.md#symbol-load) with `fail` = `true`.
+  - If they fail with `FileError`, name the failure `error` and recover:
+    - Call `print` with `value` = `"load failed as expected"`.
+- If they fail with `IndexError`, name the failure `error` and recover:
+  - Call `print` with `value` = `"unexpected index failure"`.
+
+## 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.
+
+### [`Calculator`](calculator.aug.md#symbol-Calculator)
+
+Class from `calculator`.
+
+- Construct with no caller inputs → [`Calculator`](calculator.aug.md#symbol-Calculator).
+- [`Calculator.add`](calculator.aug.md#symbol-Calculator.add) (`left`: `int`, `right`: `int`) → `int`; 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).
+
+### [`load`](calculator.aug.md#symbol-load)
+
+Function from `calculator`.
+
+- [`load`](calculator.aug.md#symbol-load) (`fail`: `bool`) → `string`; can fail with `FileError`.
+
+### [`ConsoleLogger`](logging/console.aug.md#symbol-ConsoleLogger)
+
+Class from `logging`.
+
+Used as a type or provider.
+
+## Built-in operations used by this file
+
+- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
+- `Map<int, string>.get` (`key`: `int`) → `optional string`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
+- `Set<int>.length` (no inputs) → `int`: Read the number of elements.
+- `Tuple<int, string>.get` (`index`: `int`) → `string`: Read a statically checked constant position. Prefer tuple destructuring when reading several positions.
+- `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/drop/.aug-spec/manifest.json

@@ -0,0 +1,8 @@
+{
+  "format": 1,
+  "files": [
+    "main.aug.md",
+    "resource.aug.md"
+  ],
+  "digest": "772f94c0390ab48369860e4b045064eabee967b18881ea6422c7fbafb41df19a"
+}

package/examples/drop/main.aug

@@ -0,0 +1,3 @@
+import Resource from resource
+own Resource resource = Resource()
+print(value="using resource")

package/examples/drop/main.aug.md

@@ -0,0 +1,35 @@
+<!-- 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
+
+- Run 2 other startup steps in source order.
+
+## Startup, in source order
+
+- Set `resource` of type [`Resource`](resource.aug.md#symbol-Resource) to call [`Resource`](resource.aug.md#symbol-Resource).
+- This variable owns the value.
+- Call `print` with `value` = `"using resource"`.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`Resource`](resource.aug.md#symbol-Resource)
+
+Class from `resource`.
+
+- Construct with no caller inputs → [`Resource`](resource.aug.md#symbol-Resource).
+
+## 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/drop/resource.aug

@@ -0,0 +1,8 @@
+Resource() implements IResource {
+    drop() {
+        pass
+    }
+}
+interface IResource {
+    pass
+}

package/examples/drop/resource.aug.md

@@ -0,0 +1,44 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `resource.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Resource`](resource.aug.md#symbol-Resource) is a class implementing `IResource`.
+- [`IResource`](resource.aug.md#symbol-IResource) is an interface.
+
+<a id="symbol-Resource"></a>
+
+## `Resource`
+
+[source](resource.aug#L1)
+
+Behavioral class.
+
+Satisfies [`IResource`](resource.aug.md#symbol-IResource).
+
+<a id="symbol-Resource.drop"></a>
+
+### `Resource.drop`
+
+[source](resource.aug#L2)
+
+Returns: no value.
+
+**What it does**
+
+- Continue without another operation.
+
+<a id="symbol-IResource"></a>
+
+## `IResource`
+
+[source](resource.aug#L6)
+
+Interface.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

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

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

package/examples/errors/errors.aug

@@ -0,0 +1,6 @@
+load(bool fail) returns string unless FileError {
+    if fail {
+        throw FileError()
+    }
+    return "loaded"
+}

package/examples/errors/errors.aug.md

@@ -0,0 +1,33 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `errors.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`load`](errors.aug.md#symbol-load) is a function returning `string`.
+
+<a id="symbol-load"></a>
+
+## `load`
+
+[source](errors.aug#L1)
+
+**Inputs**
+
+- `fail` (`bool`) — required labeled input.
+
+Returns: `string`.
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- If `fail` is true:
+  - Fail with call `FileError`. Transfer control to a matching catch or propagate the failure.
+- Return `"loaded"`.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/errors/main.aug

@@ -0,0 +1,7 @@
+import load from errors
+try {
+    print(value=load(fail=true))
+}
+catch FileError error {
+    print(value="caught FileError")
+}

package/examples/errors/main.aug.md

@@ -0,0 +1,36 @@
+<!-- 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
+
+- Run startup operations with checked error recovery.
+
+## Startup, in source order
+
+- Try these operations:
+  - Call `print` with `value` = call [`load`](errors.aug.md#symbol-load) with `fail` = `true`.
+- If they fail with `FileError`, name the failure `error` and recover:
+  - Call `print` with `value` = `"caught FileError"`.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`load`](errors.aug.md#symbol-load)
+
+Function from `errors`.
+
+- [`load`](errors.aug.md#symbol-load) (`fail`: `bool`) → `string`; can fail with `FileError`.
+
+## 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/ffi/.aug-spec/manifest.json

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

package/examples/ffi/main.aug

@@ -0,0 +1,2 @@
+import announce from native
+announce()

package/examples/ffi/main.aug.md

@@ -0,0 +1,27 @@
+<!-- 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
+
+- Run 1 other startup step in source order.
+
+## Startup, in source order
+
+- Call [`announce`](native.aug.md#symbol-announce).
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`announce`](native.aug.md#symbol-announce)
+
+Function from `native`.
+
+- [`announce`](native.aug.md#symbol-announce) (no caller inputs) → `void`; uses `C.puts`.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/ffi/native.aug

@@ -0,0 +1,6 @@
+extern C puts(string message) returns c_int
+announce() uses C.puts {
+    unsafe {
+        puts(message="hello from C FFI")
+    }
+}

package/examples/ffi/native.aug.md

@@ -0,0 +1,43 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `native.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`puts`](native.aug.md#symbol-puts) is a function returning `c_int`.
+- [`announce`](native.aug.md#symbol-announce) is a function.
+
+<a id="symbol-puts"></a>
+
+## `puts`
+
+[source](native.aug#L1)
+
+**Inputs**
+
+- `message` (`string`) — required labeled input.
+
+Returns: `c_int`.
+
+Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.
+
+<a id="symbol-announce"></a>
+
+## `announce`
+
+[source](native.aug#L2)
+
+Returns: no value.
+
+Capabilities: `C.puts`.
+
+**What it does**
+
+- Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:
+  - Call [`puts`](native.aug.md#symbol-puts) with `message` = `"hello from C FFI"`.
+
+## 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/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()