viv-compiler 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

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/core/__init__.py

@@ -1,5 +1,5 @@
 from .core import *
-from .importer import *
-from .postprocessor import *
-from .validator import *
+from .includes import *
+from .postprocessing import *
+from .validation import *
 from .visitor import *

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/core/{importer.py → 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.

viv_compiler/core/metadata.py

@@ -0,0 +1,69 @@
+"""Module that handles the creation of metadata to attach to a compiled content bundle.
+
+The entrypoint function is `create_metadata()`.
+"""
+
+__all__ = ["create_metadata"]
+
+import viv_compiler.types
+import viv_compiler.utils
+from viv_compiler import __version__
+from viv_compiler.types import ExpressionDiscriminator
+from viv_compiler.utils import get_all_expressions_of_type
+
+
+def create_metadata(
+    action_definitions: list[viv_compiler.types.ActionDefinition],
+    trope_definitions: list[viv_compiler.types.TropeDefinition],
+) -> viv_compiler.types.CompiledContentBundleMetadata:
+    """Return a package containing metadata for the given compiled content bundle.
+
+    Args:
+        action_definitions: List containing all actions in the content bundle.
+        trope_definitions: List containing all tropes in the content bundle.
+
+    Returns:
+        A metadata package for the given content bundle.
+    """
+    metadata = {
+        "vivVersion": __version__,
+        "referencedEnums": [],
+        "referencedFunctionNames": [],
+        "itemRoles": [],
+        "buildRoles": [],
+        "timeOfDayConstrainedReactions": []
+    }
+    for ast_chunk in action_definitions + trope_definitions:
+        # Compile all referenced enums
+        all_referenced_enum_names = set(viv_compiler.utils.get_all_referenced_enum_names(ast_chunk=ast_chunk))
+        metadata["referencedEnums"].extend(all_referenced_enum_names)
+        # Compile all referenced adapter functions
+        all_referenced_function_names = set(
+            viv_compiler.utils.get_all_referenced_adapter_function_names(ast_chunk=ast_chunk)
+        )
+        metadata["referencedFunctionNames"].extend(all_referenced_function_names)
+    for action_definition in action_definitions:
+        # Compile all roles carrying 'item' and 'build' labels
+        for role_definition in action_definition["roles"].values():
+            if role_definition["item"]:
+                metadata["itemRoles"].append({
+                    "action": action_definition["name"],
+                    "role": role_definition["name"]
+                })
+            if role_definition["build"]:
+                metadata["buildRoles"].append({
+                    "action": action_definition["name"],
+                    "role": role_definition["name"]
+                })
+        # Compile all reactions referencing time of day
+        all_nested_reactions = get_all_expressions_of_type(
+            expression_type=ExpressionDiscriminator.REACTION,
+            ast_chunk=action_definition
+        )
+        for reaction in all_nested_reactions:
+            if reaction["options"]["when"] and reaction["options"]["when"]["timeOfDay"]:
+                metadata["timeOfDayConstrainedReactions"].append({
+                    "action": action_definition["name"],
+                    "reaction": reaction["actionName"]
+                })
+    return metadata

viv_compiler/core/{postprocessor.py → postprocessing.py}

@@ -1,4 +1,4 @@
-"""Postprocessor for the Viv DSL.
+"""Module that handles postprocessing of compiled ASTs for the Viv DSL.
 
 This module takes in ASTs produced by the Viv parser (with imports honored) and
 postprocesses them to produce compiled content bundles that are ready for validation.
@@ -13,9 +13,9 @@ import copy
 import viv_compiler.config
 import viv_compiler.types
 import viv_compiler.utils
-from viv_compiler import __version__
 from typing import Any, cast
-from .validator import validate_join_directives, validate_preliminary_action_definitions
+from .validation import validate_join_directives, validate_preliminary_action_definitions
+from .metadata import create_metadata
 
 
 def postprocess_combined_ast(combined_ast: viv_compiler.types.CombinedAST) -> viv_compiler.types.CompiledContentBundle:
@@ -62,15 +62,15 @@ def postprocess_combined_ast(combined_ast: viv_compiler.types.CombinedAST) -> vi
     # Isolate the trope definitions
     finalized_trope_definitions = combined_ast["tropes"]
     # Create metadata to be attached to the compiled content bundle
-    content_bundle_metadata = _create_metadata(
+    content_bundle_metadata = create_metadata(
         action_definitions=finalized_action_definitions,
         trope_definitions=finalized_trope_definitions
     )
     # Package up and return the compiled content bundle
     compiled_content_bundle: viv_compiler.types.CompiledContentBundle = {
+        "meta": content_bundle_metadata,
         "tropes": {trope["name"]: trope for trope in finalized_trope_definitions},
-        "actions": {action["name"]: action for action in finalized_action_definitions},
-        "meta": content_bundle_metadata
+        "actions": {action["name"]: action for action in finalized_action_definitions}
     }
     return compiled_content_bundle
 
@@ -721,29 +721,3 @@ def _attribute_preconditions(
         )
         final_action_definitions.append(final_action_definition)
     return final_action_definitions
-
-
-def _create_metadata(
-    action_definitions: list[viv_compiler.types.ActionDefinition],
-    trope_definitions: list[viv_compiler.types.TropeDefinition],
-) -> viv_compiler.types.CompiledContentBundleMetadata:
-    """Return a package containing metadata for the given compiled content bundle.
-
-    Args:
-        action_definitions: List containing all actions in the content bundle.
-        trope_definitions: List containing all tropes in the content bundle.
-
-    Returns:
-        A metadata package for the given content bundle.
-    """
-    metadata = {
-        "vivVersion": __version__,
-        "referencedEnums": [],
-        "referencedFunctionNames": []
-    }
-    for ast_chunk in action_definitions + trope_definitions:
-        all_referenced_enum_names = set(viv_compiler.utils.get_all_referenced_enum_names(ast_chunk=ast_chunk))
-        metadata["referencedEnums"].extend(all_referenced_enum_names)
-        all_referenced_function_names = set(viv_compiler.utils.get_all_referenced_enum_names(ast_chunk=ast_chunk))
-        metadata["referencedFunctionNames"].extend(all_referenced_function_names)
-    return metadata

viv_compiler/core/{validator.py → validation.py}

@@ -1,4 +1,4 @@
-"""A library of functions to validate preliminary action definitions and compiled content bundles.
+"""Module that handles validation of preliminary action definitions and compiled content bundles.
 
 The entrypoint functions are as follows:
     * `validate_join_directives()`: Invoked prior to handling of action inheritance.
@@ -19,29 +19,6 @@ from importlib import import_module
 from pydantic import TypeAdapter
 
 
-# todo do we already ensure all references are anchored in a (valid) role name?
-# todo warn or error if precondition references scaled enum?
-# todo validate time of day to ensure 0-23 and 0-59
-# todo technically you could inject major side effects (e.g. reaction queueing) into trope-fit expressions
-# todo ensure closing time period is always later than opening time period
-# todo ensure embargo is either permanent or has a declared time period
-# todo don't allow reaction to precast same entity multiple times
-# todo build roles:
-#  - they can cast exactly one entity, with no chance and no mean
-#  - no pool declarations
-#  - can never be precast
-#  - preconditions cannot reference build roles
-#  - don't allow them in embargoes (embargo would not be violable)
-# todo apparently the grammar allows e.g. multiple roles fields in an action definition
-#  - test what happens (presumably last in wins)
-# todo make sure times like 88:76 aren't allowed (grammar allows them)
-# todo role renaming (make sure new name being duplicate of existing one is already caught)
-#   - just detect duplicate role names right away post-visitor
-# todo prohibit entity references anchored in symbol roles
-#   - not ideal, but interpreter enforces this at runtime currently
-# todo assignments only allowed in scratch and effects
-
-
 def validate_join_directives(raw_action_definitions: list[viv_compiler.types.RawActionDefinition]) -> None:
     """Ensure that the given action definition makes proper use of `join` directives.
 

viv_compiler/core/visitor.py

@@ -166,7 +166,6 @@ class Visitor(arpeggio.PTNodeVisitor):
             "partner": False,
             "recipient": False,
             "bystander": False,
-            "subject": False,
             "absent": False,
             "precast": False,
             "build": False,
@@ -641,6 +640,19 @@ class Visitor(arpeggio.PTNodeVisitor):
             conditional_object['value'].update(child)
         return conditional_object
 
+    @staticmethod
+    def visit_associations_conditional_branches(_, children: Any) -> dict[str, viv_compiler.types.Expression]:
+        """Visit a <associations_conditional_branches> node."""
+        return {"branches": children}
+
+    @staticmethod
+    def visit_associations_conditional_branch(_, children: Any) -> dict[str, viv_compiler.types.Expression]:
+        """Visit a <associations_conditional_branch> node."""
+        component = {}
+        for child in children:
+            component.update(child)
+        return component
+
     @staticmethod
     def visit_associations_conditional_consequent(_, children: Any) -> dict[str, list[viv_compiler.types.Expression]]:
         """Visit a <associations_conditional_consequent> node."""
@@ -709,10 +721,23 @@ class Visitor(arpeggio.PTNodeVisitor):
     @staticmethod
     def visit_conditional(_, children: Any) -> viv_compiler.types.Conditional:
         """Visit a <conditional> node."""
-        conditional_object = {"type": ExpressionDiscriminator.CONDITIONAL, "value": {}}
+        component = {"type": ExpressionDiscriminator.CONDITIONAL, "value": {}}
         for child in children:
-            conditional_object['value'].update(child)
-        return conditional_object
+            component['value'].update(child)
+        return component
+
+    @staticmethod
+    def visit_conditional_branches(_, children: Any) -> dict[str, viv_compiler.types.Expression]:
+        """Visit a <conditional_branches> node."""
+        return {"branches": children}
+
+    @staticmethod
+    def visit_conditional_branch(_, children: Any) -> dict[str, viv_compiler.types.Expression]:
+        """Visit a <conditional_branch> node."""
+        component = {}
+        for child in children:
+            component.update(child)
+        return component
 
     @staticmethod
     def visit_condition(_, children: Any) -> dict[str, viv_compiler.types.Expression]:
@@ -926,12 +951,13 @@ class Visitor(arpeggio.PTNodeVisitor):
             # just syntactic sugar for `@this.scratch.`, which means any reference anchored in a global
             # variable is in fact an entity reference anchored in a role name.
             anchor = viv_compiler.config.GLOBAL_VARIABLE_REFERENCE_ANCHOR
-            path = viv_compiler.config.GLOBAL_VARIABLE_REFERENCE_PATH_PREFIX
-            # Add in the global variable itself, as a property name
-            path.append({
-                "type": ReferencePathComponentDiscriminator.REFERENCE_PATH_COMPONENT_PROPERTY_NAME,
-                "propertyName": children[0]["name"],
-            })
+            path = [
+                *viv_compiler.config.GLOBAL_VARIABLE_REFERENCE_PATH_PREFIX,
+                {
+                    "type": ReferencePathComponentDiscriminator.REFERENCE_PATH_COMPONENT_PROPERTY_NAME,
+                    "name": children[0]["name"],
+                }
+            ]
             path += children[1] if len(children) > 1 else []
         else:
             anchor = children[0]["name"]
@@ -1063,13 +1089,17 @@ class Visitor(arpeggio.PTNodeVisitor):
     @staticmethod
     def visit_enum(_, children: Any) -> viv_compiler.types.Enum:
         """Visit an <enum> node."""
-        scaled = "#" in children  # As opposed to ##, which yields an unscaled enum
-        additive_inverse_present = "-" in children
+        additive_inverse_present = False
+        if len(children) > 1:
+            additive_inverse_present = children[0] == "-"
+        token = children[-1]
+        unscaled = token[:2] == "##"  # As opposed to '#', which yields an scaled enum
+        name = token.lstrip('#')
         component = {
             "type": ExpressionDiscriminator.ENUM,
             "value": {
-                "name": children[-1],
-                "scaled": scaled,
+                "name": name,
+                "scaled": not unscaled,
                 "minus": additive_inverse_present
             }
         }

viv_compiler/grammar/viv.peg

@@ -57,8 +57,8 @@ binding_pool_directive = binding_pool_from_directive / binding_pool_is_directive
 binding_pool_from_directive = "from" expression
 binding_pool_is_directive = "is" expression
 role_labels = role_label ("," role_label)*
-role_label = "initiator" / "partner" / "recipient" / "bystander" / "subject" / "location" /
-           "symbol" / "absent" / "action" / "item" / "precast" / build_directive
+role_label = "initiator" / "partner" / "recipient" / "bystander" / "location" /
+             "symbol" / "absent" / "action" / "item" / "precast" / build_directive
 build_directive = "build" "(" build_directive_entity_recipe ")"
 build_directive_entity_recipe = object
 binding_rate_directive = chance_directive / mean_directive
@@ -94,20 +94,23 @@ time = hh (":" mm)? ("pm" / "am" / "PM" / "AM")
 hh = r"[0-9]{1,2}"
 mm = r"[0-9]{2}"
 abandonment_conditions = "abandon" ":" statements
-saliences = child_join_operator? "saliences" saliences_default_value saliences_body?
+
+salience_associations_local_variable_name = "c"
+
+saliences = (child_join_operator? "saliences" saliences_default_value) /
+            (child_join_operator? "saliences" "for" local_variable_sigil salience_associations_local_variable_name saliences_default_value saliences_body?)
 saliences_default_value = "default" (enum / number)
 saliences_body = ":" statement+
 
-associations = child_join_operator? "associations" associations_default_value associations_body?
+associations = (child_join_operator? "associations" associations_default_value) /
+               (child_join_operator? "associations" "for" local_variable_sigil salience_associations_local_variable_name associations_default_value associations_body?)
 associations_default_value = "default" tags
 associations_body = ":" associations_statements
 associations_statements = associations_statement+
 associations_statement = associations_conditional / associations_loop / tags
-associations_conditional =
-    "if" condition ":"
-        associations_conditional_consequent
-	("else:" associations_conditional_alternative)?
-	"end"
+associations_conditional = associations_conditional_branches ("else:" associations_conditional_alternative)? "end"
+associations_conditional_branches = "if" associations_conditional_branch ("elif" associations_conditional_branch)*
+associations_conditional_branch = condition ":" associations_conditional_consequent
 associations_conditional_consequent = associations_scoped_statements ""
 associations_conditional_alternative = associations_scoped_statements ""
 associations_loop =
@@ -146,7 +149,9 @@ adapter_function_call = "~" name "(" args? ")" eval_fail_safe_marker?
 args = expression ("," expression)*
 statements = statement+
 statement = conditional / loop / reaction / expression / literal
-conditional = "if" condition ":" consequent ("else:" alternative)? "end"
+conditional = conditional_branches ("else:" alternative)? "end"
+conditional_branches = "if" conditional_branch ("elif" conditional_branch)*
+conditional_branch = condition ":" consequent
 condition = expression
 consequent = scoped_statements ""
 alternative = scoped_statements ""

viv_compiler/types/content_public_schemas.py

@@ -29,12 +29,12 @@ if TYPE_CHECKING:
 
 class CompiledContentBundle(TypedDict):
     """A content bundle in the format produced by the Viv compiler."""
+    # Metadata for the content bundle, which is currently used for validation purposes
+    meta: CompiledContentBundleMetadata
     # Trope definitions, keyed by name
     tropes: dict[TropeName, TropeDefinition]
     # Action definitions, keyed by name
     actions: dict[ActionName, ActionDefinition]
-    # Metadata for the content bundle, which is currently used for validation purposes
-    meta: CompiledContentBundleMetadata
 
 
 class CompiledContentBundleMetadata(TypedDict):
@@ -57,6 +57,31 @@ class CompiledContentBundleMetadata(TypedDict):
     # content bundle. This is used for validation during the initialization of
     # a target application's Viv adapter.
     referencedFunctionNames: list[AdapterFunctionName]
+    # An array specifying all role definitions carrying the `item` label. This is used
+    # for validation during the initialization of a target application's Viv adapter.
+    itemRoles: list[CompiledContentBundleMetadataRoleEntry]
+    # An array specifying all role definitions carrying the `build` label. This is used
+    # for validation during the initialization of a target application's Viv adapter.
+    buildRoles: list[CompiledContentBundleMetadataRoleEntry]
+    # An array specifying all reactions that are constrained by the time of day. This is used
+    # for validation during the initialization of a target application's Viv adapter.
+    timeOfDayConstrainedReactions: list[CompiledContentBundleMetadataTimeOfDayConstrainedReaction]
+
+
+class CompiledContentBundleMetadataRoleEntry(TypedDict):
+    """A simple record of a case of a role carrying a `build` label, used for validation purposes."""
+    # The name of the action containing a role carrying the `build` label
+    action: ActionName
+    # The name of the role carrying the `build` label
+    role: RoleName
+
+
+class CompiledContentBundleMetadataTimeOfDayConstrainedReaction(TypedDict):
+    """A simple record of a case of reaction that is constrained by the time of day, used for validation purposes."""
+    # The name of the action containing a reaction that is constrained by the time of day
+    action: ActionName
+    # The name of the target action of the reaction that is constrained by the time of day
+    reaction: ActionName
 
 
 # Unique name for an arbitrary function exposed in a target application's Viv adapter
@@ -175,8 +200,6 @@ class RoleDefinition(TypedDict, total=False):
     recipient: bool
     # Whether an entity cast in this role is an uninvolved witness to the associated action
     bystander: bool
-    # Whether an entity cast in this role is the subject of the associated action
-    subject: bool
     # Whether an entity cast in this role is a character who is not physically present for the associated action
     absent: bool
     # Whether this role must be precast via reaction bindings. See Reaction docs for details

viv_compiler/types/dsl_public_schemas.py

@@ -216,13 +216,19 @@ class Conditional(TypedDict):
 
 class ConditionalValue(TypedDict, total=False):
     """The actual expression value for a Viv conditional."""
+    # Branches representing the `if` and `elif` clauses in this conditional expression
+    branches: list[ConditionalBranch]
+    # If an author has provided an alternative body (via an `else` clause), a list
+    # of expressions that will be evaluated/executed should the condition not hold.
+    alternative: list[Expression]
+
+
+class ConditionalBranch(TypedDict):
+    """A Viv conditional branch, representing an `if` or `elif` clause."""
     # The condition that will be tested, which holds if its evaluation is truthy
     condition: Expression
     # A list of expressions that will be evaluated/executed should the condition hold
     consequent: list[Expression]
-    # If an author has provided an alternative body (via an `else` clause), a list
-    # of expressions that will be evaluated/executed should the condition not hold.
-    alternative: list[Expression]
 
 
 class Conjunction(NegatableExpression):

{viv_compiler-0.1.0.dist-info → viv_compiler-0.1.1.dist-info}/METADATA

@@ -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.dist-info → viv_compiler-0.1.1.dist-info}/RECORD

@@ -1,7 +1,7 @@
 viv_compiler/__init__.py,sha256=qYCGYC46CCguVk7LybHbWlV1b4dPY7K0UOfrEF8k0E8,592
 viv_compiler/__main__.py,sha256=dyCH7r86O9Nw516E38Gm0gQjcSYDd57dhLGRBPoCi7s,60
 viv_compiler/api.py,sha256=8vr_WoLEzPSOMRNmovewE2f4b8_-r5xp5PdYc7S2rgc,2164
-viv_compiler/cli.py,sha256=6ZMj0TnDNXS99NpOV2Y3CiOVAh-cpknmOACrR_bBmh0,8350
+viv_compiler/cli.py,sha256=BEMXRpOfPal7sri_fzY2zPdeE6QmxgITatfMZoh3HVM,8448
 viv_compiler/py.typed,sha256=qrkHrYJvGoZpU2BpVLNxJB44LlhqVSKyYOwD_L_1m3s,10
 viv_compiler/_samples/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 viv_compiler/_samples/smoke-test.viv,sha256=hBgnuOvO7A78iDZPTM6Z6xlkaLAA9zgmkuxPVwCLUGQ,152
@@ -9,24 +9,25 @@ viv_compiler/backports/__init__.py,sha256=OozGI7C0wkn6Xjn19DPE_SSdSKX-gRiOQu8yoo
 viv_compiler/backports/backports.py,sha256=NkZcknH0-iuZczNfGSlL-3yy9FpL9-Y9j_H65TQs_FA,243
 viv_compiler/config/__init__.py,sha256=A00lpnUKg-q3y_b-cN3jKF9urkGTGjb2Yz_gGc9WCLs,22
 viv_compiler/config/config.py,sha256=y8R2W2mctP6lbyB_aqIAmJINDIqAAXtzPJrA6lYv-bk,3981
-viv_compiler/core/__init__.py,sha256=QHyfqFCifNLT5ZTmLFUMWCURN4BuN2_uY4Z-7wTAeQo,121
-viv_compiler/core/core.py,sha256=1ViI19Qa6F_mQbiqbEC7sYyJGH3VbuABI4mqF9xwFik,7828
-viv_compiler/core/importer.py,sha256=XRv9wum_V4ll_vHU0pyerwmJW1Nr1IVlA_-ALtmzGxo,4877
-viv_compiler/core/postprocessor.py,sha256=EBW8GAJa7Pikln5FzHQEpJ2QfPC66-HOmfAjGIA_HEY,40160
-viv_compiler/core/validator.py,sha256=punxJ-2iPBFhyyR0ZePcyQAjMTma3ENr4gIiRKckWzU,42314
-viv_compiler/core/visitor.py,sha256=t70j4e6CK363h7ey3W-v2_FbGeu80r4fOTK7npgxRmk,46864
+viv_compiler/core/__init__.py,sha256=ZAU-F0_tXtRWRmw-anqCdZZDabN42nCrIfm_74RdBpE,123
+viv_compiler/core/core.py,sha256=bJzNpf6DM8F1ITn7vmCRxsCELnZ2FgY_23eCxULOGao,7828
+viv_compiler/core/includes.py,sha256=Peth-YttHzbyTB9NXoyBKSDKBJ_NX6MEwOTGEUcHvIg,4879
+viv_compiler/core/metadata.py,sha256=QZToKtisN-ZYNckJsejMaGwXsMSR_TI11MbIuAl8_No,2894
+viv_compiler/core/postprocessing.py,sha256=fgogeBR4U92_dH-GBNDFrZqv9CuzCI1nlx7xHs3j6Iw,39073
+viv_compiler/core/validation.py,sha256=_fYvYxl2keAdF0KFx41c3JIl4EchrI9feVSM8VXj-fE,41000
+viv_compiler/core/visitor.py,sha256=ZF6h_Ebj8nujUbxDjNSxK-U2st_Bl6ZX3UFYeu5jBdE,47931
 viv_compiler/grammar/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-viv_compiler/grammar/viv.peg,sha256=otsDwXAAE14XmdzgjL4oPYgY651RgVVHVFQmmyde4TE,10538
+viv_compiler/grammar/viv.peg,sha256=9xGvGl_TgNp0oX66um3Z2RQzG8MOJGBrDEiHoW6sP0I,11152
 viv_compiler/types/__init__.py,sha256=FLwJ0wV_vdR95waeHfZ4YnUIvkK7v8RqR139lpnP1RE,102
-viv_compiler/types/content_public_schemas.py,sha256=4yPq3rEUzvKp6WOBoCERZuifUVtl-bXsSen_eQjithw,22019
-viv_compiler/types/dsl_public_schemas.py,sha256=UMRoL197O0U-UAnpGHE_XXGzdg1I8S2jyXtV71ekoGI,22318
+viv_compiler/types/content_public_schemas.py,sha256=WOHhgjIhoB-jiqHXDjqmnbY0V-QtxMQO9TBo_vOneo4,23422
+viv_compiler/types/dsl_public_schemas.py,sha256=Jzy3zxtjyrnorgD52Lb39t3GCMd-vSRGKYXdBkG2dQA,22556
 viv_compiler/types/internal_types.py,sha256=LOU4kT_tjxjU0CXqnqfluV-EBgX2KkhmUOa07B0i1xo,7816
 viv_compiler/utils/__init__.py,sha256=alIDGBnxWH4JvP-UW-7N99seBBi0r1GV1h8f1ERFBec,21
 viv_compiler/utils/_version.py,sha256=B40VyT6r1P2PNwgWWItzAYhh25_deCqUcl4EaXq0Beg,88
 viv_compiler/utils/utils.py,sha256=TwT9VKV1fXVFLToSXO-Cu046Gu2siA_Y7xGog_Zx9pA,7257
-viv_compiler-0.1.0.dist-info/licenses/LICENSE,sha256=_N1SL7eyeeqRS4HHgl_n85kuwUSw22qWP6IpQZ9F_M4,1066
-viv_compiler-0.1.0.dist-info/METADATA,sha256=GH9QH_XkSBoMYrmmqyTz-hP4EXIdejMDgWzimmgmVFI,7955
-viv_compiler-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-viv_compiler-0.1.0.dist-info/entry_points.txt,sha256=YluMB1bLcPmnfaeAaMAtxXsKCkIEvyhb2dVgkVp55Ko,84
-viv_compiler-0.1.0.dist-info/top_level.txt,sha256=fd_4ocrOmLnp5oEnwxv2_Yt_JkluHdKD-Jr5eN__iaE,13
-viv_compiler-0.1.0.dist-info/RECORD,,
+viv_compiler-0.1.1.dist-info/licenses/LICENSE,sha256=_N1SL7eyeeqRS4HHgl_n85kuwUSw22qWP6IpQZ9F_M4,1066
+viv_compiler-0.1.1.dist-info/METADATA,sha256=MZmgisVHYAOH3B9lZTgkaZgienTQYfAWrRL_f5e_fTU,8427
+viv_compiler-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+viv_compiler-0.1.1.dist-info/entry_points.txt,sha256=YluMB1bLcPmnfaeAaMAtxXsKCkIEvyhb2dVgkVp55Ko,84
+viv_compiler-0.1.1.dist-info/top_level.txt,sha256=fd_4ocrOmLnp5oEnwxv2_Yt_JkluHdKD-Jr5eN__iaE,13
+viv_compiler-0.1.1.dist-info/RECORD,,