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}