@greenpandastudios/aug-cli 0.19.0

package/docs/examples/developer-workflow/logging/logger.md

@@ -0,0 +1,111 @@
+---
+title: "logging/logger.aug · A small tested application"
+generated: true
+source: "examples/developer-workflow/logging/logger.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `logging/logger.aug`
+
+[A small tested application](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](../main.md)
+- [`calculator.aug`](../calculator.md)
+- [`logging/console.aug`](console.md)
+- [`logging/export.aug`](export.md)
+- [`logging/logger.aug`](logger.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+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
+```
+
+```aug [Braces]
+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
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## 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`](logger.md#symbol-Logger) is an interface.
+
+### `Logger` {#symbol-Logger}
+
+[source](logger.md#code)
+
+Interface.
+
+**Author documentation**
+
+Receives a message describing an application operation.
+
+#### `Logger.log` {#symbol-Logger.log}
+
+[source](logger.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 write.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`Console`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console)
+
+Capability interface from `august.io`.
+
+- [`Console.write`](../dependencies/august/0.19.0/io/contracts.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/docs/examples/developer-workflow/main.md

@@ -0,0 +1,172 @@
+---
+title: "main.aug · A small tested application"
+generated: true
+source: "examples/developer-workflow/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[A small tested application](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`calculator.aug`](calculator.md)
+- [`logging/console.aug`](logging/console.md)
+- [`logging/export.aug`](logging/export.md)
+- [`logging/logger.aug`](logging/logger.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+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")
+```
+
+```aug [Braces]
+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")
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## 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
+
+- 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`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
+- Provide [`ConsoleLogger`](logging/console.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.md#symbol-Calculator); inject `_logger` from `Logger`.
+  - Call `print` with `value` = call [`Calculator.add`](calculator.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.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`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole)
+
+Class from `august.io`.
+
+Used as a type or provider.
+
+#### [`Calculator`](calculator.md#symbol-Calculator)
+
+Class from `calculator`.
+
+- Construct with no caller inputs → [`Calculator`](calculator.md#symbol-Calculator).
+- [`Calculator.add`](calculator.md#symbol-Calculator.add) (`left`: `int`, `right`: `int`) → `int`; 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).
+
+#### [`load`](calculator.md#symbol-load)
+
+Function from `calculator`.
+
+- [`load`](calculator.md#symbol-load) (`fail`: `bool`) → `string`; can fail with `FileError`.
+
+#### [`ConsoleLogger`](logging/console.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/docs/examples/drop/index.md

@@ -0,0 +1,33 @@
+---
+title: "Resource cleanup"
+generated: true
+source: "examples/drop"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Resource cleanup
+
+Release an owned resource when its lifetime ends.
+
+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.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`resource.aug`](resource.md)
+
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check examples/drop
+aug spec examples/drop
+aug run examples/drop
+```
+
+[Browse all examples](../index.md)

package/docs/examples/drop/main.md

@@ -0,0 +1,85 @@
+---
+title: "main.aug · Resource cleanup"
+generated: true
+source: "examples/drop/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Resource cleanup](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`resource.aug`](resource.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import Resource from resource
+own Resource resource = Resource()
+print(value="using resource")
+```
+
+```aug [Braces]
+import Resource from resource
+own Resource resource = Resource()
+print(value="using resource")
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## 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
+
+- Run 2 other startup steps in source order.
+
+### Startup, in source order
+
+- Set `resource` of type [`Resource`](resource.md#symbol-Resource) to call [`Resource`](resource.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.md#symbol-Resource)
+
+Class from `resource`.
+
+- Construct with no caller inputs → [`Resource`](resource.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/docs/examples/drop/resource.md

@@ -0,0 +1,95 @@
+---
+title: "resource.aug · Resource cleanup"
+generated: true
+source: "examples/drop/resource.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `resource.aug`
+
+[Resource cleanup](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`resource.aug`](resource.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+Resource() implements IResource:
+    drop():
+        pass
+interface IResource:
+    pass
+```
+
+```aug [Braces]
+Resource() implements IResource {
+    drop() {
+        pass
+    }
+}
+interface IResource {
+    pass
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## 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
+
+- [`Resource`](resource.md#symbol-Resource) is a class implementing `IResource`.
+- [`IResource`](resource.md#symbol-IResource) is an interface.
+
+### `Resource` {#symbol-Resource}
+
+[source](resource.md#code)
+
+Behavioral class.
+
+Satisfies [`IResource`](resource.md#symbol-IResource).
+
+#### `Resource.drop` {#symbol-Resource.drop}
+
+[source](resource.md#code)
+
+Returns: no value.
+
+**What it does**
+
+- Continue without another operation.
+
+### `IResource` {#symbol-IResource}
+
+[source](resource.md#code)
+
+Interface.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/errors/errors.md

@@ -0,0 +1,85 @@
+---
+title: "errors.aug · Checked failures"
+generated: true
+source: "examples/errors/errors.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `errors.aug`
+
+[Checked failures](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`errors.aug`](errors.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+load(bool fail) returns string unless FileError:
+    if fail:
+        throw FileError()
+    return "loaded"
+```
+
+```aug [Braces]
+load(bool fail) returns string unless FileError {
+    if fail {
+        throw FileError()
+    }
+    return "loaded"
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## 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
+
+- [`load`](errors.md#symbol-load) is a function returning `string`.
+
+### `load` {#symbol-load}
+
+[source](errors.md#code)
+
+**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/docs/examples/errors/index.md

@@ -0,0 +1,33 @@
+---
+title: "Checked failures"
+generated: true
+source: "examples/errors"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Checked failures
+
+Declare errors with unless, catch them, and run cleanup.
+
+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.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`errors.aug`](errors.md)
+
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check examples/errors
+aug spec examples/errors
+aug run examples/errors
+```
+
+[Browse all examples](../index.md)

package/docs/examples/errors/main.md

@@ -0,0 +1,92 @@
+---
+title: "main.aug · Checked failures"
+generated: true
+source: "examples/errors/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Checked failures](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`errors.aug`](errors.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import load from errors
+try:
+    print(value=load(fail=true))
+catch FileError error:
+    print(value="caught FileError")
+```
+
+```aug [Braces]
+import load from errors
+try {
+    print(value=load(fail=true))
+}
+catch FileError error {
+    print(value="caught FileError")
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## 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
+
+- Run startup operations with checked error recovery.
+
+### Startup, in source order
+
+- Try these operations:
+  - Call `print` with `value` = call [`load`](errors.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.md#symbol-load)
+
+Function from `errors`.
+
+- [`load`](errors.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.
+
+::::
+
+:::::