tla-ts 0.0.1 → 0.0.3-dev.6979965

package/src/builtins.ts

@@ -1,22 +1,60 @@
-import { TlaEvaluationError } from "./errors";
+import { TlaEvaluationError, TlaModuleError } from "./errors";
 import type { Builtin, BuiltinArgument, Context, OperatorValue } from "./evaluate";
 import {
-  checkInteger,
   formatValue,
   getSequenceElements,
   isEnumerable,
+  isFunctionValue,
   isSetValue,
+  toFiniteFunction,
+  MAXIMUM_INTEGER,
+  MINIMUM_INTEGER,
   toFiniteSet,
   type Value,
 } from "./values";
 
-export const isOperatorValue = (argument: BuiltinArgument): argument is OperatorValue =>
+// TLC evaluates these operators in its core, or its Java code for them takes integers, so a wrong
+// argument is an evaluation failure. Every other standard-module operator checks its arguments in
+// Java and raises an EvalException.
+const CORE_OPERATOR_NAMES = new Set([
+  "=",
+  "#",
+  "~",
+  "<=>",
+  "/\\",
+  "\\/",
+  "=>",
+  "\\in",
+  "\\notin",
+  "\\subseteq",
+  "\\cup",
+  "\\cap",
+  "\\",
+  "SUBSET",
+  "UNION",
+  "DOMAIN",
+  "+",
+  "-",
+  "*",
+  "^",
+  "\\div",
+  "%",
+  "..",
+  "Seq",
+  "IsFiniteSet",
+  "RandomElement",
+]);
+
+const createArgumentError = (name: string, message: string) =>
+  CORE_OPERATOR_NAMES.has(name) ? new TlaEvaluationError(message) : new TlaModuleError(message);
+
+const isOperatorValue = (argument: BuiltinArgument): argument is OperatorValue =>
   typeof argument === "object" && argument.kind === "Operator";
 
 export const getValue = (args: BuiltinArgument[], index: number, name: string): Value => {
   const argument = args[index];
   if (argument === undefined || isOperatorValue(argument)) {
-    throw new TlaEvaluationError(`${name} expects a value as argument ${index + 1}`);
+    throw createArgumentError(name, `${name} expects a value as argument ${index + 1}`);
   }
   return argument;
 };
@@ -24,7 +62,10 @@ export const getValue = (args: BuiltinArgument[], index: number, name: string):
 export const getNumber = (args: BuiltinArgument[], index: number, name: string) => {
   const value = getValue(args, index, name);
   if (typeof value !== "number") {
-    throw new TlaEvaluationError(`${name} expects an integer but received ${formatValue(value)}`);
+    throw createArgumentError(
+      name,
+      `${name} expects an integer but received ${formatValue(value)}`,
+    );
   }
   return value;
 };
@@ -32,7 +73,7 @@ export const getNumber = (args: BuiltinArgument[], index: number, name: string)
 export const getBoolean = (args: BuiltinArgument[], index: number, name: string) => {
   const value = getValue(args, index, name);
   if (typeof value !== "boolean") {
-    throw new TlaEvaluationError(`${name} expects a boolean but received ${formatValue(value)}`);
+    throw createArgumentError(name, `${name} expects a boolean but received ${formatValue(value)}`);
   }
   return value;
 };
@@ -40,20 +81,24 @@ export const getBoolean = (args: BuiltinArgument[], index: number, name: string)
 export const getSet = (args: BuiltinArgument[], index: number, name: string) => {
   const value = getValue(args, index, name);
   if (!isSetValue(value))
-    throw new TlaEvaluationError(`${name} expects a set but received ${formatValue(value)}`);
+    throw createArgumentError(name, `${name} expects a set but received ${formatValue(value)}`);
   return value;
 };
 
-export const getFiniteSet = (args: BuiltinArgument[], index: number, name: string) => {
+export const getEnumerableSet = (args: BuiltinArgument[], index: number, name: string) => {
   const set = getSet(args, index, name);
   if (!isEnumerable(set)) {
-    throw new TlaEvaluationError(
+    throw createArgumentError(
+      name,
       `${name} cannot enumerate the non-enumerable set ${formatValue(set)}`,
     );
   }
-  return toFiniteSet(set);
+  return set;
 };
 
+const getFiniteSet = (args: BuiltinArgument[], index: number, name: string) =>
+  toFiniteSet(getEnumerableSet(args, index, name));
+
 export const getElements = (args: BuiltinArgument[], index: number, name: string) =>
   getFiniteSet(args, index, name).elements;
 
@@ -61,14 +106,28 @@ export const getSequence = (args: BuiltinArgument[], index: number, name: string
   const value = getValue(args, index, name);
   const elements = getSequenceElements(value);
   if (!elements)
-    throw new TlaEvaluationError(`${name} expects a sequence but received ${formatValue(value)}`);
+    throw createArgumentError(
+      name,
+      `${name} expects a sequence but received ${formatValue(value)}`,
+    );
   return elements;
 };
 
+export const getFunction = (args: BuiltinArgument[], index: number, name: string) => {
+  const value = getValue(args, index, name);
+  if (!isFunctionValue(value)) {
+    throw createArgumentError(
+      name,
+      `${name} expects a function but received ${formatValue(value)}`,
+    );
+  }
+  return toFiniteFunction(value);
+};
+
 export const getOperator = (args: BuiltinArgument[], index: number, name: string) => {
   const argument = args[index];
   if (argument === undefined || !isOperatorValue(argument)) {
-    throw new TlaEvaluationError(`${name} expects an operator as argument ${index + 1}`);
+    throw createArgumentError(name, `${name} expects an operator as argument ${index + 1}`);
   }
   return argument;
 };
@@ -122,13 +181,6 @@ export const defineStateOperator = (
   isStateLevel: true,
 });
 
-export const toNumber = (value: Value, name: string) => {
-  if (typeof value !== "number") {
-    throw new TlaEvaluationError(`${name} expects an integer but received ${formatValue(value)}`);
-  }
-  return value;
-};
-
 export const defineBinary = (
   name: string,
   compute: (left: Value, right: Value) => Value,
@@ -141,13 +193,141 @@ export const defineBinary = (
   evaluateBinary: compute,
 });
 
-export const defineArithmetic = (name: string, compute: (left: number, right: number) => number) =>
-  defineBinary(name, (left, right) =>
-    checkInteger(compute(toNumber(left, name), toNumber(right, name))),
+export const isOutOfRange = (value: number) => value > MAXIMUM_INTEGER || value < MINIMUM_INTEGER;
+
+export const createOverflowError = (computation: string) =>
+  new TlaModuleError(`Overflow when computing ${computation}`);
+
+const JAVA_CLASSES: Record<string, string> = {
+  ModelValue: "ModelValue",
+  Set: "SetEnumValue",
+  Interval: "IntervalValue",
+  InfiniteSet: "UserValue",
+  SequenceSet: "UserValue",
+  Subset: "SubsetValue",
+  FunctionSet: "SetOfFcnsValue",
+  RecordSet: "SetOfRcdsValue",
+  ProductSet: "SetOfTuplesValue",
+  FilteredSet: "SetPredValue",
+  LazyFunction: "FcnLambdaValue",
+  Union: "UnionValue",
+  MixedSet: "SetEnumValue",
+};
+
+const SET_OPERATION_CLASSES = {
+  "\\cup": "SetCupValue",
+  "\\cap": "SetCapValue",
+  "\\": "SetDiffValue",
+};
+
+const KIND_STRINGS: Record<string, string> = {
+  BoolValue: "a Boolean value",
+  IntValue: "an integer",
+  StringValue: "a string",
+  RecordValue: "a record",
+  SetEnumValue: "a set of the form {e1, ... ,eN}",
+  SetPredValue: "a set of the form {x \\in S : expr}",
+  TupleValue: "a tuple",
+  FcnLambdaValue: "a function of the form  [x \\in S |-> expr]",
+  FcnRcdValue: "a function  of the form (d1 :> e1 @@ ... @@ dN :> eN)",
+  SetOfFcnsValue: "a set of the form [S -> T]",
+  SetOfRcdsValue: "a set of the form [d1 : S1, ... , dN : SN]",
+  SetOfTuplesValue: "a cartesian product",
+  SubsetValue: "a set of the form SUBSET S",
+  SetDiffValue: "a set of the form S \\ T",
+  SetCapValue: "a set of the form S \\cap T",
+  SetCupValue: "a set of the form S \\cup T",
+  ModelValue: "a model value",
+  UserValue: "a special set constant",
+  IntervalValue: "a set of the form i..j",
+  UnionValue: "a set of the form UNION  S",
+};
+
+// TLC stores a function as a TupleValue or a RecordValue when it has that shape, so the
+// shape stands in for how TLC built the value.
+export const getJavaClassName = (value: Value) => {
+  if (typeof value === "number") return "IntValue";
+  if (typeof value === "string") return "StringValue";
+  if (typeof value === "boolean") return "BoolValue";
+  if (value.kind === "SetOperation") return SET_OPERATION_CLASSES[value.operator];
+  if (value.kind !== "Function") return JAVA_CLASSES[value.kind];
+  const domain = value.domain;
+  if (domain.every((key, index) => key === index + 1)) return "TupleValue";
+  return domain.every((key) => typeof key === "string") ? "RecordValue" : "FcnRcdValue";
+};
+
+export const getKindString = (value: Value) => KIND_STRINGS[getJavaClassName(value)];
+
+export const createJavaOverrideError = (signature: string, message: string) =>
+  new TlaEvaluationError(
+    `Attempted to apply the operator overridden by the Java method\n${signature},\nbut it produced the following error:\n${message}`,
   );
 
+// TLC reports a failure inside an operator's Java method as a failure of the method, except an
+// EvalException that the method raises itself. A method that evaluates its own arguments reports
+// every failure that way.
+export const overrideWithJava = (builtin: Builtin, signature: string): Builtin => {
+  const guard =
+    <Arguments extends unknown[]>(compute: (...args: Arguments) => Value) =>
+    (...args: Arguments) => {
+      try {
+        return compute(...args);
+      } catch (error) {
+        const isWrapped =
+          error instanceof TlaEvaluationError &&
+          (builtin.isLazy === true || !(error instanceof TlaModuleError));
+        throw isWrapped ? createJavaOverrideError(signature, error.message) : error;
+      }
+    };
+  return {
+    ...builtin,
+    evaluate: guard(builtin.evaluate),
+    evaluateUnary: builtin.evaluateUnary && guard(builtin.evaluateUnary),
+    evaluateBinary: builtin.evaluateBinary && guard(builtin.evaluateBinary),
+  };
+};
+
+export const getJavaInteger = (value: Value, signature: string) => {
+  if (typeof value !== "number") {
+    throw createJavaOverrideError(
+      signature,
+      `Cannot cast tlc2.value.impl.${getJavaClassName(value)} to tlc2.value.impl.IntValue`,
+    );
+  }
+  return value;
+};
+
+export const getIntegersSignature = (method: string, result: string, arity: number) =>
+  `public static tlc2.value.impl.${result} tlc2.module.Integers.${method}(${Array.from({ length: arity }, () => "tlc2.value.impl.IntValue").join(",")})`;
+
+export const defineArithmetic = (
+  name: string,
+  method: string,
+  compute: (left: number, right: number) => number,
+) => {
+  const signature = getIntegersSignature(method, "IntValue", 2);
+  return defineBinary(name, (left, right) => {
+    const leftNumber = getJavaInteger(left, signature);
+    const rightNumber = getJavaInteger(right, signature);
+    const result = compute(leftNumber, rightNumber);
+    if (isOutOfRange(result)) throw createOverflowError(`${leftNumber}${name}${rightNumber}`);
+    return result;
+  });
+};
+
+const getIntegerArgument = (value: Value, position: string, name: string) => {
+  if (typeof value !== "number") {
+    throw new TlaModuleError(
+      `The ${position} argument of ${name} should be an integer, but instead it is:\n${formatValue(value)}`,
+    );
+  }
+  return value;
+};
+
 export const defineComparison = (name: string, compare: (left: number, right: number) => boolean) =>
-  defineBinary(name, (left, right) => compare(toNumber(left, name), toNumber(right, name)));
+  defineBinary(name, (left, right) =>
+    compare(getIntegerArgument(left, "first", name), getIntegerArgument(right, "second", name)),
+  );
 
 export const defineLazyOperator = (
   name: string,

package/src/bundled-modules.ts

@@ -1,48 +1,79 @@
-const REALS = `---- MODULE Reals ----
+// TLC's Reals.tla, RealTime.tla, and Toolbox.tla, verbatim, so that errors inside them name the same
+// lines as TLC's errors.
+const REALS = `-------------------------------- MODULE Reals -------------------------------
+(***************************************************************************)
+(* This module provides dummy definitions of the operators that are        *)
+(* defined by the real Reals module.  It is expected that any tool that    *)
+(* handles specifications that use real numbers will provide its own       *)
+(* implementations of these operators.  TLC currently does not handle real *)
+(* numbers and produces an error if a specification requires TLC to        *)
+(* evaluate the operators defined here or to evaluate any operator defined *)
+(* in the Integers module that is applied to non-integer real numbers.     *)
+(*                                                                         *)
+(* See the book "Specifying Systems" for the real Reals module.            *)
+(***************************************************************************)
 EXTENDS Integers
 
-Real == "Reals"
+Real  == "Reals"
+a / b == CHOOSE m \\in Real : m * b = a
+Infinity == CHOOSE i : (i \\notin Real) /\\ (\\A r \\in Real : i > r)
+=============================================================================`;
 
-a / b == CHOOSE quotient \\in Real : quotient * b = a
-
-Infinity == CHOOSE value : (value \\notin Real) /\\ (\\A real \\in Real : value > real)
-====`;
+const REAL_TIME = `----------------------------- MODULE RealTime -------------------------------
+(***************************************************************************)
+(* This standard module is described in Chapter 9 of the book "Specifying  *)
+(* Systems".  The type of specification described there cannot be handled  *)
+(* by the TLC model checker.                                               *)
+(***************************************************************************)
+EXTENDS Reals 
+VARIABLE now
 
-const REAL_TIME = `---- MODULE RealTime ----
-EXTENDS Reals
+RTBound(A, v, D, E) == 
+  LET TNext(t)  ==  t' = IF <<A>>_v \\/ ~(ENABLED <<A>>_v)'
+                           THEN 0 
+                           ELSE t + (now'-now)
 
-VARIABLE now
+      Timer(t) == (t=0)  /\\  [][TNext(t)]_<<t, v, now>>
 
-RTBound(A, v, D, E) ==
-  LET TNext(timer) == timer' = IF <<A>>_v \\/ ~(ENABLED <<A>>_v)'
-                               THEN 0
-                               ELSE timer + (now' - now)
-      Timer(timer) == (timer = 0) /\\ [][TNext(timer)]_<<timer, v, now>>
-      MaxTime(timer) == [](timer \\leq E)
-      MinTime(timer) == [][A => timer \\geq D]_v
-  IN \\EE timer : Timer(timer) /\\ MaxTime(timer) /\\ MinTime(timer)
+      MaxTime(t) == [](t \\leq E) 
 
-RTnow(v) == LET NowNext == /\\ now' \\in {real \\in Real : real > now}
+      MinTime(t) == [][A => t \\geq D]_v 
+  IN \\EE t : Timer(t) /\\ MaxTime(t) /\\ MinTime(t)
+-----------------------------------------------------------------------------
+RTnow(v) == LET NowNext == /\\ now' \\in {r \\in Real : r > now} 
                            /\\ UNCHANGED v
-            IN /\\ now \\in Real
-               /\\ [][NowNext]_now
-               /\\ \\A real \\in Real : WF_now(NowNext /\\ (now' > real))
-====`;
+            IN  /\\ now \\in Real 
+                /\\ [][NowNext]_now
+                /\\ \\A r \\in Real : WF_now(NowNext /\\ (now'>r))
+=============================================================================`;
 
-const TOOLBOX = `---- MODULE Toolbox ----
-LOCAL INSTANCE Naturals
-LOCAL INSTANCE FiniteSets
-LOCAL INSTANCE TLC
+const TOOLBOX = `----------------------------- MODULE Toolbox --------------------------------
+(***************************************************************************)
+(*                                                                         *)
+(***************************************************************************)
+LOCAL INSTANCE Naturals   \\* a + b
+LOCAL INSTANCE FiniteSets \\* Cardinality
+LOCAL INSTANCE TLC        \\* TLCGet
 
-_TETrace == CHOOSE trace \\in [(Nat \\ {0}) -> STRING] : TRUE
+-----------------------------------------------------------------------------
+
+(* Trace Exploration *)
+
+_TETrace ==
+    CHOOSE f \\in [ (Nat \\ {0}) -> STRING ] : TRUE
 
 LOCAL _TETraceLength == Cardinality(DOMAIN _TETrace)
 
-_TEPosition ==
-  IF TLCGet("level") >= _TETraceLength
-  THEN _TETraceLength
-  ELSE IF TLCGet("level") = 0 THEN 1 ELSE TLCGet("level")
-====`;
+\\* When evaluated as part of a TLC ALIAS expression, \`_TEPosition\` should be
+\\* redefined as \`TLCGet("level"), or replace with \`TLCGet(level)\` right away.
+\\* The definition below accounts for several "peculiarities" of the
+\\* Toolbox's trace exploration.
+_TEPosition == 
+    IF TLCGet("level") >= _TETraceLength
+       THEN _TETraceLength
+       ELSE IF TLCGet("level") = 0 THEN 1 ELSE TLCGet("level")
+
+=============================================================================`;
 
 export const BUNDLED_MODULES = new Map([
   ["Reals", REALS],