viv-compiler 0.1.0__tar.gz

viv_compiler-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 James Ryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

viv_compiler-0.1.0/PKG-INFO

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: viv-compiler
+Version: 0.1.0
+Summary: Compiler for the DSL of Viv, an action system for emergent narrative.
+Author-email: James Ryan <mail@jamesryan.ai>
+License: MIT License
+        
+        Copyright (c) 2025 James Ryan
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/james-owen-ryan/viv
+Project-URL: Repository, https://github.com/james-owen-ryan/viv/tree/main/compiler
+Project-URL: Issues, https://github.com/james-owen-ryan/viv/issues
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: arpeggio<3.0,>=2.0
+Requires-Dist: pydantic<2.12,>=2.11
+Requires-Dist: typing_extensions<5.0,>=4.6
+Dynamic: license-file
+
+# 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.
+
+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
+```
+
+This installs both the `viv_compiler` Python package and the `vivc` command-line interface.
+
+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
+
+The API is intended for programmatic invocation of the compiler.
+
+
+### `compile_from_path()`
+
+This function 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.
+
+
+### `get_version()`
+
+Returns the version string for the currently installed compiler.
+
+
+### `VivCompileError`
+
+Custom exception type raised by the API when compilation fails. Inherits from `Exception`.
+
+
+### Examples
+
+Compile a source file:
+
+```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)
+```
+
+Print the version number for the installed Viv compiler:
+
+```python
+from viv_compiler import get_version
+print(get_version())
+```
+
+
+## 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
+source .venv-viv-compiler/bin/activate   # macOS/Linux
+# 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/README.md

@@ -0,0 +1,241 @@
+# 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.
+
+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
+```
+
+This installs both the `viv_compiler` Python package and the `vivc` command-line interface.
+
+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
+
+The API is intended for programmatic invocation of the compiler.
+
+
+### `compile_from_path()`
+
+This function 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.
+
+
+### `get_version()`
+
+Returns the version string for the currently installed compiler.
+
+
+### `VivCompileError`
+
+Custom exception type raised by the API when compilation fails. Inherits from `Exception`.
+
+
+### Examples
+
+Compile a source file:
+
+```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)
+```
+
+Print the version number for the installed Viv compiler:
+
+```python
+from viv_compiler import get_version
+print(get_version())
+```
+
+
+## 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
+source .venv-viv-compiler/bin/activate   # macOS/Linux
+# 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/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "viv-compiler"
+version = "0.1.0"  # 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" }]
+requires-python = ">=3.10"
+dependencies = [
+  "arpeggio>=2.0,<3.0",
+  "pydantic>=2.11,<2.12",
+  "typing_extensions>=4.6,<5.0",
+]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Compilers",
+]
+
+[project.readme]
+file = "README.md"
+content-type = "text/markdown"
+
+[project.urls]
+Homepage = "https://github.com/james-owen-ryan/viv"
+Repository = "https://github.com/james-owen-ryan/viv/tree/main/compiler"
+Issues = "https://github.com/james-owen-ryan/viv/issues"
+
+[project.scripts]
+vivc = "viv_compiler.cli:main"
+viv-compiler = "viv_compiler.cli:main"  # Alias in case of a name collision
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+license-files = ["LICENSE*"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"viv_compiler" = ["grammar/viv.peg", "py.typed", "_samples/*.viv"]

viv_compiler-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

viv_compiler-0.1.0/src/viv_compiler/__init__.py

@@ -0,0 +1,14 @@
+try:
+    from importlib.metadata import version, PackageNotFoundError
+    try:
+        __version__ = version("viv-compiler")
+    except PackageNotFoundError:
+        # If we're running from a repo checkout, not the published package,
+        # we can pull the version from file.
+        from ._version import __version__
+except ImportError as e:
+    raise RuntimeError("viv_compiler appears to be corrupted: missing file `_version.py`") from e
+
+
+from .api import compile_from_path, get_version, VivCompileError
+__all__ = ["compile_from_path", "get_version", "VivCompileError", "__version__"]

viv_compiler-0.1.0/src/viv_compiler/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+if __name__ == "__main__":
+    main()

viv_compiler-0.1.0/src/viv_compiler/_samples/smoke-test.viv

@@ -0,0 +1,5 @@
+// A test action serving a quick smoke test that the
+// Viv compiler is functioning on the target machine.
+action test:
+    roles:
+        x: initiator

viv_compiler-0.1.0/src/viv_compiler/api.py

@@ -0,0 +1,58 @@
+"""API for the Viv compiler.
+
+This API is for machines. For human use, see the CLI exposed in `cli.py`.
+"""
+
+from pathlib import Path
+from typing import Sequence
+from viv_compiler import __version__
+from viv_compiler.types import CompiledContentBundle
+from .core import compile_viv_source_code
+
+
+def compile_from_path(
+    *,  # Require keyword arguments only
+    source_file_path: Path,
+    default_salience: float = 1.0,
+    default_associations: Sequence[str] = (),
+    default_reaction_priority: float = 1.0,
+    use_memoization: bool = True,
+    debug: bool = False,
+) -> CompiledContentBundle:
+    """Compile the given Viv source file to produce a JSON-serializable compiled content bundle.
+
+        Args:
+            source_file_path: The absolute path to the Viv source file to be parsed.
+            default_salience: A user-provided default salience value to use when one is not specified
+                in an action definition.
+            default_associations: A user-provided default associations value to use when one is not
+                specified in an action definition.
+            default_reaction_priority: A user-provided default reaction priority to use when one is not
+                specified in a reaction declaration.
+            use_memoization: Whether to use memoization during PEG parsing (faster, but uses more memory).
+            debug: Whether to invoke verbose debugging for the PEG parser itself.
+
+        Returns:
+            The compiled content bundle.
+        """
+    try:
+        return compile_viv_source_code(
+            source_file_path=source_file_path,
+            default_salience=float(default_salience),
+            default_associations=list(default_associations),
+            default_reaction_priority=float(default_reaction_priority),
+            use_memoization=use_memoization,
+            debug=debug,
+        )
+    except Exception as e:
+        raise VivCompileError(str(e)) from e
+
+
+def get_version() -> str:
+    """Return the Viv version number associated with this compiler instance."""
+    return __version__
+
+
+class VivCompileError(Exception):
+    """Raised when Viv compilation fails."""
+    pass

viv_compiler-0.1.0/src/viv_compiler/backports/__init__.py

@@ -0,0 +1 @@
+from .backports import *

viv_compiler-0.1.0/src/viv_compiler/backports/backports.py

@@ -0,0 +1,12 @@
+"""Backports for <3.11 Python functionality."""
+
+import sys
+from enum import Enum
+
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    class StrEnum(str, Enum):
+        """Backport of Python 3.11's StrEnum."""
+        pass