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

viv_compiler/{utils/_version.py → _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/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

viv_compiler/config/config.py

@@ -25,9 +25,9 @@ NEGATABLE_EXPRESSION_TYPES = {
     ExpressionDiscriminator.CONJUNCTION,
     ExpressionDiscriminator.DISJUNCTION,
     ExpressionDiscriminator.ENTITY_REFERENCE,
-    ExpressionDiscriminator.LOCAL_VARIABLE_REFERENCE,
     ExpressionDiscriminator.LOOP,
     ExpressionDiscriminator.MEMBERSHIP_TEST,
+    ExpressionDiscriminator.SYMBOL_REFERENCE,
     ExpressionDiscriminator.TROPE_FIT_EXPRESSION,
 }
 
@@ -56,28 +56,21 @@ REACTION_FIELD_DEFAULT_OPTIONS = {
     "abandonmentConditions": [],
 }
 
-# The path to which the global-variable sigil `$` expands. This sigil is really just syntactic sugar for
+# Name for the special action self-reference role, which is always bound to the action itself
+ACTION_SELF_REFERENCE_ROLE_NAME = 'this'
+
+# A set containing the special role names that are automatically created by Viv at various points
+SPECIAL_ROLE_NAMES = {'hearer', ACTION_SELF_REFERENCE_ROLE_NAME}
+
+# The path to which the scratch-variable sigil `$` expands. This sigil is really just syntactic sugar for
 # the path `@this.scratch`, which stores a blackboard local to a performed action. For instance, the scratch
-# operation `$foo.bar = 99` is syntactic sugar for the expression `@this.scratch.foo.bar = 99`.
-GLOBAL_VARIABLE_REFERENCE_ANCHOR = "this"
-GLOBAL_VARIABLE_REFERENCE_PATH_PREFIX = [{
+# operation `$@foo.bar = 99` is syntactic sugar for the expression `@this.scratch.foo.bar = 99`.
+SCRATCH_VARIABLE_REFERENCE_ANCHOR = ACTION_SELF_REFERENCE_ROLE_NAME
+SCRATCH_VARIABLE_REFERENCE_PATH_PREFIX = [{
     "type": ReferencePathComponentDiscriminator.REFERENCE_PATH_COMPONENT_PROPERTY_NAME,
     "name": "scratch",
 }]
 
-# The path to which the local-variable sigil `$$` expands. This sigil is really just a property lookup in
-# the special `__locals__` field of an evaluation context, which is a temporary store for scoped local
-# variables. For instance, the local-variable reference `$$c` defines an attempt to access `__locals__.c`
-# in an evaluation context. Unlike the `$` sigil, this is not syntactic sugar, since the Viv author has
-# no other way to reference local variables.
-LOCAL_VARIABLE_REFERENCE_PATH = ["__locals__"]
-
-# Name for the variable to which each character is set when computing their salience for an action
-SALIENCES_VARIABLE_NAME = "c"
-
-# Name for the variable to which each character is set when computing their associations for an action
-ASSOCIATIONS_VARIABLE_NAME = "c"
-
 # A default salience value, to be used when the API caller does not provide one
 DEFAULT_SALIENCE_VALUE = 1.0
 
@@ -86,3 +79,9 @@ DEFAULT_ASSOCIATIONS_VALUE = []
 
 # A default reaction priority value, to be used when the API caller does not provide one
 DEFAULT_REACTION_PRIORITY_VALUE = 1.0
+
+# A list containing the names of action fields in which assignments are permitted
+ACTION_FIELDS_PERMITTING_ASSIGNMENTS = ("scratch", "effects",)
+
+# A list containing the names of action fields in which reactions are permitted
+ACTION_FIELDS_PERMITTING_REACTIONS = ("reactions",)

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
@@ -106,7 +106,7 @@ def _honor_user_supplied_config_parameters(
     """
     viv_compiler.config.ACTION_DEFINITION_OPTIONAL_FIELD_DEFAULT_VALUES["saliences"] = {
         "default": {'type': 'float', 'value': default_salience},
-        "variable": viv_compiler.config.SALIENCES_VARIABLE_NAME,
+        "variable": None,
         "body": [],
     }
     default_associations_expression = {
@@ -115,7 +115,7 @@ def _honor_user_supplied_config_parameters(
     }
     viv_compiler.config.ACTION_DEFINITION_OPTIONAL_FIELD_DEFAULT_VALUES["associations"] = {
         "default": default_associations_expression,
-        "variable": viv_compiler.config.ASSOCIATIONS_VARIABLE_NAME,
+        "variable": None,
         "body": [],
     }
     viv_compiler.config.REACTION_FIELD_DEFAULT_OPTIONS["priority"] = {

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,71 @@
+"""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": []
+    }
+    all_referenced_enum_names = []
+    all_referenced_function_names = []
+    for ast_chunk in action_definitions + trope_definitions:
+        # Compile all referenced enums
+        all_referenced_enum_names.extend(viv_compiler.utils.get_all_referenced_enum_names(ast_chunk=ast_chunk))
+        # Compile all referenced adapter functions
+        all_referenced_function_names.extend(viv_compiler.utils.get_all_referenced_adapter_function_names(
+            ast_chunk=ast_chunk
+        ))
+    metadata["referencedEnums"].extend(sorted(set(all_referenced_enum_names)))
+    metadata["referencedFunctionNames"].extend(sorted(set(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