Skip to main content

vvv_core/lang/
mod.rs

1//! The language plugin boundary.
2//!
3//! A [`Language`] knows how to look inside one kind of source file. It never
4//! hands out parser nodes: everything it returns is plain data ([`RawMatch`],
5//! [`Symbol`], [`ImportRef`], [`Facts`]), which is what lets the core and the
6//! planners be tested with a fake language and lets a real language move out
7//! of process.
8
9mod registry;
10
11use std::borrow::Cow;
12use std::fmt;
13
14use serde::{Deserialize, Serialize};
15
16pub use registry::LanguageRegistry;
17
18use crate::facts::Facts;
19use crate::highlight::{Highlight, HighlightRule};
20use crate::import::{ImportGrammar, ImportRef};
21use crate::paths::PathSyntax;
22use crate::query::Query;
23use crate::resolve::{Layout, Surgery};
24use crate::search::{RawMatch, SearchError};
25use crate::semantics::Semantics;
26use crate::symbol::{Symbol, SymbolRule};
27
28/// Stable identifier of a language (`rust`, `typescript`, ...).
29#[derive(Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
30#[serde(transparent)]
31pub struct LanguageId(Cow<'static, str>);
32
33impl LanguageId {
34    pub const fn new(id: &'static str) -> Self {
35        Self(Cow::Borrowed(id))
36    }
37
38    pub fn as_str(&self) -> &str {
39        &self.0
40    }
41}
42
43impl From<String> for LanguageId {
44    fn from(id: String) -> Self {
45        Self(Cow::Owned(id))
46    }
47}
48
49impl From<&str> for LanguageId {
50    fn from(id: &str) -> Self {
51        Self(Cow::Owned(id.to_owned()))
52    }
53}
54
55impl fmt::Display for LanguageId {
56    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
57        f.write_str(&self.0)
58    }
59}
60
61impl fmt::Debug for LanguageId {
62    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
63        write!(f, "LanguageId({})", self.0)
64    }
65}
66
67/// Everything a grammar-backed language declares about itself, as data:
68/// what a declaration is, what an identifier token is, where import paths
69/// live. A language module contributes one of these beside its semantics.
70#[derive(Debug, Clone, Copy, PartialEq, Eq)]
71pub struct Grammar {
72    pub symbols: &'static [SymbolRule],
73    pub identifiers: &'static [&'static str],
74    pub imports: ImportGrammar,
75    pub highlights: &'static [HighlightRule],
76}
77
78impl Grammar {
79    pub const EMPTY: Self = Self {
80        symbols: &[],
81        identifiers: &[],
82        imports: ImportGrammar::EMPTY,
83        highlights: &[],
84    };
85}
86
87pub trait Language: Send + Sync {
88    fn id(&self) -> LanguageId;
89
90    /// File extensions (without the dot) this language claims.
91    fn extensions(&self) -> &'static [&'static str];
92
93    /// What the language's syntax means.
94    fn semantics(&self) -> &'static Semantics;
95
96    /// How the language spells paths: what its import text is parsed with
97    /// and what a rendered path is spelled back with.
98    fn paths(&self) -> PathSyntax;
99
100    /// Text every glob import contains (`::*` in Rust), so a file that does
101    /// not spell it need not be parsed when only globs are looked for;
102    /// `None` when the language has no glob imports.
103    fn glob_marker(&self) -> Option<&'static str> {
104        None
105    }
106
107    /// Everything about one file from one parse.
108    fn facts(&self, source: &str) -> Result<Facts, SearchError>;
109
110    /// Whether this language can run `query` at all: its grammar compiles
111    /// the pattern and knows the node kind. Asked once per language before
112    /// any file is read; a language that declines is skipped, not fatal.
113    fn accepts(&self, query: &Query) -> Result<(), SearchError> {
114        let _ = query;
115        Ok(())
116    }
117
118    /// Search over one file's text, honouring every part of the query.
119    fn find(&self, source: &str, query: &Query) -> Result<Vec<RawMatch>, SearchError>;
120
121    /// Declarations in one file, in source order.
122    fn symbols(&self, source: &str) -> Result<Vec<Symbol>, SearchError> {
123        let _ = source;
124        Ok(Vec::new())
125    }
126
127    /// Every identifier token spelling `name`, declarations included.
128    fn references(&self, source: &str, name: &str) -> Result<Vec<RawMatch>, SearchError> {
129        let _ = (source, name);
130        Ok(Vec::new())
131    }
132
133    /// Import paths in one file, in source order.
134    fn imports(&self, source: &str) -> Result<Vec<ImportRef>, SearchError> {
135        let _ = source;
136        Ok(Vec::new())
137    }
138
139    /// Syntax colouring for one file, as non-overlapping spans in order.
140    fn highlights(&self, source: &str) -> Result<Vec<Highlight>, SearchError> {
141        let _ = source;
142        Ok(Vec::new())
143    }
144
145    /// How the language's projects are arranged, when vvv can follow them.
146    fn layout(&self) -> Option<&dyn Layout> {
147        None
148    }
149
150    /// How to spell edits in the language, when files can be moved.
151    fn surgery(&self) -> Option<&dyn Surgery> {
152        None
153    }
154}