Skip to main content

vvv_core/symbol/
mod.rs

1//! Language-neutral view of declarations.
2//!
3//! A plugin describes its grammar with [`SymbolRule`]s (data); the generic
4//! extractor in `vvv-lang` turns them into [`Symbol`]s. Nothing here knows
5//! tree-sitter.
6
7mod kind;
8
9use serde::{Deserialize, Serialize};
10
11pub use kind::{SymbolKind, UnknownSymbolKind};
12
13use crate::text::Span;
14
15/// A declaration found in one file.
16#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
17pub struct Symbol {
18    pub kind: SymbolKind,
19    pub name: String,
20    /// The identifier token itself: what a rename replaces.
21    pub name_span: Span,
22    /// The declaration node.
23    pub span: Span,
24    /// The declaration with what belongs to it in the text: leading
25    /// attributes and doc comments, an enclosing `export`. What moving the
26    /// declaration cuts; what an outline shows.
27    pub extent: Span,
28    /// The visibility as written (`pub(crate)`, `export`); `None` when the
29    /// declaration has no modifier. What it means is the language's
30    /// [`Semantics`](crate::Semantics).
31    #[serde(default, skip_serializing_if = "Option::is_none")]
32    pub visibility: Option<Modifier>,
33}
34
35impl Symbol {
36    /// A symbol whose extent is its node and which has no modifier.
37    pub fn plain(kind: SymbolKind, name: impl Into<String>, name_span: Span, span: Span) -> Self {
38        Self {
39            kind,
40            name: name.into(),
41            name_span,
42            span,
43            extent: span,
44            visibility: None,
45        }
46    }
47
48    pub fn modifier(&self) -> Option<&str> {
49        self.visibility.as_ref().map(|m| m.text.as_str())
50    }
51}
52
53/// A visibility modifier as it appears in the source.
54#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
55pub struct Modifier {
56    pub span: Span,
57    pub text: String,
58}
59
60/// Where a declaration's visibility modifier is found in the tree.
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62pub enum ModifierAt {
63    /// A direct child of this kind (`visibility_modifier` in Rust).
64    Child(&'static str),
65    /// An enclosing node of this kind whose first token is the modifier
66    /// (`export_statement` in TypeScript). It becomes part of the extent.
67    Parent(&'static str),
68}
69
70/// "Nodes of kind `node` declare a `kind` whose name is the field `name_field`."
71///
72/// Rules are tried in order; the first whose `node`, `under` and `within`
73/// all match wins, so put the more specific rule (a method inside an impl)
74/// before the general one (a function).
75#[derive(Debug, Clone, Copy, PartialEq, Eq)]
76pub struct SymbolRule {
77    pub node: &'static str,
78    /// Field holding the identifier; `None` when the node is its own name
79    /// (a bare enum member, say).
80    pub name_field: Option<&'static str>,
81    pub kind: SymbolKind,
82    /// Only applies when the direct parent has this kind.
83    pub under: Option<&'static str>,
84    /// Only applies when an ancestor of this node kind exists, without a
85    /// nested declaration of the same `node` kind in between.
86    pub within: Option<&'static str>,
87    /// Kinds of preceding siblings that belong to the declaration
88    /// (attributes, doc comments) and extend its extent, as long as no blank
89    /// line separates them from it.
90    pub leading: &'static [&'static str],
91    /// Where the visibility modifier is, if the language has one.
92    pub visibility: Option<ModifierAt>,
93    /// When the name node has a child in this field, the name is that
94    /// child's, repeatedly: `Foo` inside the `generic_type` `Foo<'a>` an
95    /// `impl` is for.
96    pub name_inner: Option<&'static str>,
97}
98
99impl SymbolRule {
100    pub const fn new(node: &'static str, name_field: &'static str, kind: SymbolKind) -> Self {
101        Self {
102            node,
103            name_field: Some(name_field),
104            kind,
105            under: None,
106            within: None,
107            leading: &[],
108            visibility: None,
109            name_inner: None,
110        }
111    }
112
113    /// The node is the identifier token itself.
114    pub const fn self_named(node: &'static str, kind: SymbolKind) -> Self {
115        Self {
116            node,
117            name_field: None,
118            kind,
119            under: None,
120            within: None,
121            leading: &[],
122            visibility: None,
123            name_inner: None,
124        }
125    }
126
127    pub const fn name_inner(mut self, field: &'static str) -> Self {
128        self.name_inner = Some(field);
129        self
130    }
131
132    pub const fn leading(mut self, kinds: &'static [&'static str]) -> Self {
133        self.leading = kinds;
134        self
135    }
136
137    pub const fn visibility(mut self, at: ModifierAt) -> Self {
138        self.visibility = Some(at);
139        self
140    }
141
142    /// The direct parent must be this kind.
143    pub const fn under(mut self, parent: &'static str) -> Self {
144        self.under = Some(parent);
145        self
146    }
147
148    pub const fn within(mut self, ancestor: &'static str) -> Self {
149        self.within = Some(ancestor);
150        self
151    }
152}