Skip to main content

dive_model/
error.rs

1//! Errors and messages of the binding stage, with TLC's codes and texts.
2//!
3//! The texts are TLC's `tlc2.output.MP.getMessage` templates at tlaplus
4//! `94d0c50`, with `%n%` replaced by the parameters as TLC passes them.
5
6use std::fmt;
7
8/// TLC's message codes (`tlc2.output.EC`) the binding stage reports.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
10#[allow(
11    missing_docs,
12    reason = "each variant is TLC's EC constant of that name"
13)]
14pub enum Ec {
15    General,
16    TlcIntegerTooBig,
17    TlcCantHandleRealNumbers,
18    TlcConfigValueNotAssignedToConstantParam,
19    TlcConfigRhsIdAppearedAfterLhsId,
20    TlcConfigWrongSubstitution,
21    TlcConfigWrongSubstitutionNumberOfArgs,
22    TlcConfigSubstitutionNonConstant,
23    TlcConfigIdDoesNotAppearInSpec,
24    TlcConfigNotBothSpecAndInit,
25    TlcConfigIdRequiresNoArg,
26    TlcConfigSpecifiedNotDefined,
27    TlcConfigIdHasValue,
28    TlcConfigMissingInit,
29    TlcConfigMissingNext,
30    TlcConfigIdMustNotBeConstant,
31    TlcConfigOpNoArgs,
32    TlcConfigOpNotInSpec,
33    TlcConfigOpIsEqual,
34    TlcConfigSpecIsTrivial,
35    TlcCantHandleSubscript,
36    TlcCantHandleConjunct,
37    TlcCantHandleTooManyNextStateRels,
38    TlcConfigPropertyNotCorrectlyDefined,
39    TlcConfigPropertyActionLevel,
40    TlcConfigPropertyActionLevelSquareASubV,
41    TlcConfigPropertyActionLevelAngleASubV,
42    TlcConfigOpArityInconsistent,
43    TlcNoModules,
44    TlcInvariantViolatedLevel,
45    TlcInvariantConstantLevel,
46    TlcSpecificationFeaturesTemporalQuantifier,
47    TlcLiveCannotHandleFormula,
48    TlcLiveFormulaTautology,
49    TlcLiveFormulaStateLevel,
50    TlcCouldNotDetermineSubscript,
51    TlcSubscriptContainNoStateVar,
52    TlcSymmetrySetTooSmall,
53}
54
55impl Ec {
56    /// TLC's number.
57    #[must_use]
58    pub fn code(self) -> u32 {
59        match self {
60            Self::General => 1000,
61            Self::TlcIntegerTooBig => 2265,
62            Self::TlcCantHandleRealNumbers => 2244,
63            Self::TlcConfigValueNotAssignedToConstantParam => 2222,
64            Self::TlcConfigRhsIdAppearedAfterLhsId => 2223,
65            Self::TlcConfigWrongSubstitution => 2224,
66            Self::TlcConfigWrongSubstitutionNumberOfArgs => 2225,
67            Self::TlcConfigSubstitutionNonConstant => 2281,
68            Self::TlcConfigIdDoesNotAppearInSpec => 2226,
69            Self::TlcConfigNotBothSpecAndInit => 2227,
70            Self::TlcConfigIdRequiresNoArg => 2228,
71            Self::TlcConfigSpecifiedNotDefined => 2229,
72            Self::TlcConfigIdHasValue => 2230,
73            Self::TlcConfigMissingInit => 2231,
74            Self::TlcConfigMissingNext => 2232,
75            Self::TlcConfigIdMustNotBeConstant => 2233,
76            Self::TlcConfigOpNoArgs => 2234,
77            Self::TlcConfigOpNotInSpec => 2235,
78            Self::TlcConfigOpIsEqual => 2236,
79            Self::TlcConfigSpecIsTrivial => 2237,
80            Self::TlcCantHandleSubscript => 2238,
81            Self::TlcCantHandleConjunct => 2239,
82            Self::TlcCantHandleTooManyNextStateRels => 2240,
83            Self::TlcConfigPropertyNotCorrectlyDefined => 2241,
84            Self::TlcConfigPropertyActionLevel => 2272,
85            Self::TlcConfigPropertyActionLevelSquareASubV => 2273,
86            Self::TlcConfigPropertyActionLevelAngleASubV => 2274,
87            Self::TlcConfigOpArityInconsistent => 2242,
88            Self::TlcNoModules => 2245,
89            Self::TlcInvariantViolatedLevel => 2146,
90            Self::TlcInvariantConstantLevel => 2149,
91            Self::TlcSpecificationFeaturesTemporalQuantifier => 2301,
92            Self::TlcLiveCannotHandleFormula => 2213,
93            Self::TlcLiveFormulaTautology => 2253,
94            Self::TlcLiveFormulaStateLevel => 2255,
95            Self::TlcCouldNotDetermineSubscript => 2139,
96            Self::TlcSubscriptContainNoStateVar => 2140,
97            Self::TlcSymmetrySetTooSmall => 2300,
98        }
99    }
100
101    /// TLC's constant name.
102    #[must_use]
103    pub fn name(self) -> &'static str {
104        match self {
105            Self::General => "GENERAL",
106            Self::TlcIntegerTooBig => "TLC_INTEGER_TOO_BIG",
107            Self::TlcCantHandleRealNumbers => "TLC_CANT_HANDLE_REAL_NUMBERS",
108            Self::TlcConfigValueNotAssignedToConstantParam => {
109                "TLC_CONFIG_VALUE_NOT_ASSIGNED_TO_CONSTANT_PARAM"
110            }
111            Self::TlcConfigRhsIdAppearedAfterLhsId => "TLC_CONFIG_RHS_ID_APPEARED_AFTER_LHS_ID",
112            Self::TlcConfigWrongSubstitution => "TLC_CONFIG_WRONG_SUBSTITUTION",
113            Self::TlcConfigWrongSubstitutionNumberOfArgs => {
114                "TLC_CONFIG_WRONG_SUBSTITUTION_NUMBER_OF_ARGS"
115            }
116            Self::TlcConfigSubstitutionNonConstant => "TLC_CONFIG_SUBSTITUTION_NON_CONSTANT",
117            Self::TlcConfigIdDoesNotAppearInSpec => "TLC_CONFIG_ID_DOES_NOT_APPEAR_IN_SPEC",
118            Self::TlcConfigNotBothSpecAndInit => "TLC_CONFIG_NOT_BOTH_SPEC_AND_INIT",
119            Self::TlcConfigIdRequiresNoArg => "TLC_CONFIG_ID_REQUIRES_NO_ARG",
120            Self::TlcConfigSpecifiedNotDefined => "TLC_CONFIG_SPECIFIED_NOT_DEFINED",
121            Self::TlcConfigIdHasValue => "TLC_CONFIG_ID_HAS_VALUE",
122            Self::TlcConfigMissingInit => "TLC_CONFIG_MISSING_INIT",
123            Self::TlcConfigMissingNext => "TLC_CONFIG_MISSING_NEXT",
124            Self::TlcConfigIdMustNotBeConstant => "TLC_CONFIG_ID_MUST_NOT_BE_CONSTANT",
125            Self::TlcConfigOpNoArgs => "TLC_CONFIG_OP_NO_ARGS",
126            Self::TlcConfigOpNotInSpec => "TLC_CONFIG_OP_NOT_IN_SPEC",
127            Self::TlcConfigOpIsEqual => "TLC_CONFIG_OP_IS_EQUAL",
128            Self::TlcConfigSpecIsTrivial => "TLC_CONFIG_SPEC_IS_TRIVIAL",
129            Self::TlcCantHandleSubscript => "TLC_CANT_HANDLE_SUBSCRIPT",
130            Self::TlcCantHandleConjunct => "TLC_CANT_HANDLE_CONJUNCT",
131            Self::TlcCantHandleTooManyNextStateRels => "TLC_CANT_HANDLE_TOO_MANY_NEXT_STATE_RELS",
132            Self::TlcConfigPropertyNotCorrectlyDefined => {
133                "TLC_CONFIG_PROPERTY_NOT_CORRECTLY_DEFINED"
134            }
135            Self::TlcConfigPropertyActionLevel => "TLC_CONFIG_PROPERTY_ACTION_LEVEL",
136            Self::TlcConfigPropertyActionLevelSquareASubV => {
137                "TLC_CONFIG_PROPERTY_ACTION_LEVEL_SQUARE_A_SUB_V"
138            }
139            Self::TlcConfigPropertyActionLevelAngleASubV => {
140                "TLC_CONFIG_PROPERTY_ACTION_LEVEL_ANGLE_A_SUB_V"
141            }
142            Self::TlcConfigOpArityInconsistent => "TLC_CONFIG_OP_ARITY_INCONSISTENT",
143            Self::TlcNoModules => "TLC_NO_MODULES",
144            Self::TlcInvariantViolatedLevel => "TLC_INVARIANT_VIOLATED_LEVEL",
145            Self::TlcInvariantConstantLevel => "TLC_INVARIANT_CONSTANT_LEVEL",
146            Self::TlcSpecificationFeaturesTemporalQuantifier => {
147                "TLC_SPECIFICATION_FEATURES_TEMPORAL_QUANTIFIER"
148            }
149            Self::TlcLiveCannotHandleFormula => "TLC_LIVE_CANNOT_HANDLE_FORMULA",
150            Self::TlcLiveFormulaTautology => "TLC_LIVE_FORMULA_TAUTOLOGY",
151            Self::TlcLiveFormulaStateLevel => "TLC_LIVE_FORMULA_STATE_LEVEL",
152            Self::TlcCouldNotDetermineSubscript => "TLC_COULD_NOT_DETERMINE_SUBSCRIPT",
153            Self::TlcSubscriptContainNoStateVar => "TLC_SUBSCRIPT_CONTAIN_NO_STATE_VAR",
154            Self::TlcSymmetrySetTooSmall => "TLC_SYMMETRY_SET_TOO_SMALL",
155        }
156    }
157
158    /// TLC's message template (`MP.getMessage`).
159    #[must_use]
160    #[allow(clippy::too_many_lines, reason = "one arm per message, TLC's texts")]
161    pub fn template(self, nparams: usize) -> &'static str {
162        match self {
163            Self::General => "%1%",
164            Self::TlcSymmetrySetTooSmall => {
165                "The set%1% %2% %3% been defined to be a symmetry set but contain%4% less than two elements."
166            }
167            Self::TlcIntegerTooBig => "TLC can't handle a number this big.\n%1%",
168            Self::TlcCantHandleRealNumbers => "TLC can't handle real numbers.\n%1%",
169            Self::TlcConfigValueNotAssignedToConstantParam => {
170                "The constant parameter %1% is not assigned a value by the configuration file."
171            }
172            Self::TlcConfigRhsIdAppearedAfterLhsId => {
173                "In the configuration file, the identifier %1% appears\non the right-hand side of a <- after already appearing on the\nleft-hand side of one."
174            }
175            Self::TlcConfigWrongSubstitution => {
176                "The configuration file substitutes for %1% with the undefined identifier %2%."
177            }
178            Self::TlcConfigWrongSubstitutionNumberOfArgs => {
179                "The configuration file substitutes for %1% with %2% of different number of arguments."
180            }
181            Self::TlcConfigSubstitutionNonConstant => {
182                "The configuration file substitutes constant %1% with non-constant %2%%3%"
183            }
184            Self::TlcConfigIdDoesNotAppearInSpec => {
185                "In the configuration file, the identifier %1% does not appear in the specification."
186            }
187            Self::TlcConfigNotBothSpecAndInit => {
188                "The configuration file cannot specify both INIT/NEXT and SPECIFICATION fields."
189            }
190            Self::TlcConfigIdRequiresNoArg => {
191                if nparams == 2 {
192                    "TLC requires %1% not to take any argument, but one was given: %2%"
193                } else {
194                    "TLC requires %1% not to take any argument."
195                }
196            }
197            Self::TlcConfigSpecifiedNotDefined => {
198                "The %1% %2% specified in the configuration file\nis not defined in the specification."
199            }
200            Self::TlcConfigIdHasValue => "The %1% of %2% is equal to %3%",
201            Self::TlcConfigMissingInit => {
202                "The configuration file did not specify the initial state predicate."
203            }
204            Self::TlcConfigMissingNext => {
205                "The configuration file did not specify the next state predicate."
206            }
207            Self::TlcConfigIdMustNotBeConstant => "The %1% %2% cannot be a constant.",
208            Self::TlcConfigOpNoArgs => "The operator %1% cannot take any argument.",
209            Self::TlcConfigOpNotInSpec => "The operator %1% is not defined in the spec.",
210            Self::TlcConfigOpIsEqual => {
211                "The operator %1%, which equals %2%,\ncannot be used as a %3%"
212            }
213            Self::TlcConfigSpecIsTrivial => "The spec is trivially false because %1% is false.",
214            Self::TlcCantHandleSubscript => "TLC cannot handle subscript %1%",
215            Self::TlcCantHandleConjunct => "TLC cannot handle this conjunct of the spec:\n%1%",
216            Self::TlcCantHandleTooManyNextStateRels => {
217                "The specification contains more than one conjunct of the form [][Next]_v,\nbut TLC can handle only specifications with one next-state relation."
218            }
219            Self::TlcConfigPropertyNotCorrectlyDefined => {
220                "The property %1% is not correctly defined."
221            }
222            Self::TlcConfigPropertyActionLevel => {
223                "The formula %1% at %2% is an action-level formula (i.e., it contains no temporal operators). Only temporal-level (or state-level) formulas are allowed under PROPERTY or PROPERTIES. To check that action %1% holds in *every* step of the behavior, define a temporal property: Let A be the formula at %2%; rewrite A as [][A]_v, where v is a state function (typically the tuple of variables) (compare page 90 of Specifying Systems at https://lamport.azurewebsites.net/tla/book.html)."
224            }
225            Self::TlcConfigPropertyActionLevelSquareASubV => {
226                "The formula %1% at %2% is an action-level formula (i.e., it contains no temporal operators). Only temporal-level (or state-level) formulas are allowed under PROPERTY or PROPERTIES. To check that action %1% holds in *every* step of the behavior, define a temporal property by applying the \"always\" temporal operator ([]) to the formula at %2% (compare page 90 of Specifying Systems at https://lamport.azurewebsites.net/tla/book.html)."
227            }
228            Self::TlcConfigPropertyActionLevelAngleASubV => {
229                "The formula %1% at %2% is an action-level formula (i.e., it contains no temporal operators). Only temporal-level (or state-level) formulas are allowed under PROPERTY or PROPERTIES. To check that infinitely many %1% steps occur, define a temporal property by applying the \"always eventually\" temporal operator combination ([]<>) to the formula at %2% (compare page 91 of Specifying Systems at https://lamport.azurewebsites.net/tla/book.html)."
230            }
231            Self::TlcConfigOpArityInconsistent => {
232                "The arity of the operator %1% is inconsistent in the configuration file."
233            }
234            Self::TlcNoModules => {
235                "In the configuration file, the module name %1% is not a module in the specification."
236            }
237            Self::TlcInvariantViolatedLevel => {
238                if nparams > 1 {
239                    "The invariant %1% is not a state predicate (one with no primes or temporal operators).\nNote that a bug can cause TLC to incorrectly report this error.\nIf you believe your TLA+ or PlusCal specification to be correct,\nplease check if this bug described in LevelNode.java starting at line 590ff affects you."
240                } else {
241                    "The invariant %1% is not a state predicate (one with no primes or temporal operators)."
242                }
243            }
244            Self::TlcInvariantConstantLevel => {
245                "The invariant %1% is a constant-level formula (i.e., it contains no variables, primes, or temporal operators) and evaluates to %2%. To assert constant-level formulas in your spec, use ASSUME ConstInv. If you optionally want to give the assumption a name, write ASSUME YourAssumption == ConstInv instead. See https://explain.tlapl.us/assumptions-and-invariants for additional details."
246            }
247            Self::TlcSpecificationFeaturesTemporalQuantifier => {
248                "TLC does not support temporal existential, nor universal, quantification over state variables."
249            }
250            Self::TlcLiveCannotHandleFormula => {
251                if nparams > 1 {
252                    "TLC cannot handle the temporal formula %1%:\n%2%"
253                } else {
254                    "TLC cannot handle the temporal formula %1%"
255                }
256            }
257            Self::TlcLiveFormulaTautology => {
258                "Temporal formula is a tautology (its negation is unsatisfiable)."
259            }
260            Self::TlcLiveFormulaStateLevel => {
261                "The formula %1% is a state-level formula, but it was used as a PROPERTY (or PROPERTIES), where a temporal formula is typically expected. State-level formulas used as PROPERTY or PROPERTIES are only checked in the initial state. To verify that the formula %1% holds in all states of every behavior, use INVARIANT %1% instead. Alternatively, applying the \"always\" temporal operator ([]) to the state-level formula %1% changes it into a temporal formula, asserting that %1% holds in all states of every behavior. See https://explain.tlapl.us/invariants-and-properties for additional details."
262            }
263            Self::TlcCouldNotDetermineSubscript => {
264                "TLC could not determine if the subscript of the next-state relation contains\nall state variables. Proceed with fingers crossed."
265            }
266            Self::TlcSubscriptContainNoStateVar => {
267                "The subscript of the next-state relation specified by the specification\ndoes not seem to contain the state variable %1%"
268            }
269        }
270    }
271
272    /// The message with `params` substituted, as `MP.getMessage` builds it.
273    #[must_use]
274    pub fn render(self, params: &[String]) -> String {
275        let mut text = self.template(params.len()).to_owned();
276        for (i, p) in params.iter().enumerate() {
277            text = text.replace(&format!("%{}%", i + 1), p);
278        }
279        text
280    }
281}
282
283/// What kind of failure a [`BindError`] is.
284#[derive(Debug, Clone, PartialEq, Eq)]
285pub enum ErrorKind {
286    /// TLC reports this error too, with this code (`EC`).
287    Tlc(Ec),
288    /// An evaluation error TLC reports while it processes the model (for
289    /// example a value in the configuration TLC cannot normalize), with
290    /// TLC's code.
291    Eval {
292        /// TLC's code.
293        code: u32,
294    },
295    /// Something dive does not implement exactly. Never a verdict.
296    Unsupported {
297        /// The feature, by name.
298        feature: String,
299    },
300    /// An internal inconsistency (a bug in dive), never a verdict.
301    Bug,
302}
303
304/// An error binding the model.
305#[derive(Debug, Clone, PartialEq, Eq)]
306pub struct BindError {
307    /// What kind of error.
308    pub kind: ErrorKind,
309    /// TLC's message text (for unsupported features and bugs, dive's).
310    pub message: String,
311}
312
313impl BindError {
314    /// A TLC error with its parameters.
315    #[must_use]
316    pub fn tlc(ec: Ec, params: &[&str]) -> Self {
317        let params: Vec<String> = params.iter().map(|s| (*s).to_owned()).collect();
318        Self {
319            kind: ErrorKind::Tlc(ec),
320            message: ec.render(&params),
321        }
322    }
323
324    /// An unsupported feature.
325    #[must_use]
326    pub fn unsupported(feature: impl Into<String>) -> Self {
327        let feature = feature.into();
328        Self {
329            message: format!("unsupported: {feature}"),
330            kind: ErrorKind::Unsupported { feature },
331        }
332    }
333
334    /// An internal error.
335    #[must_use]
336    pub fn bug(message: impl Into<String>) -> Self {
337        Self {
338            kind: ErrorKind::Bug,
339            message: message.into(),
340        }
341    }
342
343    /// TLC's code, if TLC reports this error.
344    #[must_use]
345    pub fn code(&self) -> Option<u32> {
346        match &self.kind {
347            ErrorKind::Tlc(ec) => Some(ec.code()),
348            ErrorKind::Eval { code } => Some(*code),
349            ErrorKind::Unsupported { .. } | ErrorKind::Bug => None,
350        }
351    }
352
353    /// The error as TLC prints it with `-tool`.
354    #[must_use]
355    pub fn tool_text(&self) -> String {
356        match self.code() {
357            Some(c) => format!(
358                "@!@!@STARTMSG {c}:1 @!@!@\n{}\n@!@!@ENDMSG {c} @!@!@",
359                self.message
360            ),
361            None => self.message.clone(),
362        }
363    }
364}
365
366impl fmt::Display for BindError {
367    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
368        match &self.kind {
369            ErrorKind::Tlc(ec) => write!(f, "{} ({}): {}", ec.name(), ec.code(), self.message),
370            ErrorKind::Eval { code } => write!(f, "evaluation error ({code}): {}", self.message),
371            ErrorKind::Unsupported { .. } | ErrorKind::Bug => f.write_str(&self.message),
372        }
373    }
374}
375
376impl std::error::Error for BindError {}
377
378/// Something TLC prints while it processes the model, in order.
379#[derive(Debug, Clone, PartialEq, Eq)]
380pub enum Message {
381    /// Output of `Print` or `PrintT` (one `println`).
382    Print(String),
383    /// A warning, with TLC's code.
384    Warning {
385        /// TLC's code.
386        code: Ec,
387        /// TLC's text.
388        message: String,
389    },
390}
391
392impl Message {
393    /// A warning with its parameters.
394    #[must_use]
395    pub fn warning(code: Ec, params: &[&str]) -> Self {
396        let params: Vec<String> = params.iter().map(|s| (*s).to_owned()).collect();
397        Self::Warning {
398            message: code.render(&params),
399            code,
400        }
401    }
402}
403
404/// A failed binding: the error, and what TLC printed before it.
405#[derive(Debug, Clone, PartialEq, Eq)]
406pub struct Failure {
407    /// The error.
408    pub error: BindError,
409    /// What was printed before it, in order.
410    pub output: Vec<Message>,
411}
412
413impl fmt::Display for Failure {
414    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
415        self.error.fmt(f)
416    }
417}
418
419impl std::error::Error for Failure {}