viv-compiler 0.1.0__py3-none-any.whl

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/__main__.py

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

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

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

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

viv_compiler/cli.py

@@ -0,0 +1,237 @@
+"""Command‑line interface (CLI) for the Viv DSL compiler.
+
+This CLI is for humans. For programmatic use, call the compiler functions exposed in `api.py`.
+"""
+
+import sys
+import json
+import argparse
+import traceback
+import viv_compiler.config
+from pathlib import Path
+from importlib import resources
+from .api import compile_from_path, get_version
+from viv_compiler.types import CompiledContentBundle
+
+
+def main() -> None:
+    """Command-line interface (CLI) for the Viv DSL compiler."""
+    # Build the parser for command-line arguments
+    parser = _build_parser()
+    # Parse the command-line arguments
+    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")
+        sys.exit(0)
+    # If test mode is engaged, invoke the compiler on a test file and exit
+    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():
+            raise FileNotFoundError(f"Output-file directory does not exist: {path_to_output_file.parent}")
+    else:
+        path_to_output_file = None
+    compiled_content_bundle = _invoke_compiler(args=args)
+    # If we get to here, compilation succeeded
+    print("Success!\n", file=sys.stderr)
+    _emit_results(compiled_content_bundle=compiled_content_bundle, args=args, path_to_output_file=path_to_output_file)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the parser for our command-line arguments.
+
+    Returns:
+        A prepared parser for our command-line arguments.
+    """
+    parser = argparse.ArgumentParser(
+        description="Compile a Viv source file (.viv) to produce a content bundle ready for use in a Viv runtime",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    )
+    parser.add_argument(
+        '-i',
+        '--input',
+        metavar='source_file',
+        type=str,
+        help='relative or absolute path to the Viv source file (.viv) to be compiled'
+    )
+    parser.add_argument(
+        '-o',
+        '--output',
+        metavar='output_file',
+        type=str,
+        default=None,
+        help='path to which output file (.json) will be written'
+    )
+    parser.add_argument(
+        '-s',
+        '--default_salience',
+        metavar='default_salience',
+        type=float,
+        default=viv_compiler.config.DEFAULT_SALIENCE_VALUE,
+        help='default salience value to use when one is not specified'
+    )
+    parser.add_argument(
+        '-a',
+        '--default_associations',
+        metavar='default_associations',
+        type=str,
+        nargs='*',
+        default=viv_compiler.config.DEFAULT_ASSOCIATIONS_VALUE,
+        help='default associations (sequence of strings) to use when not specified'
+    )
+    parser.add_argument(
+        '-r',
+        '--default_reaction_priority',
+        metavar='default_reaction_priority',
+        type=float,
+        default=viv_compiler.config.DEFAULT_REACTION_PRIORITY_VALUE,
+        help='default reaction priority to use when not specified'
+    )
+    parser.add_argument(
+        '-p',
+        '--print',
+        action='store_true',
+        default=False,
+        help='after compilation, print compiled content bundle in console'
+    )
+    parser.add_argument(
+        '-l',
+        '--list',
+        action='store_true',
+        default=False,
+        help='after compilation, list all compiled actions in console'
+    )
+    parser.add_argument(
+        '-m',
+        '--memoization',
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help='enable/disable memoization in the underlying PEG parser',
+    )
+    parser.add_argument(
+        '-d',
+        '--debug',
+        action='store_true',
+        default=False,
+        help='engage debug mode in the underlying PEG parser'
+    )
+    parser.add_argument(
+        '-t',
+        '--test',
+        action='store_true',
+        default=False,
+        help='run a simple smoke test to confirm the compiler is installed correctly'
+    )
+    parser.add_argument(
+        '-v',
+        '--version',
+        action='store_true',
+        help='print compiler version and exit'
+    )
+    return parser
+
+
+def _run_smoke_test(args: argparse.Namespace) -> None:
+    """Runs a smoke test to confirm that the Viv compiler installation appears to be functioning.
+
+    Args:
+        args: Parsed command-line arguments.
+
+    Side Effects:
+        The results are printed out to `stderr`.
+    """
+    with resources.as_file(resources.files("viv_compiler._samples") / "smoke-test.viv") as sample_path:
+        compile_from_path(
+            source_file_path=sample_path,
+            default_salience=float(args.default_salience),
+            default_associations=args.default_associations,
+            default_reaction_priority=float(args.default_priority),
+            debug=False,
+            use_memoization=True,
+        )
+        print("Smoke test passed: Viv compiler installation looks good.\n", file=sys.stderr)
+
+
+def _invoke_compiler(args: argparse.Namespace) -> CompiledContentBundle:
+    """Invokes the compiler on the user's specified source file, with their specified configuration settings.
+
+    Args:
+        args: Parsed command-line arguments.
+
+    Returns:
+        The compiled content bundle, if compilation succeeds.
+    """
+    source_file_path = Path(args.input).expanduser().resolve()
+    try:
+        compiled_content_bundle = compile_from_path(
+            source_file_path=source_file_path,
+            default_salience=float(args.default_salience),
+            default_associations=args.default_associations,
+            default_reaction_priority=float(args.default_priority),
+            debug=args.debug,
+            use_memoization=args.memoization,
+        )
+        return compiled_content_bundle
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except BrokenPipeError:
+        # noinspection PyBroadException
+        try:
+            sys.stderr.close()
+        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()
+        sys.exit(1)
+
+
+def _emit_results(
+    compiled_content_bundle: CompiledContentBundle,
+    args: argparse.Namespace,
+    path_to_output_file: Path | None
+) -> None:
+    """Emits the compiled content bundle according to the user's specified output parameters.
+
+    Args:
+        compiled_content_bundle: A compiled content bundle.
+        args: Parsed command-line arguments.
+
+    Side Effects:
+        The results are written to file and/or printed to `stderr` and `stdout`, depending on user parameters.
+    """
+    # 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)
+        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
+    # `stdout`, with headers piped to `stderr`).
+    if args.list:
+        lines = []
+        action_names = [action_definition['name'] for action_definition in compiled_content_bundle['actions'].values()]
+        for action_name in sorted(action_names):
+            lines.append(action_name)
+        if not action_names:
+            lines.append("N/A")
+        print(f"\t== 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
+    if path_to_output_file:
+        with open(path_to_output_file, "w", encoding="utf-8") as outfile:
+            outfile.write(json.dumps(compiled_content_bundle, ensure_ascii=False))
+        print(f"Wrote output to file: {path_to_output_file}\n", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

viv_compiler/config/__init__.py

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

viv_compiler/config/config.py

@@ -0,0 +1,88 @@
+"""System configuration for the Viv DSL compiler.
+
+Defines a set of constants constituting the configuration parameters necessary for the function
+of the compiler. These are only meant to be modified in the course of system development, i.e.,
+not by users. That said, user-supplied default values for the `saliences` and `associations`
+fields will be used programmatically to update the dictionary below containing default values
+for optional fields in action definitions.
+"""
+
+from viv_compiler.types import ExpressionDiscriminator, ReferencePathComponentDiscriminator
+
+
+# Name of the root symbol in the Viv DSL grammar
+GRAMMAR_ROOT_SYMBOL = "file"
+
+# Name of the symbol associated with comments in the Viv DSL grammar
+GRAMMAR_COMMENT_SYMBOL = "comment"
+
+# Viv expression types that support negation. While the grammar (and therefore the parser)
+# will allow for negation in other expression types, the validator will use this config
+# parameter to enforce this policy.
+NEGATABLE_EXPRESSION_TYPES = {
+    ExpressionDiscriminator.ADAPTER_FUNCTION_CALL,
+    ExpressionDiscriminator.COMPARISON,
+    ExpressionDiscriminator.CONJUNCTION,
+    ExpressionDiscriminator.DISJUNCTION,
+    ExpressionDiscriminator.ENTITY_REFERENCE,
+    ExpressionDiscriminator.LOCAL_VARIABLE_REFERENCE,
+    ExpressionDiscriminator.LOOP,
+    ExpressionDiscriminator.MEMBERSHIP_TEST,
+    ExpressionDiscriminator.TROPE_FIT_EXPRESSION,
+}
+
+# Default values for various optional fields in an action definition
+ACTION_DEFINITION_OPTIONAL_FIELD_DEFAULT_VALUES = {
+    "gloss": None,
+    "report": None,
+    "control": {},
+    "tags": {"type": "list", "value": []},  # This is an expression that produces a list, not a list itself
+    "preconditions": [],
+    "scratch": [],
+    "effects": [],
+    "reactions": [],
+    "saliences": None,  # Set by user via CLI, which uses a default value if none is provided
+    "associations": None,  # Set by user via CLI, which uses a default value if none is provided
+    "embargoes": [],
+}
+
+# Default values for the options in an action definition's reaction field
+REACTION_FIELD_DEFAULT_OPTIONS = {
+    "urgent": {"type": "bool", "value": False},
+    "priority": None,  # Set by user via CLI, which uses a default value if none is provided
+    "killCode": None,
+    "where": None,
+    "when": None,
+    "abandonmentConditions": [],
+}
+
+# The path to which the global-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 = [{
+    "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
+
+# A default associations value, to be used when the API caller does not provide one
+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

viv_compiler/core/__init__.py

@@ -0,0 +1,5 @@
+from .core import *
+from .importer import *
+from .postprocessor import *
+from .validator import *
+from .visitor import *

viv_compiler/core/core.py

@@ -0,0 +1,185 @@
+"""Compiler for the Viv DSL.
+
+This high-level module invokes other components of the compiler out the full compilation pipeline:
+
+  * Loading and parsing of the Viv DSL grammar.
+  * Loading and parsing of a Viv source file.
+  * Walking the parse tree with a visitor, to produce an AST.
+  * Combining of ASTs, to honor 'include' statements (imports between Viv files).
+  * Postprocessing of a combined AST, to produce full-fledged trope and action definitions,
+    together constituting a Viv compiled content bundle.
+  * Validation of the Viv compiled content bundle.
+  * Emitting JSON output for the validated Viv compiled content bundle.
+
+The entrypoint function is `compile_viv_source_code()`, and everything else
+is only meant to be invoked internally, i.e., within this module.
+"""
+
+__all__ = ["compile_viv_source_code"]
+
+import arpeggio
+import viv_compiler.config
+import viv_compiler.types
+from typing import Any
+from pathlib import Path
+from importlib.resources import files
+from .importer import integrate_imported_files
+from .visitor import Visitor
+from .postprocessor import postprocess_combined_ast
+from .validator import validate_content_bundle
+# noinspection PyUnresolvedReferences
+from arpeggio.cleanpeg import ParserPEG
+
+
+def compile_viv_source_code(
+    source_file_path: Path,
+    default_salience: float,
+    default_associations: list[str],
+    default_reaction_priority: float,
+    use_memoization: bool,
+    debug = False,
+) -> viv_compiler.types.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 (default: `False`).
+
+    Returns:
+        The compiled content bundle.
+    """
+    # Honor user-supplied config parameters, or the associated default values if none were supplied
+    _honor_user_supplied_config_parameters(
+        default_salience=default_salience,
+        default_associations=default_associations,
+        default_reaction_priority=default_reaction_priority,
+    )
+    # Create a Viv parser
+    viv_parser = _create_viv_parser(use_memoization=use_memoization, debug=debug)
+    # Load the source file to be compiled
+    source_file_contents = _load_source_file(source_file_path=source_file_path)
+    # Parse the source file to produce a parse tree
+    tree = viv_parser.parse(_input=source_file_contents)
+    # Following the visitor pattern in parsing, traverse the parse tree to gradually
+    # 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(
+        viv_parser=viv_parser,
+        ast=ast,
+        entry_point_file_path=source_file_path
+    )
+    # Conduct postprocessing to produce a final compiled content bundle
+    compiled_content_bundle: viv_compiler.types.CompiledContentBundle = postprocess_combined_ast(
+        combined_ast=combined_ast
+    )
+    # Conduct final validation. This will throw an error if any serious issues are detected.
+    validate_content_bundle(content_bundle=compiled_content_bundle)
+    # Finally, return the compiled content bundle
+    return compiled_content_bundle
+
+
+def _honor_user_supplied_config_parameters(
+    default_salience: float,
+    default_associations: list[str],
+    default_reaction_priority: float,
+) -> None:
+    """Updates the global Viv compiler config to honor any user-supplied parameters.
+
+    Args:
+        default_salience: A user-provided default salience value to use when one is not specified in
+            an action definition. The CLI provides a default value if the user does not supply one.
+        default_associations: A user-provided default associations value to use when one is not specified
+            in an action definition. The CLI provides a default value if the user does not supply one.
+        default_reaction_priority: A user-provided default reaction priority to use when one is not
+            specified in a reaction declaration.
+
+    Returns:
+        The compiled content bundle JSON string, if no output file path was provided, else None.
+    """
+    viv_compiler.config.ACTION_DEFINITION_OPTIONAL_FIELD_DEFAULT_VALUES["saliences"] = {
+        "default": {'type': 'float', 'value': default_salience},
+        "variable": viv_compiler.config.SALIENCES_VARIABLE_NAME,
+        "body": [],
+    }
+    default_associations_expression = {
+        "type": "list",
+        "value": [{"type": "string", "value": association} for association in default_associations]
+    }
+    viv_compiler.config.ACTION_DEFINITION_OPTIONAL_FIELD_DEFAULT_VALUES["associations"] = {
+        "default": default_associations_expression,
+        "variable": viv_compiler.config.ASSOCIATIONS_VARIABLE_NAME,
+        "body": [],
+    }
+    viv_compiler.config.REACTION_FIELD_DEFAULT_OPTIONS["priority"] = {
+        "type": "float",
+        "value": default_reaction_priority
+    }
+
+
+def _create_viv_parser(use_memoization: bool, debug: bool) -> ParserPEG:
+    """Return a PEG parser initialized for the Viv DSL, with user-defined settings.
+
+    Args:
+        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:
+        A PEG parser initialized for the Viv DSL.
+    """
+    # Load the Viv DSL grammar
+    viv_grammar = files("viv_compiler.grammar").joinpath("viv.peg").read_text(encoding="utf-8")
+    # Prepare and return the parser
+    viv_parser = ParserPEG(
+        language_def=viv_grammar,
+        root_rule_name=viv_compiler.config.GRAMMAR_ROOT_SYMBOL,
+        comment_rule_name=viv_compiler.config.GRAMMAR_COMMENT_SYMBOL,
+        reduce_tree=False,
+        ws="\t\n\r ",
+        memoization=use_memoization,
+        debug=debug
+    )
+    return viv_parser
+
+
+def _load_source_file(source_file_path: Path) -> str:
+    """Return the contents of the Viv source file at the given path.
+
+    Args:
+        source_file_path: Path to the Viv source file to be compiled.
+
+    Returns:
+        Contents of the Viv source file at the given path.
+    """
+    try:
+        source_file_contents = open(source_file_path, encoding="utf8").read()
+    except FileNotFoundError:
+        raise FileNotFoundError(f"Bad input file path (file not found): {source_file_path}")
+    return source_file_contents
+
+
+def _sanitize_ast(ast: Any) -> Any:
+    """Returns a deep copy of the given AST with all (nested) Arpeggio containers replaced with plain lists.
+
+    Args:
+        ast: An AST produced by our visitor.
+
+    Returns:
+        A deep copy of the given AST with all (nested) Arpeggio containers replaced with plain lists.
+    """
+    if isinstance(ast, arpeggio.SemanticActionResults):
+        return [_sanitize_ast(v) for v in ast]
+    if isinstance(ast, dict):
+        return {k: _sanitize_ast(v) for k, v in ast.items()}
+    if isinstance(ast, list):
+        return [_sanitize_ast(v) for v in ast]
+    if isinstance(ast, tuple):
+        return [_sanitize_ast(v) for v in ast]
+    return ast