viv-compiler 0.1.0__tar.gz → 0.1.2__tar.gz

{viv_compiler-0.1.0/src/viv_compiler.egg-info → viv_compiler-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: viv-compiler
-Version: 0.1.0
+Version: 0.1.2
 Summary: Compiler for the DSL of Viv, an action system for emergent narrative.
 Author-email: James Ryan <mail@jamesryan.ai>
 License: MIT License
@@ -45,7 +45,7 @@ Dynamic: license-file
 
 This package contains the reference compiler for the domain-specific language (DSL) at the heart of [Viv](https://github.com/james-owen-ryan/viv), an action system for emergent narrative.
 
-The Viv compiler accepts a *Viv source file* (`.viv`) and produces a *Viv content bundle* in a JSON-serializable format conforming to the `CompiledContentBundle` schema defined [here](https://github.com/james-owen-ryan/viv/blob/main/compiler/src/viv_compiler/types/dsl_public_schemas.py), making it ready for usage in any Viv runtime.
+The Viv compiler accepts a **Viv source file** (`.viv`) and produces a **Viv content bundle** in a JSON-serializable format conforming to the `CompiledContentBundle` schema defined [here](https://github.com/james-owen-ryan/viv/blob/main/compiler/src/viv_compiler/types/dsl_public_schemas.py), making it ready for usage in any Viv runtime with the same version number as the compiler.
 
 Once you've installed this package, you'll have access to the two compiler interfaces that are documented below:
 
@@ -65,19 +65,17 @@ Once you've installed this package, you'll have access to the two compiler inter
 
 ## Installation
 
-Install from PyPI:
+* Install from PyPI:
 
-```
-pip install viv-compiler
-```
-
-This installs both the `viv_compiler` Python package and the `vivc` command-line interface.
+	```
+	pip install viv-compiler
+	```
 
-Smoke test to confirm your installation looks good:
+* Run a smoke test to confirm your installation looks good:
 
-```
-vivc --test
-```
+	```
+	vivc --test
+	```
 
 
 ## Command-Line Interface (CLI)
@@ -156,127 +154,167 @@ vivc --input path/to/source.viv [options]
 
 ### Examples
 
-Compile a source file and write the resulting content bundle to file:
+* Compile a source file and write the resulting content bundle to file:
 
-```
-vivc --input /path/to/my-actions.viv --output /path/to/myContentBundle.json
-```
+	```
+	vivc --input /path/to/my-actions.viv --output /path/to/myContentBundle.json
+	```
 
-Compile a source file and log the output in the console:
+* Compile a source file and log the output in the console:
 
-```
-vivc --input /path/to/my-actions.viv --print
-```
+	```
+	vivc --input /path/to/my-actions.viv --print
+	```
 
-Log the version number for the installed Viv compiler:
+* Log the version number for the installed Viv compiler:
 
-```
-vivc -v
-```
+	```
+	vivc -v
+	```
 
 
 ## Python API
 
-The API is intended for programmatic invocation of the compiler.
-
+Once you've installed `viv-compiler`, the Viv compiler Python API can be invoked by importing `viv_compiler` into your project.
 
-### `compile_from_path()`
 
-This function invokes the compiler for a specified Viv source file.
+### API Reference
 
-**Arguments**
+#### `compile_from_path()`
 
-* `source_file_path` (`Path`)
+* **Purpose**
 
-	* Absolute path to a `.viv` source file.
+	* Invokes the compiler for a specified Viv source file.
 
-* `default_salience` (`float`)
+* **Arguments**
 
-	* Default salience for actions (if unspecified).
+	* `source_file_path` (`Path`)
+	
+		* Absolute path to a `.viv` source file.
 
-* `default_associations` `(list[str])`
+	* `default_salience` (`float`)
 
-	* Default associations for actions (if unspecified).
+		* Default salience for actions (if unspecified).
 
-* `default_reaction_priority` (`float`)
+	* `default_associations` `(list[str])`
 	
-	* Default reaction priority for actions (if unspecified).
-
-* `use_memoization` (`bool`)
+		* Default associations for actions (if unspecified).
 
-	* Whether to enable memoization in the underlying PEG parser (faster but uses more memory).
+	* `default_reaction_priority` (`float`)
+		
+		* Default reaction priority for actions (if unspecified).
+	
+	* `use_memoization` (`bool`)
+	
+		* Whether to enable memoization in the underlying PEG parser (faster but uses more memory).
+	
+	* `debug` (`bool`)
+	
+		* Whether to enable verbose debugging for the underlying PEG parser.
 
-* `debug` (`bool`)
+* **Returns**
 
-	* Whether to enable verbose debugging for the underlying PEG parser.
+	* The compiled Viv bundle, in a JSON-serializable format conforming to the `CompiledContentBundle` schema defined in the project code.
 
-**Returns**
+* **Raises**
 
-* The compiled Viv bundle, in a JSON-serializable format conforming to the `CompiledContentBundle` schema defined in the project code.
+	* `VivCompileError`
+	
+		* Raised when compilation fails.
 
-**Raises**
+* **Example**
 
-* `VivCompileError`
+	```python
+	from pathlib import Path
+	from viv_compiler import compile_from_path, VivCompileError
+	
+	try:
+		content_bundle = compile_from_path(source_file_path=Path("my-actions.viv"))
+		print("Compilation succeeded:", content_bundle)
+	except VivCompileError as e:
+		print("Compilation failed:", e)
+	```
 
-	* Raised when compilation fails.
 
+#### `get_version()`
 
-### `get_version()`
+* **Purpose** 
 
-Returns the version string for the currently installed compiler.
+	* Returns the version string for the currently installed compiler. All content bundles produced by the compiler will be stamped with the same version number, making them compatible with any Viv runtime with the same version number.
 
+* **Arguments**
 
-### `VivCompileError`
+	* None.
 
-Custom exception type raised by the API when compilation fails. Inherits from `Exception`.
+* **Returns**
 
+	* A string constituting the version number of the installed Viv compiler.
 
-### Examples
+* **Example**
 
-Compile a source file:
+	```python
+	from viv_compiler import get_version
+	
+	version = get_version()
+	print("Viv compiler version:", version)
+	```
 
-```python
-from pathlib import Path
-from viv_compiler import compile_from_path, VivCompileError
 
-try:
-    content_bundle = compile_from_path(source_file_path=Path("my-actions.viv"))
-    print("Compilation succeeded:", content_bundle)
-except VivCompileError as e:
-    print("Compilation failed:", e)
-```
+#### `VivCompileError`
 
-Print the version number for the installed Viv compiler:
+* **Purpose** 
 
-```python
-from viv_compiler import get_version
-print(get_version())
-```
+	* Custom exception type (inherits from `Exception`) raised by the API when compilation fails.
 
 
 ## Running from Source
 
 For contributors or developers working directly from a repo checkout:
 
-```
-# Clone the Viv monorepo
-git clone https://github.com/james-owen-ryan/viv
-cd viv/compiler
+* Clone the Viv monorepo:
 
-# Create a virtual environment
-python -m venv .venv-viv-compiler
-source .venv-viv-compiler/bin/activate   # macOS/Linux
-# Windows PowerShell: .\.venv-viv-compiler\Scripts\Activate.ps1
+	```
+	git clone https://github.com/james-owen-ryan/viv
+	cd viv/compiler
+	```
 
-# Install the compiler package from source (editable)
-python -m pip install -e .
+* Create a virtual environment:
 
-# Invoke the CLI directly
-python -m viv_compiler --test
+	```
+	python -m venv .venv-viv-compiler
+	```
 
-# Or use the installed console script
-vivc --test
-```
+* Activate the virtual environment...
+
+	* macOS/Linux:
+
+		```
+		source .venv-viv-compiler/bin/activate
+		```
+		
+	* Windows PowerShell: 
+
+		```
+		.\.venv-viv-compiler\Scripts\Activate.ps1
+		```
+
+* Install the compiler package from source (editable):
+
+	```
+	python -m pip install -e .
+	```
+
+*  Invoke the CLI directly:
+
+	```
+	python -m viv_compiler --test
+	```
+
+* Or use the installed console script:
+
+	```
+	vivc --test
+	```
 
 
 ## License

viv_compiler-0.1.2/README.md

@@ -0,0 +1,279 @@
+# Viv Compiler
+
+This package contains the reference compiler for the domain-specific language (DSL) at the heart of [Viv](https://github.com/james-owen-ryan/viv), an action system for emergent narrative.
+
+The Viv compiler accepts a **Viv source file** (`.viv`) and produces a **Viv content bundle** in a JSON-serializable format conforming to the `CompiledContentBundle` schema defined [here](https://github.com/james-owen-ryan/viv/blob/main/compiler/src/viv_compiler/types/dsl_public_schemas.py), making it ready for usage in any Viv runtime with the same version number as the compiler.
+
+Once you've installed this package, you'll have access to the two compiler interfaces that are documented below:
+
+* A **command-line interface** (`vivc`) for invoking the compiler from the command line.
+
+* A **Python API** for invoking the compiler programmatically.
+
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Command-Line Interface](#command-line-interface-cli)
+- [Python API](#python-api)
+- [Running from Source](#running-from-source)
+- [License](#license)
+
+
+## Installation
+
+* Install from PyPI:
+
+	```
+	pip install viv-compiler
+	```
+
+* Run a smoke test to confirm your installation looks good:
+
+	```
+	vivc --test
+	```
+
+
+## Command-Line Interface (CLI)
+
+Once you've installed `viv-compiler`, the Viv compiler CLI will be exposed via the command `vivc` (and its alias `viv-compiler`).
+
+
+### Usage
+
+```
+vivc --input path/to/source.viv [options]
+```
+
+
+### Arguments
+
+* `-i, --input <path_to_source_file>`
+
+  * Required unless `--version` or `--test` is specified.
+  * Relative or absolute path to the Viv source file (`.viv`) to compile.
+  * If you are using `include` statements to import between files, this should be the main entrypoint file.
+
+* `-o, --output <path_to_output_file>`
+
+  * Optional.
+  * Path to write the compiled JSON bundle.
+
+
+### Flags and Options (Optional)
+
+* `-h, --help`
+
+	* Show help message and exit.
+
+* `-s, --default_salience <float>`
+
+  * Sets the default salience (floating-point number) for actions when unspecified.
+  * Default: value from `viv_compiler.config.DEFAULT_SALIENCE_VALUE`.
+
+* `-a, --default_associations <string ...>`
+
+  * Sets the default associations (zero or more strings) for actions when unspecified.
+  * Default: value from `viv_compiler.config.DEFAULT_ASSOCIATIONS_VALUE`.
+
+* `-r, --default_reaction_priority <float>`
+
+  * Sets the default reaction priority (floating-point number) for actions when unspecified.
+  * Default: value from `viv_compiler.config.DEFAULT_REACTION_PRIORITY_VALUE`.
+
+* `-m, --memoization, --no-memoization`
+
+  * Enable/disable memoization in the underlying PEG parser (slower but uses less memory).
+  * Default: enabled.
+
+* `-p, --print`
+
+  * After compilation, pretty-print the compiled bundle JSON.
+
+* `-l, --list`
+
+  * After compilation, print out a list of compiled action names.
+
+* `-d, --debug`
+
+  * Enable verbose debugging for the underlying PEG parser.
+
+* `-t, --test`
+
+  * Run a smoke test using a sample Viv file to confirm the installation works.
+  * Ignores `--input`.
+
+* `-v, --version`
+
+  * Print the current compiler version and exit.
+
+
+### Examples
+
+* Compile a source file and write the resulting content bundle to file:
+
+	```
+	vivc --input /path/to/my-actions.viv --output /path/to/myContentBundle.json
+	```
+
+* Compile a source file and log the output in the console:
+
+	```
+	vivc --input /path/to/my-actions.viv --print
+	```
+
+* Log the version number for the installed Viv compiler:
+
+	```
+	vivc -v
+	```
+
+
+## Python API
+
+Once you've installed `viv-compiler`, the Viv compiler Python API can be invoked by importing `viv_compiler` into your project.
+
+
+### API Reference
+
+#### `compile_from_path()`
+
+* **Purpose**
+
+	* Invokes the compiler for a specified Viv source file.
+
+* **Arguments**
+
+	* `source_file_path` (`Path`)
+	
+		* Absolute path to a `.viv` source file.
+
+	* `default_salience` (`float`)
+
+		* Default salience for actions (if unspecified).
+
+	* `default_associations` `(list[str])`
+	
+		* Default associations for actions (if unspecified).
+
+	* `default_reaction_priority` (`float`)
+		
+		* Default reaction priority for actions (if unspecified).
+	
+	* `use_memoization` (`bool`)
+	
+		* Whether to enable memoization in the underlying PEG parser (faster but uses more memory).
+	
+	* `debug` (`bool`)
+	
+		* Whether to enable verbose debugging for the underlying PEG parser.
+
+* **Returns**
+
+	* The compiled Viv bundle, in a JSON-serializable format conforming to the `CompiledContentBundle` schema defined in the project code.
+
+* **Raises**
+
+	* `VivCompileError`
+	
+		* Raised when compilation fails.
+
+* **Example**
+
+	```python
+	from pathlib import Path
+	from viv_compiler import compile_from_path, VivCompileError
+	
+	try:
+		content_bundle = compile_from_path(source_file_path=Path("my-actions.viv"))
+		print("Compilation succeeded:", content_bundle)
+	except VivCompileError as e:
+		print("Compilation failed:", e)
+	```
+
+
+#### `get_version()`
+
+* **Purpose** 
+
+	* Returns the version string for the currently installed compiler. All content bundles produced by the compiler will be stamped with the same version number, making them compatible with any Viv runtime with the same version number.
+
+* **Arguments**
+
+	* None.
+
+* **Returns**
+
+	* A string constituting the version number of the installed Viv compiler.
+
+* **Example**
+
+	```python
+	from viv_compiler import get_version
+	
+	version = get_version()
+	print("Viv compiler version:", version)
+	```
+
+
+#### `VivCompileError`
+
+* **Purpose** 
+
+	* Custom exception type (inherits from `Exception`) raised by the API when compilation fails.
+
+
+## Running from Source
+
+For contributors or developers working directly from a repo checkout:
+
+* Clone the Viv monorepo:
+
+	```
+	git clone https://github.com/james-owen-ryan/viv
+	cd viv/compiler
+	```
+
+* Create a virtual environment:
+
+	```
+	python -m venv .venv-viv-compiler
+	```
+
+* Activate the virtual environment...
+
+	* macOS/Linux:
+
+		```
+		source .venv-viv-compiler/bin/activate
+		```
+		
+	* Windows PowerShell: 
+
+		```
+		.\.venv-viv-compiler\Scripts\Activate.ps1
+		```
+
+* Install the compiler package from source (editable):
+
+	```
+	python -m pip install -e .
+	```
+
+*  Invoke the CLI directly:
+
+	```
+	python -m viv_compiler --test
+	```
+
+* Or use the installed console script:
+
+	```
+	vivc --test
+	```
+
+
+## License
+
+MIT License © 2025 James Ryan

{viv_compiler-0.1.0 → viv_compiler-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "viv-compiler"
-version = "0.1.0"  # This gets updated programmatically by `viv/scripts/bump_version.sh`
+version = "0.1.2"  # This gets updated programmatically by `viv/scripts/bump_version.sh`
 description = "Compiler for the DSL of Viv, an action system for emergent narrative."
 license = { file = "LICENSE" }
 authors = [{ name = "James Ryan", email = "mail@jamesryan.ai" }]

{viv_compiler-0.1.0/src/viv_compiler/utils → viv_compiler-0.1.2/src/viv_compiler}/_version.py

@@ -1,2 +1,2 @@
 # This is programmatically updated by viv/scripts/bump_version.sh
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{viv_compiler-0.1.0 → viv_compiler-0.1.2}/src/viv_compiler/cli.py

@@ -10,6 +10,8 @@ import traceback
 import viv_compiler.config
 from pathlib import Path
 from importlib import resources
+
+from viv_compiler import VivCompileError
 from .api import compile_from_path, get_version
 from viv_compiler.types import CompiledContentBundle
 
@@ -22,16 +24,17 @@ def main() -> None:
     args = parser.parse_args()
     # If the user has requested the compiler version, print it and exit
     if args.version:
-        print(f"\nviv_compiler {get_version()}\n")
+        print(get_version())
         sys.exit(0)
+    # If test mode is not engaged and no source file was provided, error and exit
+    if not args.test and not args.input:
+        parser.error("Unless the 'test' flag is engaged, an action file must be provided")
     # If test mode is engaged, invoke the compiler on a test file and exit
+    print("\nCompiling...\n", file=sys.stderr)
     if args.test:
         _run_smoke_test(args=args)
         sys.exit(0)
-    elif not args.input:
-        parser.error("Unless the 'test' flag is engaged, an action file must be provided")
     # Otherwise, it's showtime, so let's invoke the compiler
-    print("\nCompiling...\n", file=sys.stderr)
     if args.output:
         path_to_output_file = Path(args.output).expanduser().resolve()
         if not path_to_output_file.parent.exists():
@@ -152,7 +155,7 @@ def _run_smoke_test(args: argparse.Namespace) -> None:
             source_file_path=sample_path,
             default_salience=float(args.default_salience),
             default_associations=args.default_associations,
-            default_reaction_priority=float(args.default_priority),
+            default_reaction_priority=float(args.default_reaction_priority),
             debug=False,
             use_memoization=True,
         )
@@ -174,7 +177,7 @@ def _invoke_compiler(args: argparse.Namespace) -> CompiledContentBundle:
             source_file_path=source_file_path,
             default_salience=float(args.default_salience),
             default_associations=args.default_associations,
-            default_reaction_priority=float(args.default_priority),
+            default_reaction_priority=float(args.default_reaction_priority),
             debug=args.debug,
             use_memoization=args.memoization,
         )
@@ -188,10 +191,9 @@ def _invoke_compiler(args: argparse.Namespace) -> CompiledContentBundle:
         except Exception:
             pass
         sys.exit(1)
-    except Exception as e:
-        print(f"Error encountered during compilation: {e}", file=sys.stderr)
-        if args.debug:
-            traceback.print_exc()
+    except VivCompileError as e:
+        cause = e.__cause__ or e
+        print(f"Error encountered during compilation:\n\n{cause}\n", file=sys.stderr)
         sys.exit(1)
 
 
@@ -211,7 +213,7 @@ def _emit_results(
     """
     # If we're to print out the result, let's do so now, via `stdout` (with headers piped to `stderr`)
     if args.print:
-        print("\t== Result ==\n", file=sys.stderr)
+        print("    == Result ==\n", file=sys.stderr)
         sys.stdout.write(json.dumps(compiled_content_bundle, indent=2, sort_keys=True))
         sys.stdout.write("\n\n")
     # If we're to list out the compiled actions, let's do so now (again via
@@ -223,7 +225,7 @@ def _emit_results(
             lines.append(action_name)
         if not action_names:
             lines.append("N/A")
-        print(f"\t== Actions ({len(action_names)}) ==\n", file=sys.stderr)
+        print(f"    == Actions ({len(action_names)}) ==\n", file=sys.stderr)
         print("\n".join(f"- {line}" for line in lines), file=sys.stderr)
         print("", file=sys.stderr)
     # If an output file path has been provided, write the output file to the specified path