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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: viv-compiler
-Version: 0.1.0
+Version: 0.1.1
 Summary: Compiler for the DSL of Viv, an action system for emergent narrative.
 Author-email: James Ryan <mail@jamesryan.ai>
 License: MIT License
@@ -71,8 +71,6 @@ 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:
 
 ```
@@ -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
+	
+	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.0 → viv_compiler-0.1.1}/README.md

@@ -28,8 +28,6 @@ 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:
 
 ```
@@ -113,127 +111,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
+	
+	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.0 → viv_compiler-0.1.1}/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.1"  # 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 → viv_compiler-0.1.1}/src/viv_compiler/cli.py

@@ -22,16 +22,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 +153,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 +175,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,
         )
@@ -211,7 +212,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 +224,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

viv_compiler-0.1.1/src/viv_compiler/core/__init__.py

@@ -0,0 +1,5 @@
+from .core import *
+from .includes import *
+from .postprocessing import *
+from .validation import *
+from .visitor import *

{viv_compiler-0.1.0 → viv_compiler-0.1.1}/src/viv_compiler/core/core.py

@@ -23,10 +23,10 @@ import viv_compiler.types
 from typing import Any
 from pathlib import Path
 from importlib.resources import files
-from .importer import integrate_imported_files
+from .includes import integrate_included_files
 from .visitor import Visitor
-from .postprocessor import postprocess_combined_ast
-from .validator import validate_content_bundle
+from .postprocessing import postprocess_combined_ast
+from .validation import validate_content_bundle
 # noinspection PyUnresolvedReferences
 from arpeggio.cleanpeg import ParserPEG
 
@@ -37,7 +37,7 @@ def compile_viv_source_code(
     default_associations: list[str],
     default_reaction_priority: float,
     use_memoization: bool,
-    debug = False,
+    debug=False,
 ) -> viv_compiler.types.CompiledContentBundle:
     """Compile the given Viv source file to produce a JSON-serializable compiled content bundle.
 
@@ -71,7 +71,7 @@ def compile_viv_source_code(
     # construct an abstract syntax tree (AST).
     ast: viv_compiler.types.AST = _sanitize_ast(ast=arpeggio.visit_parse_tree(tree, Visitor()))
     # If there are any include declarations (i.e., import statements), honor those now
-    combined_ast: viv_compiler.types.CombinedAST = integrate_imported_files(
+    combined_ast: viv_compiler.types.CombinedAST = integrate_included_files(
         viv_parser=viv_parser,
         ast=ast,
         entry_point_file_path=source_file_path

viv_compiler-0.1.0/src/viv_compiler/core/importer.py → viv_compiler-0.1.1/src/viv_compiler/core/includes.py

@@ -1,10 +1,10 @@
 """Module that handles importing between Viv files.
 
-The entrypoint function is `integrate_imported_files()`, and everything else is only meant to be
+The entrypoint function is `integrate_included_files()`, and everything else is only meant to be
 invoked internally, i.e., within this module.
 """
 
-__all__ = ["integrate_imported_files"]
+__all__ = ["integrate_included_files"]
 
 import arpeggio
 import viv_compiler.types
@@ -14,13 +14,13 @@ from .visitor import Visitor
 from arpeggio.cleanpeg import ParserPEG
 
 
-def integrate_imported_files(
+def integrate_included_files(
     viv_parser: ParserPEG,
     ast: viv_compiler.types.AST,
     entry_point_file_path: Path,
 ) -> viv_compiler.types.CombinedAST:
-    """Handle any include declarations in the given AST (including any recursive ones) and return a dictionary
-    containing trope definitions and action definitions.
+    """Handle any `include` declarations in the given AST (including any recursive ones)
+    and return a dictionary containing trope definitions and action definitions.
 
     Args:
         viv_parser: A prepared Viv parser.