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}