Skip to main content

dive_config/
model.rs

1//! The typed model configuration.
2
3use crate::value::{ConfigValue, Spanned};
4use dive_syntax::TextRange;
5use std::collections::BTreeMap;
6
7/// A name as written in the cfg: the token's exact text and its span.
8///
9/// TLC looks names up by their text, so a name is not necessarily an
10/// identifier: `INVARIANT A, B` names `A`, `,` and `B`. For a constant
11/// written `A!B!C`, the text is `A!B!C` and the span covers all of it.
12#[derive(Debug, Clone, PartialEq, Eq)]
13pub struct Name {
14    /// The text TLC uses.
15    pub text: String,
16    /// Its bytes in the cfg file.
17    pub span: TextRange,
18}
19
20/// One entry of a `CONSTANT`/`CONSTANTS` section, in source order.
21#[derive(Debug, Clone, PartialEq, Eq)]
22pub enum ConstantEntry {
23    /// `C = v`, `F(a1, ..., an) = v`, or the module-scoped `C = [M] v`.
24    Assignment {
25        /// The constant (or constant operator) being assigned.
26        name: Name,
27        /// Arguments of a constant-operator entry such as `F(1, 2) = 3`.
28        args: Vec<Spanned<ConfigValue>>,
29        /// `M` in `C = [M] v`: the assignment applies in module `M` only.
30        module: Option<Name>,
31        /// The value.
32        value: Spanned<ConfigValue>,
33    },
34    /// `C <- D` (replace `C` by definition `D`), or `C <- [M] D`, which
35    /// replaces `C` only in module `M`.
36    Substitution {
37        /// The constant or definition being replaced.
38        name: Name,
39        /// `M` in `C <- [M] D`.
40        module: Option<Name>,
41        /// The definition that replaces it.
42        target: Name,
43    },
44}
45
46/// A parsed TLC model configuration.
47///
48/// Fields mirror TLC's `ModelConfig` tables. Section keywords that TLC
49/// treats as synonyms share one field (`INVARIANT`/`INVARIANTS`), and
50/// repeated list sections append. Single-valued keywords may appear once.
51///
52/// Whether the names exist in the specification, have the right arity and
53/// level, and whether `SPECIFICATION` conflicts with `INIT`/`NEXT`, is
54/// checked later by TLC's `SpecProcessor`, not by the cfg reader. Those
55/// checks belong to semantic analysis and the checker.
56#[derive(Debug, Clone, Default, PartialEq, Eq)]
57#[non_exhaustive]
58pub struct ModelConfig {
59    /// `INIT`.
60    pub init: Option<Name>,
61    /// `NEXT`.
62    pub next: Option<Name>,
63    /// `SPECIFICATION`.
64    pub specification: Option<Name>,
65    /// `VIEW`.
66    pub view: Option<Name>,
67    /// `SYMMETRY`.
68    pub symmetry: Option<Name>,
69    /// `ALIAS`.
70    pub alias: Option<Name>,
71    /// `_PERIODIC`: TLC's undocumented periodic-evaluation hook.
72    pub periodic: Option<Name>,
73    /// `_RL_REWARD`: TLC's undocumented reinforcement-learning reward hook.
74    pub rl_reward: Option<Name>,
75    /// `CHECK_DEADLOCK TRUE|FALSE`. Absent means TLC's default (check).
76    pub check_deadlock: Option<Spanned<bool>>,
77    /// `INVARIANT` and `INVARIANTS`.
78    pub invariants: Vec<Name>,
79    /// `PROPERTY` and `PROPERTIES`.
80    pub properties: Vec<Name>,
81    /// `CONSTRAINT` and `CONSTRAINTS`.
82    pub constraints: Vec<Name>,
83    /// `ACTION_CONSTRAINT` and `ACTION_CONSTRAINTS`.
84    pub action_constraints: Vec<Name>,
85    /// `POSTCONDITION` and `POSTCONDITIONS`.
86    pub postconditions: Vec<Name>,
87    /// `_POSSIBLE`: TLC's provisional reachability assertions.
88    pub possible: Vec<Name>,
89    /// Every `CONSTANT`/`CONSTANTS` entry, in source order.
90    pub constants: Vec<ConstantEntry>,
91    /// Model value names in the order TLC creates them (first occurrence
92    /// while parsing values, including operator arguments and set
93    /// elements). TLC numbers model values in this order.
94    pub model_values: Vec<String>,
95}
96
97/// An assignment entry, as returned by [`ModelConfig::assignments`].
98#[derive(Debug, Clone, Copy, PartialEq, Eq)]
99pub struct Assignment<'a> {
100    /// The constant.
101    pub name: &'a Name,
102    /// Operator arguments, empty for a plain constant.
103    pub args: &'a [Spanned<ConfigValue>],
104    /// The value.
105    pub value: &'a Spanned<ConfigValue>,
106}
107
108impl ModelConfig {
109    /// Whether TLC checks for deadlock under this configuration, before
110    /// command-line flags: `CHECK_DEADLOCK FALSE` turns it off, and TLC's
111    /// `-deadlock` flag also turns it off.
112    #[must_use]
113    pub fn checks_deadlock(&self) -> bool {
114        self.check_deadlock.as_ref().is_none_or(|s| s.value)
115    }
116
117    /// Assignments to the root module's constants, in source order,
118    /// duplicates included (TLC's `getConstants()`).
119    pub fn assignments(&self) -> impl Iterator<Item = Assignment<'_>> {
120        self.constants.iter().filter_map(|e| match e {
121            ConstantEntry::Assignment {
122                name,
123                args,
124                module: None,
125                value,
126            } => Some(Assignment { name, args, value }),
127            _ => None,
128        })
129    }
130
131    /// Module-scoped assignments `C = [M] v`, grouped by module, each group
132    /// in source order (TLC's `getModConstants()`).
133    #[must_use]
134    pub fn module_assignments(&self) -> BTreeMap<&str, Vec<Assignment<'_>>> {
135        let mut out: BTreeMap<&str, Vec<Assignment<'_>>> = BTreeMap::new();
136        for e in &self.constants {
137            if let ConstantEntry::Assignment {
138                name,
139                args,
140                module: Some(m),
141                value,
142            } = e
143            {
144                out.entry(m.text.as_str())
145                    .or_default()
146                    .push(Assignment { name, args, value });
147            }
148        }
149        out
150    }
151
152    /// Root-module substitutions `C <- D`, keyed by `C`. A later entry for
153    /// the same name replaces an earlier one, as in TLC's `getOverrides()`.
154    #[must_use]
155    pub fn substitutions(&self) -> BTreeMap<&str, &Name> {
156        let mut out = BTreeMap::new();
157        for e in &self.constants {
158            if let ConstantEntry::Substitution {
159                name,
160                module: None,
161                target,
162            } = e
163            {
164                out.insert(name.text.as_str(), target);
165            }
166        }
167        out
168    }
169
170    /// Module-scoped substitutions `C <- [M] D`, by module and then by `C`,
171    /// later entries replacing earlier ones (TLC's `getModOverrides()`).
172    #[must_use]
173    pub fn module_substitutions(&self) -> BTreeMap<&str, BTreeMap<&str, &Name>> {
174        let mut out: BTreeMap<&str, BTreeMap<&str, &Name>> = BTreeMap::new();
175        for e in &self.constants {
176            if let ConstantEntry::Substitution {
177                name,
178                module: Some(m),
179                target,
180            } = e
181            {
182                out.entry(m.text.as_str())
183                    .or_default()
184                    .insert(name.text.as_str(), target);
185            }
186        }
187        out
188    }
189}