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

viv_compiler/types/content_public_schemas.py

@@ -20,6 +20,7 @@ if TYPE_CHECKING:
         FloatField,
         IntField,
         ListField,
+        LocalVariable,
         ObjectField,
         StringField,
         TemplateStringField,
@@ -46,9 +47,9 @@ class CompiledContentBundleMetadata(TypedDict):
     The metadata here is also used to support validation during initialization of a target application's
     Viv adapter by, e.g., confirming that any referenced enums and adapter functions actually exist.
     """
-    # The Viv compiler version at the time of compiling this content bundle. If this
-    # version number corresponds to the version number for a Viv runtime, the content
-    # bundle is guaranteed to be compatible with that runtime.
+    # The Viv compiler version at the time of compiling this content bundle. This will be a
+    # `MAJOR.MINOR.PATCH` version, and all Viv runtimes will require that the `MAJOR.MINOR`
+    # portion matches that of the runtime version at hand.
     vivVersion: str
     # An array containing the names of all enums referenced in the content bundle. This is
     # used for validation during the initialization of a target application's Viv adapter.
@@ -94,7 +95,7 @@ class TropeDefinition(TypedDict):
     name: TropeName
     # The parameters for the trope. These take entity references as arguments,
     # allowing the conditions to refer to those entities.
-    params: list[TropeParamName]
+    params: list[TropeParam]
     # The ordered set of conditions composing the trope
     conditions: list[Expression]
 
@@ -102,6 +103,16 @@ class TropeDefinition(TypedDict):
 # A unique name for a trope
 TropeName = str
 
+
+class TropeParam(TypedDict):
+    """A trope parameter."""
+    # The name of the trope parameter (unique only within the trope definition)
+    name: TropeParamName
+    # Whether this is an entity trope parameter, in which case arguments
+    # for this parameter should be entity IDs.
+    isEntityParam: bool
+
+
 # A unique trope parameter name
 TropeParamName = str
 
@@ -129,8 +140,8 @@ class ActionDefinition(TypedDict):
     preconditions: dict[RoleName, list[WrappedExpression]]
     # An ordered set of expressions that prepare a set of temporary variables that may be referenced
     # downstream in the action definition. These temporary variables can be referenced by an author
-    # using the `$` sigil, but this is syntactic sugar for `@this.scratch` — e.g., `$foo` is equivalent
-    # to `@this.scratch.foo`.
+    # using the `$` sigil, but this is syntactic sugar for `@this.scratch` — e.g., `$&foo` is equivalent
+    # to `@this.scratch.foo`, with the second sigil indicating the type of the scratch variable.
     scratch: list[Expression]
     # An ordered set of expressions that, when executed, cause updates to the target application state
     effects: list[WrappedExpression]
@@ -250,25 +261,19 @@ class ReactionValue(TypedDict):
     # The name of the target action, i.e., the one queued up by this reaction
     actionName: ActionName
     # Specification for how to precast entities in (a subset of) the roles of the target action
-    bindings: list[ReactionBinding]
+    bindings: list[ReactionRoleBindings]
     # Parameterization of the reaction along various options
     options: ReactionOptions
 
 
-class ReactionBinding(TypedDict):
+class ReactionRoleBindings(TypedDict):
     """An expression specifying how to precast a particular role in a reaction's target action."""
-    # Discriminator for Viv binding expressions
-    type: Literal[ExpressionDiscriminator.BINDING]
-    # The actual expression value
-    value: ReactionBindingValue
-
-
-class ReactionBindingValue(TypedDict):
-    """Value of a binding expression."""
-    # The name of the role in the target action that will be precast via this binding
+    # The name of the role in the target action that will be precast via these bindings
     role: RoleName
-    # An expression that should evaluate to the entity to precast in the role associated with this binding
-    entity: Expression
+    # Whether the bindings are marked as being associated with an entity role
+    isEntityRole: bool
+    # An expression that should evaluate to the candidate(s) to precast in the role associated with this binding
+    candidates: Expression
 
 
 class ReactionOptions(TypedDict, total=False):
@@ -313,10 +318,10 @@ class Saliences(TypedDict):
     # which no `body` expressions hold. This will always be structured as a Viv enum,
     # int, or float, where even the enum should resolve to a numeric value.
     default: Union[Enum, IntField, FloatField]
-    # The name of the variable to which a character will be bound when computing a salience for
-    # them. This allows for evaluation of the body expressions, which may refer to this variable
-    # in order to do things like conditionalize salience based on the character at hand.
-    variable: VariableName
+    # If there is a non-empty body, the local variable to which a character will be bound when computing
+    # a salience for them. This allows for evaluation of the body expressions, which may refer to this
+    # variable in order to do things like conditionalize salience based on the character at hand.
+    variable: LocalVariable | None
     # An ordered array of Viv expressions that will each evaluate to a numeric value, as in the
     # `default` property. These will be evaluated in turn, with the first numeric evaluated value
     # being assigned as the character's salience. If no body expression evaluates to a numeric
@@ -332,10 +337,10 @@ class Associations(TypedDict):
     # `body` expressions hold. This will always be structured as a Viv list whose elements will be
     # simple Viv string expressions.
     default: ListField
-    # The name of the variable to which a character will be bound when computing associations for
-    # them. This allows for evaluation of the body expressions, which may refer to this variable
-    # in order to do things like conditionalize associations based on the character at hand.
-    variable: VariableName
+    # If there is a non-empty body, the local variable to which a character will be bound when computing
+    # associations for them. This allows for evaluation of the body expressions, which may refer to this
+    # variable in order to do things like conditionalize associations based on the character at hand.
+    variable: LocalVariable | None
     # An ordered array of Viv expressions that will each evaluate to Viv lists containing simple
     # Viv string expressions, as in the `default` property. These will be evaluated in turn, with
     # all the results being concatenated together to compose the associations for the character

viv_compiler/types/dsl_public_schemas.py

@@ -36,7 +36,6 @@ Expression: TypeAlias = Annotated[
         "FloatField",
         "IntField",
         "ListField",
-        "LocalVariableReference",
         "Loop",
         "MembershipTest",
         "NullField",
@@ -44,6 +43,7 @@ Expression: TypeAlias = Annotated[
         "Reaction",
         "RoleUnpacking",
         "StringField",
+        "SymbolReference",
         "TemplateStringField",
         "TropeFitExpression",
     ],
@@ -56,7 +56,6 @@ class ExpressionDiscriminator(StrEnum):
     ADAPTER_FUNCTION_CALL = "adapterFunctionCall"
     ASSIGNMENT = "assignment"
     ARITHMETIC_EXPRESSION = "arithmeticExpression"
-    BINDING = "binding"
     BOOL = "bool"
     CHANCE_EXPRESSION = "chanceExpression"
     COMPARISON = "comparison"
@@ -69,7 +68,6 @@ class ExpressionDiscriminator(StrEnum):
     FLOAT = "float"
     INT = "int"
     LIST = "list"
-    LOCAL_VARIABLE_REFERENCE = "localVariableReference"
     LOOP = "loop"
     MEMBERSHIP_TEST = "membershipTest"
     NULL_TYPE = "nullType"
@@ -77,6 +75,7 @@ class ExpressionDiscriminator(StrEnum):
     REACTION = "reaction"
     ROLE_UNPACKING = "roleUnpacking"
     STRING = "string"
+    SYMBOL_REFERENCE = "symbolReference"
     TEMPLATE_STRING = "templateString"
     TROPE_FIT_EXPRESSION = "tropeFitExpression"
 
@@ -97,7 +96,7 @@ class AdapterFunctionCall(NegatableExpression):
     `transport()` exposed in the adapter. The Viv runtime confirms the existence of all
     referenced function names during adapter initialization.
     """
-    # Discriminant for a Viv adapter function call
+    # Discriminator for a Viv adapter function call
     type: Literal[ExpressionDiscriminator.ADAPTER_FUNCTION_CALL]
     # The actual expression value
     value: AdapterFunctionCallValue
@@ -122,7 +121,7 @@ AdapterFunctionName = str
 
 class ArithmeticExpression(TypedDict):
     """A Viv arithmetic expression, which accepts two numeric operands and evaluates to a number."""
-    # Discriminant for a Viv arithmetic expression
+    # Discriminator for a Viv arithmetic expression
     type: Literal[ExpressionDiscriminator.ARITHMETIC_EXPRESSION]
     # The actual expression value
     value: ArithmeticExpressionValue
@@ -144,7 +143,7 @@ ArithmeticOperator = Literal["+", "-", "*", "/"]
 
 class Assignment(TypedDict):
     """A Viv assignment (or update)."""
-    # Discriminant for a Viv assignment
+    # Discriminator for a Viv assignment
     type: Literal[ExpressionDiscriminator.ASSIGNMENT]
     # The actual expression value
     value: AssignmentValue
@@ -153,10 +152,13 @@ class Assignment(TypedDict):
 class AssignmentValue(TypedDict):
     """The actual expression value for a Viv assignment."""
     # An expression whose evaluation will be used as the left operand in the assignment/update
-    left: Expression
+    left: Union[EntityReference, SymbolReference]
     # The assignment/update operator
     operator: AssignmentOperator
-    # An expression whose evaluation will be used as the right operand in the assignment/update
+    # An expression whose evaluation will be used as the right operand in the assignment/update. Note
+    # that for assignments that update persistent entity data, the value will always be proactively
+    # dehydrated, such that all entity data included in the value will be converted into the associated
+    # entity ID. We do this to prevent several potential issues, and the data can be rehydrated later on.
     right: Expression
 
 
@@ -166,7 +168,7 @@ AssignmentOperator = Literal["=", "+=", "-=", "*=", "/=", "append", "remove"]
 
 class BoolField(TypedDict):
     """A Viv boolean."""
-    # Discriminant for a Viv boolean
+    # Discriminator for a Viv boolean
     type: Literal[ExpressionDiscriminator.BOOL]
     # The boolean literal to which this expression will evaluate
     value: bool
@@ -178,7 +180,7 @@ class ChanceExpression(TypedDict):
     This is a kind of condition that evaluates to True if the specified probability value (a number
     between 0.0 and 1.0) exceeds a pseudorandom number generated by the Viv interpreter.
     """
-    # Discriminant for a Viv chance expression
+    # Discriminator for a Viv chance expression
     type: Literal[ExpressionDiscriminator.CHANCE_EXPRESSION]
     # The specified probability, which the compiler guarantees to be a number in the range [0, 1]
     value: float
@@ -186,7 +188,7 @@ class ChanceExpression(TypedDict):
 
 class Comparison(NegatableExpression):
     """A Viv comparison, whereby two values are compared using a comparator."""
-    # Discriminant for a Viv comparison
+    # Discriminator for a Viv comparison
     type: Literal[ExpressionDiscriminator.COMPARISON]
     # The actual expression value
     value: ComparisonValue
@@ -208,7 +210,7 @@ Comparator = Literal["==", ">", ">=", "<", "<=", "!="]
 
 class Conditional(TypedDict):
     """A Viv conditional expression, allowing for branching based on the value of a test."""
-    # Discriminant for a Viv conditional
+    # Discriminator for a Viv conditional
     type: Literal[ExpressionDiscriminator.CONDITIONAL]
     # The actual expression value
     value: ConditionalValue
@@ -237,7 +239,7 @@ class Conjunction(NegatableExpression):
     This kind of expression takes multiple expressions as operands and evaluates to
     `True` if and only if all the respective expressions evaluate to truthy values.
     """
-    # Discriminant for a Viv conjunction
+    # Discriminator for a Viv conjunction
     type: Literal[ExpressionDiscriminator.CONJUNCTION]
     # The actual expression value
     value: ConjunctionValue
@@ -257,7 +259,7 @@ class Disjunction(NegatableExpression):
     This kind which takes multiple expressions and evaluates to `True` if and only
     if at least one of the respective expressions evaluate to a truthy value.
     """
-    # Discriminant for a Viv disjunction
+    # Discriminator for a Viv disjunction
     type: Literal[ExpressionDiscriminator.DISJUNCTION]
     # The actual expression value
     value: DisjunctionValue
@@ -272,39 +274,49 @@ class DisjunctionValue(TypedDict):
 
 
 class EntityReference(NegatableExpression):
-    """A Viv entity reference, structured as an anchor role and a path to a specific property value.
+    """A Viv entity reference, structured as an anchor name and a (possibly empty) path to a specific property value.
 
-    Usually, the property is on the entity cast into the anchor role, but this is not the case if
-    the reference contains a pointer. For instance, `@person.boss->boss->traits.cruel` would return
-    the value stored at the path `traits.cruel` on the boss of the boss of the entity cast in the
-    anchor role `@person`.
+    Usually, the property is on the anchor entity, but this is not the case if the reference contains
+    a pointer. For instance, `@person.boss->boss->traits.cruel` would return the value stored at the
+    path `traits.cruel` on the boss of the boss of the entity cast in the anchor role `@person`.
 
-    Note that the compiler currently prevents an author from anchoring an entity reference in a
-    symbol role, which allows the interpreter to assume that the anchor role binds an entity.
+    Note that the compiler prevents an author from anchoring an entity reference in a symbol.
 
-    Also note that references anchored in global variables, e.g. `$foo.bar.baz`, are compiled
-    to entities anchored in role references -- this is because `$` is really just syntactic
-    sugar for `@this.scratch.`.
+    Also note that references anchored in scratch variables, e.g. `$@foo.bar.baz`, are compiled
+    to entity references -- this is because `$` is really just syntactic sugar for `@this.scratch.`,
+    with the next sigil indicating the type of the scratch variable.
     """
-    # Discriminant for a Viv reference
+    # Discriminator for a Viv entity reference
     type: Literal[ExpressionDiscriminator.ENTITY_REFERENCE]
     # The actual expression value
-    value: EntityReferenceValue
+    value: ReferenceValue
 
 
-class EntityReferenceValue(TypedDict):
-    """The actual expression value for a Viv entity reference."""
-    # The name of the role that anchors this reference
-    anchor: RoleName
-    # If applicable, the path to a specified property value. If the reference is just to
-    # the entity itself, this will be an empty list. Otherwise, it will specify a path
-    # to a specific property value, either on that entity or another one (via a pointer).
+class SymbolReference(NegatableExpression):
+    """A Viv symbol reference, structured as an anchor name and a (possibly empty) path to a specific property value."""
+    # Discriminator for a Viv symbol reference
+    type: Literal[ExpressionDiscriminator.SYMBOL_REFERENCE]
+    # The actual expression value
+    value: ReferenceValue
+
+
+class ReferenceValue(TypedDict):
+    """The actual expression value for a Viv entity reference or symbol reference."""
+    # Whether the anchor is a local variable. This is a common pattern when an author loops over a role
+    # unpacking, where the members of the group role can only be referenced individually by setting each
+    # one to a local variable (the loop variable).
+    local: bool
+    # The name anchoring this reference
+    anchor: Union[RoleName, VariableName]
+    # If applicable, the path to a specified property value. If the reference is just to the entity
+    # or symbol itself, this will be an empty list. Otherwise, it will specify a path to a specific
+    # property value, either on that entity or symbol or another entity (via a pointer).
     path: list[ReferencePathComponent]
 
 
 class ReferencePathComponentPropertyName(TypedDict, total=False):
     """A component of a Viv reference path specifying a property to access."""
-    # Discriminant for a property-name reference path component
+    # Discriminator for a property-name reference path component
     type: Literal[ReferencePathComponentDiscriminator.REFERENCE_PATH_COMPONENT_PROPERTY_NAME]
     # The name of the property to access
     name: str
@@ -315,7 +327,7 @@ class ReferencePathComponentPropertyName(TypedDict, total=False):
 
 class ReferencePathComponentPointer(TypedDict, total=False):
     """A component of a Viv reference path specifying a pointer to dereference."""
-    # Discriminant for a pointer reference path component
+    # Discriminator for a pointer reference path component
     type: Literal[ReferencePathComponentDiscriminator.REFERENCE_PATH_COMPONENT_POINTER]
     # The name of the property to access in the entity data of the entity targeted by the pointer
     propertyName: str
@@ -330,7 +342,7 @@ class ReferencePathComponentLookup(TypedDict, total=False):
 
     The key/index can be specified by an arbitrary Viv expression.
     """
-    # Discriminant for a lookup reference path component
+    # Discriminator for a lookup reference path component
     type: Literal[ReferencePathComponentDiscriminator.REFERENCE_PATH_COMPONENT_LOOKUP]
     # An expression that should evaluate to a valid property key (string or integer)
     key: Expression
@@ -341,11 +353,11 @@ class ReferencePathComponentLookup(TypedDict, total=False):
 
 class ReferencePathComponentDiscriminator(StrEnum):
     """Enum containing discriminators for the possible reference path components."""
-    # Discriminant for a property-name reference path component
+    # Discriminator for a property-name reference path component
     REFERENCE_PATH_COMPONENT_PROPERTY_NAME = "referencePathComponentPropertyName"
-    # Discriminant for a pointer reference path component
+    # Discriminator for a pointer reference path component
     REFERENCE_PATH_COMPONENT_POINTER = "referencePathComponentPointer"
-    # Discriminant for a lookup reference path component
+    # Discriminator for a lookup reference path component
     REFERENCE_PATH_COMPONENT_LOOKUP = "referencePathComponentLookup"
 
 
@@ -362,7 +374,7 @@ class Enum(TypedDict):
 
     Enums are resolved by the target application at runtime.
     """
-    # Discriminant for a Viv enum
+    # Discriminator for a Viv enum
     type: Literal[ExpressionDiscriminator.ENUM]
     # The actual expression value
     value: EnumValue
@@ -395,13 +407,13 @@ class EvalFailSafeField(TypedDict):
     A Viv author may specify an attempt to access a property that may not exist, safely,
     via the eval fail-safe operator `?`, as in this example: `@foo.bar?.baz`.
     """
-    # Discriminant for the Viv eval fail-safe operator
+    # Discriminator for the Viv eval fail-safe operator
     type: Literal[ExpressionDiscriminator.EVAL_FAIL_SAFE]
 
 
 class FloatField(TypedDict):
     """A Viv floating-point number."""
-    # Discriminant for a Viv floating-point number
+    # Discriminator for a Viv floating-point number
     type: Literal[ExpressionDiscriminator.FLOAT]
     # The float literal to which this expression will evaluate
     value: float
@@ -409,7 +421,7 @@ class FloatField(TypedDict):
 
 class IntField(TypedDict):
     """A Viv integer."""
-    # Discriminant for a Viv integer
+    # Discriminator for a Viv integer
     type: Literal[ExpressionDiscriminator.INT]
     # The integer literal to which this expression will evaluate
     value: int
@@ -420,38 +432,15 @@ class ListField(TypedDict):
 
     Once evaluated, the result will contain the respective evaluations of the expressions, in that same order.
     """
-    # Discriminant for a Viv list
+    # Discriminator for a Viv list
     type: Literal[ExpressionDiscriminator.LIST]
     # The actual expression value
     value: list[Expression]
 
 
-class LocalVariableReference(NegatableExpression):
-    """A Viv local-variable reference, meaning a reference anchored in a local variable.
-
-    This kind of expression is structured as an anchor (the local variable name) with a subsequent path
-    to a specific property value. If a local variable is bound to an entity, this works just like an
-    entity reference — common when looping over role unpackings. Local variables may, however, hold
-    arbitrary values to which authors can refer.
-    """
-    # Discriminant for a Viv local-variable reference
-    type: Literal[ExpressionDiscriminator.LOCAL_VARIABLE_REFERENCE]
-    # The actual expression value
-    value: LocalVariableReferenceValue
-
-
-class LocalVariableReferenceValue(TypedDict):
-    """The actual expression value for a Viv local-variable reference."""
-    # The name of the local variable that anchors this reference
-    anchor: VariableName
-    # If applicable, the path to a specified property value. If the reference is just to the
-    # variable's value itself, this will be an empty list. Otherwise, it specifies the path.
-    path: list[ReferencePathComponent]
-
-
 class Loop(TypedDict):
     """A Viv loop, allowing for iteration over some iterable value."""
-    # Discriminant for a Viv loop
+    # Discriminator for a Viv loop
     type: Literal[ExpressionDiscriminator.LOOP]
     # The actual expression value
     value: LoopValue
@@ -461,15 +450,22 @@ class LoopValue(TypedDict):
     """The actual expression value for a Viv loop."""
     # An expression that should evaluate to a value that is iterable in the runtime at hand.
     iterable: Expression
-    # Name of the variable to which each member of the iterable is assigned
-    # on its respective iteration of the loop.
-    variable: VariableName
+    # The local variable to which each member of the iterable is assigned on its respective iteration of the loop
+    variable: LocalVariable
     # The body of the loop, structured as a list of expressions that will each be interpreted,
     # in order, on each iteration. These body expressions can reference the loop variable,
     # allowing for Viv code that acts on each member of an iterable.
     body: list[Expression]
 
 
+class LocalVariable(TypedDict):
+    """A Viv local variable."""
+    # The name of the local variable
+    name: VariableName
+    # Whether the variable is marked as binding an entity (as opposed to a symbol)
+    isEntityVariable: bool
+
+
 # The name for a variable used in an assignment or a loop
 VariableName = str
 
@@ -480,7 +476,7 @@ class MembershipTest(NegatableExpression):
     This kind of expression takes two expressions as operands and evaluates to `True` if the evaluation
     of the first expression is a member of the (iterable) evaluation of the second expression.
     """
-    # Discriminant for a Viv membership test
+    # Discriminator for a Viv membership test
     type: Literal[ExpressionDiscriminator.MEMBERSHIP_TEST]
     # The actual expression value
     value: MembershipTestValue
@@ -500,7 +496,7 @@ class MembershipTestValue(TypedDict):
 
 class NullField(TypedDict):
     """A Viv null value."""
-    # Discriminant for a Viv null value
+    # Discriminator for a Viv null value
     type: Literal[ExpressionDiscriminator.NULL_TYPE]
     # Python's `None`, which serializes to JSON's `null`. In any Viv runtime, expressions of this
     # type evaluate to the null-like value in the language at hand.
@@ -513,7 +509,7 @@ class ObjectField(TypedDict):
     Expressions of this type maps keys (string literals) to Viv expressions. Once evaluated,
     the result will map those same keys to the respective evaluations of the Viv expressions.
     """
-    # Discriminant for a Viv object literal
+    # Discriminator for a Viv object literal
     type: Literal[ExpressionDiscriminator.OBJECT]
     # The actual expression value
     value: dict[str, "Expression"]
@@ -526,7 +522,7 @@ class RoleUnpacking(TypedDict):
     that role. This allows for iterating over multiple entities cast into the same role, e.g.,
     to carry out effects on each.
     """
-    # Discriminant for a Viv role-unpacking expression
+    # Discriminator for a Viv role-unpacking expression
     type: Literal[ExpressionDiscriminator.ROLE_UNPACKING]
     # The actual expression value
     value: RoleName
@@ -534,7 +530,7 @@ class RoleUnpacking(TypedDict):
 
 class StringField(TypedDict):
     """A Viv string literal."""
-    # Discriminant for a Viv string literal
+    # Discriminator for a Viv string literal
     type: Literal[ExpressionDiscriminator.STRING]
     # The string literal to which this expression will evaluate
     value: str
@@ -546,10 +542,10 @@ class TemplateStringField(TypedDict):
     This kind of expression is structured as an ordered list of string literals and string-producing
     references, the evaluations of which are concatenated to form the rendered string.
     """
-    # Discriminant for a Viv templated string
+    # Discriminator for a Viv templated string
     type: Literal[ExpressionDiscriminator.TEMPLATE_STRING]
     # The actual expression value
-    value: list[Union[str, EntityReference, RoleUnpacking, LocalVariableReference]]
+    value: list[Union[str, EntityReference, SymbolReference, RoleUnpacking]]
 
 
 class TropeFitExpression(NegatableExpression):
@@ -557,7 +553,7 @@ class TropeFitExpression(NegatableExpression):
 
     This kind of expression evaluates to `True` if the trope holds with the given arguments.
     """
-    # Discriminant for a Viv trope-fit expression
+    # Discriminator for a Viv trope-fit expression
     type: Literal[ExpressionDiscriminator.TROPE_FIT_EXPRESSION]
     # The actual expression value
     value: TropeFitExpressionValue