badness_parser/bib/
ast.rs

1//! Typed, read-only wrappers over the BibTeX CST.
2//!
3//! Accessors expose syntax without assigning meaning to fields or entries.
4//!
5//! Free functions provide the same operations for untyped [`SyntaxNode`] callers.
6
7pub mod nodes;
8
9pub use nodes::{Entry, EntryType, Field, FieldName, Key, StringEntry, Value};
10
11use rowan::TextRange;
12
13use crate::bib::syntax::{SyntaxKind, SyntaxNode};
14
15/// A typed wrapper over BibTeX CST nodes of a particular [`SyntaxKind`].
16pub trait AstNode {
17    fn can_cast(kind: SyntaxKind) -> bool
18    where
19        Self: Sized;
20    fn cast(syntax: SyntaxNode) -> Option<Self>
21    where
22        Self: Sized;
23    fn syntax(&self) -> &SyntaxNode;
24}
25
26/// The first child node castable to `N`.
27pub fn child<N: AstNode>(parent: &SyntaxNode) -> Option<N> {
28    parent.children().find_map(N::cast)
29}
30
31/// All child nodes castable to `N`, in source order.
32pub fn children<N: AstNode>(parent: &SyntaxNode) -> impl Iterator<Item = N> {
33    parent.children().filter_map(N::cast)
34}
35
36// --- Free-function shims (kind-agnostic; see module docs) ---------------------
37
38/// The entry type of an `ENTRY` / `STRING_ENTRY` / … node — the word following `@`
39/// (e.g. `"article"`, `"string"`). `None` for a malformed entry with no `ENTRY_TYPE`
40/// child. Case is preserved; callers normalize.
41pub fn entry_type(entry: &SyntaxNode) -> Option<String> {
42    child::<EntryType>(entry).and_then(|t| t.text())
43}
44
45/// The cite key of a regular `ENTRY` and the byte range of its `KEY` node. `None` when
46/// the entry has no key (a recovery case) or the key is empty.
47pub fn cite_key(entry: &SyntaxNode) -> Option<(String, TextRange)> {
48    let key = child::<Key>(entry)?;
49    key.text().map(|text| (text, key.syntax().text_range()))
50}
51
52/// The macro name defined by a `STRING_ENTRY` (`@string{ name = value }`) and the
53/// byte range of its `FIELD_NAME` node. `None` for a malformed `@string` with no
54/// `name = …` field.
55pub fn string_def_name(string_entry: &SyntaxNode) -> Option<(String, TextRange)> {
56    let name = child::<Field>(string_entry)?.name_node()?;
57    name.text().map(|text| (text, name.syntax().text_range()))
58}
59
60/// The `FIELD` children of an entry, in source order.
61pub fn fields(entry: &SyntaxNode) -> impl Iterator<Item = SyntaxNode> {
62    children::<Field>(entry).map(|f| f.syntax().clone())
63}
64
65/// The name of a `FIELD` (the text of its `FIELD_NAME`), or `None` if absent.
66pub fn field_name(field: &SyntaxNode) -> Option<String> {
67    child::<FieldName>(field).and_then(|n| n.text())
68}
69
70/// The `VALUE` node of a `FIELD` (the right-hand side of `=`), or `None` if absent.
71pub fn field_value(field: &SyntaxNode) -> Option<SyntaxNode> {
72    child::<Value>(field).map(|v| v.syntax().clone())
73}
74
75/// A field `VALUE` as plain display text: the node text, trimmed, with one layer of
76/// surrounding `{…}`/`"…"` removed and interior whitespace collapsed. Shared by the
77/// LSP hover/completion cards and the semantic model's cached title/author facts.
78pub fn value_text_cleaned(value: &SyntaxNode) -> String {
79    let raw = value.text().to_string();
80    let trimmed = raw.trim();
81    let inner = trimmed
82        .strip_prefix('{')
83        .and_then(|s| s.strip_suffix('}'))
84        .or_else(|| trimmed.strip_prefix('"').and_then(|s| s.strip_suffix('"')))
85        .unwrap_or(trimmed);
86    inner.split_whitespace().collect::<Vec<_>>().join(" ")
87}
88
89/// The bare-macro *uses* inside a `VALUE`: each `LITERAL` piece whose single token is
90/// a `WORD` (an unquoted, unbraced name) is an `@string` reference. A `LITERAL`
91/// wrapping a `NUMBER` is a literal number, not a macro use, and is skipped. Yields
92/// `(name, range)` with the range of the `LITERAL` piece.
93pub fn value_macro_uses(value: &SyntaxNode) -> impl Iterator<Item = (String, TextRange)> {
94    nodes::macro_uses_of(value)
95}
96
97#[cfg(test)]
98mod tests {
99    use super::*;
100    use crate::bib::parse;
101
102    /// The first node of `kind` in a freshly parsed `src`.
103    fn node(src: &str, kind: SyntaxKind) -> SyntaxNode {
104        parse(src)
105            .syntax()
106            .descendants()
107            .find(|n| n.kind() == kind)
108            .unwrap_or_else(|| panic!("a {kind:?} node"))
109    }
110
111    #[test]
112    fn entry_type_reads_word() {
113        let entry = node("@article{k, title = {Hi}}\n", SyntaxKind::ENTRY);
114        assert_eq!(entry_type(&entry).as_deref(), Some("article"));
115    }
116
117    #[test]
118    fn cite_key_reassembles_colon_key() {
119        let entry = node("@book{westfahl:space, title = {X}}\n", SyntaxKind::ENTRY);
120        let (key, _range) = cite_key(&entry).expect("a key");
121        assert_eq!(key, "westfahl:space");
122    }
123
124    #[test]
125    fn cite_key_none_without_key() {
126        let entry = node("@misc{", SyntaxKind::ENTRY);
127        assert_eq!(cite_key(&entry), None);
128    }
129
130    #[test]
131    fn string_def_name_reads_field_name() {
132        let s = node("@string{jan = \"January\"}\n", SyntaxKind::STRING_ENTRY);
133        let (name, _range) = string_def_name(&s).expect("a name");
134        assert_eq!(name, "jan");
135    }
136
137    #[test]
138    fn fields_and_names() {
139        let entry = node("@misc{k, a = {x}, b = 3}\n", SyntaxKind::ENTRY);
140        let names: Vec<_> = fields(&entry).filter_map(|f| field_name(&f)).collect();
141        assert_eq!(names, vec!["a", "b"]);
142    }
143
144    #[test]
145    fn value_macro_uses_finds_word_not_number() {
146        // `t = pub # {x} # 2020`: only `pub` is a macro use; `2020` is a number.
147        let field = node("@misc{k, t = pub # {x} # 2020}\n", SyntaxKind::FIELD);
148        let value = field_value(&field).expect("a value");
149        let uses: Vec<_> = value_macro_uses(&value).map(|(n, _)| n).collect();
150        assert_eq!(uses, vec!["pub"]);
151    }
152
153    // --- Wrapper-native tests --------------------------------------------------
154
155    #[test]
156    fn cast_is_kind_exact() {
157        let entry = node("@article{k, title = {Hi}}\n", SyntaxKind::ENTRY);
158        assert!(Entry::cast(entry.clone()).is_some());
159        assert!(Field::cast(entry).is_none());
160    }
161
162    #[test]
163    fn entry_wrapper_reads_type_key_and_fields() {
164        let entry = Entry::cast(node("@article{k, a = {x}, b = 3}\n", SyntaxKind::ENTRY)).unwrap();
165        assert_eq!(entry.entry_type().as_deref(), Some("article"));
166        assert_eq!(entry.cite_key().map(|(k, _)| k).as_deref(), Some("k"));
167        let names: Vec<_> = entry.fields().filter_map(|f| f.name()).collect();
168        assert_eq!(names, vec!["a", "b"]);
169    }
170}
badness_parser/bib/ast.rs

badness_parser/bib/
ast.rs
