Skip to main content

dive_syntax/
lib.rs

1//! `dive-syntax`: the TLA+ lexer and parser.
2//!
3//! [`parse_module`] turns source text into a lossless concrete syntax tree
4//! (CST): the tree's text is byte-identical to the input, including
5//! whitespace, comments (and the PlusCal algorithms inside them), the text
6//! before the module header and the text after the closing `====`.
7//!
8//! The parser accepts exactly what the pinned SANY parser accepts. That
9//! includes SANY's syntactic restrictions, such as operator precedence
10//! conflicts (`a * -b` is rejected) and junction-list alignment. The one
11//! exception is pathologically deep nesting, which `dive` refuses with
12//! `DIVE-S0040` instead of risking a stack overflow. It never panics, and it always produces a
13//! tree; after an error it recovers at the next module-level unit so editors
14//! keep working.
15//!
16//! Semantic analysis (name resolution, arity, levels) is not done here;
17//! that is `dive-sema`.
18//!
19//! # Example
20//!
21//! ```
22//! use dive_syntax::{parse_module, ast::AstNode};
23//!
24//! let src = "---- MODULE Counter ----\nVARIABLE x\nInit == x = 0\nNext == x' = x + 1\n====\n";
25//! let parse = parse_module(src);
26//! assert!(parse.is_ok());
27//! assert_eq!(parse.syntax().to_string(), src); // lossless
28//!
29//! let module = parse.module().expect("a module");
30//! assert_eq!(module.name().as_deref(), Some("Counter"));
31//! let defs: Vec<String> = module
32//!     .operator_definitions()
33//!     .filter_map(|d| d.name())
34//!     .collect();
35//! assert_eq!(defs, ["Init", "Next"]);
36//! ```
37#![forbid(unsafe_code)]
38
39pub mod ast;
40pub mod diagnostics;
41mod kind;
42mod lexer;
43pub mod ops;
44mod parser;
45pub mod tokens;
46mod tree;
47
48pub use diagnostics::{Code, Diagnostic, Severity};
49pub use kind::{SyntaxElement, SyntaxKind, SyntaxNode, SyntaxToken, TlaLanguage};
50pub use rowan::{GreenNode, TextRange, TextSize};
51
52/// The result of parsing one source file.
53///
54/// Cloning is cheap: the tree is reference counted.
55#[derive(Debug, Clone, PartialEq, Eq)]
56pub struct Parse {
57    green: GreenNode,
58    diagnostics: Vec<Diagnostic>,
59}
60
61impl Parse {
62    /// The root of the concrete syntax tree (a `SOURCE_FILE` node).
63    #[must_use]
64    pub fn syntax(&self) -> SyntaxNode {
65        SyntaxNode::new_root(self.green.clone())
66    }
67
68    /// The immutable green tree, which is `Send + Sync` and cheap to clone.
69    #[must_use]
70    pub fn green(&self) -> &GreenNode {
71        &self.green
72    }
73
74    /// All diagnostics, in source order.
75    #[must_use]
76    pub fn diagnostics(&self) -> &[Diagnostic] {
77        &self.diagnostics
78    }
79
80    /// Whether SANY's parser would accept the input (no error diagnostics).
81    #[must_use]
82    pub fn is_ok(&self) -> bool {
83        !self.diagnostics.iter().any(Diagnostic::is_error)
84    }
85
86    /// The top-level module, if a module header was found.
87    #[must_use]
88    pub fn module(&self) -> Option<ast::Module> {
89        ast::SourceFile::cast(self.syntax()).and_then(|f| f.module())
90    }
91
92    /// SANY's file-name check: a file `Name.tla` must contain module `Name`
93    /// (compared exactly). `file_name` is the file's base name; everything
94    /// from its last `.` is ignored, as in SANY. Returns the error, if any.
95    ///
96    /// SANY only checks this after the module parsed, so this does too.
97    ///
98    /// ```
99    /// let p = dive_syntax::parse_module("---- MODULE A ----\n====");
100    /// assert!(p.check_file_name("A.tla").is_none());
101    /// assert_eq!(p.check_file_name("B.tla").unwrap().code.as_str(), "DIVE-S0006");
102    /// ```
103    #[must_use]
104    pub fn check_file_name(&self, file_name: &str) -> Option<Diagnostic> {
105        if !self.is_ok() {
106            return None;
107        }
108        let stem = file_name.rfind('.').map_or(file_name, |i| &file_name[..i]);
109        let module = self.module()?;
110        let name = module.name()?;
111        if name == stem {
112            return None;
113        }
114        let range = module
115            .syntax()
116            .children()
117            .find(|n| n.kind() == SyntaxKind::MODULE_HEADER)
118            .and_then(|h| {
119                h.children_with_tokens()
120                    .filter_map(rowan::NodeOrToken::into_token)
121                    .find(|t| t.kind() == SyntaxKind::IDENT)
122            })
123            .map_or_else(|| module.syntax().text_range(), |t| t.text_range());
124        Some(
125            Diagnostic::error(
126                Code::ModuleNameMismatch,
127                range,
128                format!("file name `{stem}` does not match the module name `{name}`"),
129            )
130            .with_help(format!(
131                "rename the file to `{name}.tla` or the module to `{stem}`"
132            )),
133        )
134    }
135}
136
137use ast::AstNode as _;
138
139/// Parses a TLA+ source file containing one top-level module.
140///
141/// Text before the first `---- MODULE` line and after the module's closing
142/// `====` is kept in the tree as `PRELUDE` and `TRAILER` trivia, as SANY
143/// ignores it.
144///
145/// # Example
146///
147/// ```
148/// let p = dive_syntax::parse_module("---- MODULE M ----\nx == 1 * -2\n====");
149/// assert!(!p.is_ok());
150/// assert_eq!(p.diagnostics()[0].code.as_str(), "DIVE-S0012"); // precedence conflict
151/// ```
152#[must_use]
153pub fn parse_module(source: &str) -> Parse {
154    if u32::try_from(source.len()).is_err() {
155        // rowan text sizes are 32-bit; refuse rather than truncate.
156        let mut b = rowan::GreenNodeBuilder::new();
157        b.start_node(SyntaxKind::SOURCE_FILE.into());
158        b.finish_node();
159        return Parse {
160            green: b.finish(),
161            diagnostics: vec![Diagnostic::error(
162                Code::InputTooLarge,
163                TextRange::empty(TextSize::from(0)),
164                "input larger than 4 GiB is not supported",
165            )],
166        };
167    }
168    let lexed = lexer::lex(source);
169    let out = parser::Parser::new(source, &lexed).parse();
170    let green = tree::build_green(
171        &out.root,
172        &tree::GreenInput {
173            src: source,
174            lexed: &lexed,
175            sig: &out.sig,
176            kinds: &out.kinds,
177            trailer_from: out.trailer_from,
178        },
179    );
180    let mut diagnostics = parser::lexer_diagnostics(&lexed, out.trailer_from);
181    diagnostics.extend(out.diags);
182    diagnostics.sort_by_key(|d| (d.range.start(), d.range.end()));
183    Parse { green, diagnostics }
184}