1 //! User (postfix)-snippet definitions.
3 //! Actual logic is implemented in [`crate::completions::postfix`] and [`crate::completions::snippet`] respectively.
7 // Feature: User Snippet Completions
9 // rust-analyzer allows the user to define custom (postfix)-snippets that may depend on items to be accessible for the current scope to be applicable.
11 // A custom snippet can be defined by adding it to the `rust-analyzer.completion.snippets` object respectively.
16 // "rust-analyzer.completion.snippets": {
18 // "prefix": ["spawn", "tspawn"],
20 // "thread::spawn(move || {",
24 // "description": "Insert a thread::spawn call",
25 // "requires": "std::thread",
32 // In the example above:
34 // * `"thread spawn"` is the name of the snippet.
36 // * `prefix` defines one or more trigger words that will trigger the snippets completion.
37 // Using `postfix` will instead create a postfix snippet.
39 // * `body` is one or more lines of content joined via newlines for the final output.
41 // * `description` is an optional description of the snippet, if unset the snippet name will be used.
43 // * `requires` is an optional list of item paths that have to be resolvable in the current crate where the completion is rendered.
44 // On failure of resolution the snippet won't be applicable, otherwise the snippet will insert an import for the items on insertion if
45 // the items aren't yet in scope.
47 // * `scope` is an optional filter for when the snippet should be applicable. Possible values are:
48 // ** for Snippet-Scopes: `expr`, `item` (default: `item`)
49 // ** for Postfix-Snippet-Scopes: `expr`, `type` (default: `expr`)
51 // The `body` field also has access to placeholders as visible in the example as `$0`.
52 // These placeholders take the form of `$number` or `${number:placeholder_text}` which can be traversed as tabstop in ascending order starting from 1,
53 // with `$0` being a special case that always comes last.
55 // There is also a special placeholder, `${receiver}`, which will be replaced by the receiver expression for postfix snippets, or nothing in case of normal snippets.
56 // It does not act as a tabstop.
57 use ide_db::helpers::{import_assets::LocatedImport, insert_use::ImportScope};
58 use itertools::Itertools;
59 use syntax::{ast, AstNode, GreenNode, SyntaxNode};
61 use crate::{context::CompletionContext, ImportEdit};
63 /// A snippet scope describing where a snippet may apply to.
64 /// These may differ slightly in meaning depending on the snippet trigger.
65 #[derive(Clone, Debug, PartialEq, Eq)]
66 pub enum SnippetScope {
72 /// A user supplied snippet.
73 #[derive(Clone, Debug, PartialEq, Eq)]
75 pub postfix_triggers: Box<[Box<str>]>,
76 pub prefix_triggers: Box<[Box<str>]>,
77 pub scope: SnippetScope,
78 pub description: Option<Box<str>>,
80 // These are `ast::Path`'s but due to SyntaxNodes not being Send we store these
81 // and reconstruct them on demand instead. This is cheaper than reparsing them
83 requires: Box<[GreenNode]>,
88 prefix_triggers: &[String],
89 postfix_triggers: &[String],
95 if prefix_triggers.is_empty() && postfix_triggers.is_empty() {
98 let (requires, snippet, description) = validate_snippet(snippet, description, requires)?;
100 // Box::into doesn't work as that has a Copy bound 😒
101 postfix_triggers: postfix_triggers.iter().map(Deref::deref).map(Into::into).collect(),
102 prefix_triggers: prefix_triggers.iter().map(Deref::deref).map(Into::into).collect(),
110 /// Returns [`None`] if the required items do not resolve.
111 pub(crate) fn imports(
113 ctx: &CompletionContext,
114 import_scope: &ImportScope,
115 ) -> Option<Vec<ImportEdit>> {
116 import_edits(ctx, import_scope, &self.requires)
119 pub fn snippet(&self) -> String {
120 self.snippet.replace("${receiver}", "")
123 pub fn postfix_snippet(&self, receiver: &str) -> String {
124 self.snippet.replace("${receiver}", receiver)
129 ctx: &CompletionContext,
130 import_scope: &ImportScope,
131 requires: &[GreenNode],
132 ) -> Option<Vec<ImportEdit>> {
133 let resolve = |import: &GreenNode| {
134 let path = ast::Path::cast(SyntaxNode::new_root(import.clone()))?;
135 let item = match ctx.scope.speculative_resolve(&path)? {
136 hir::PathResolution::Macro(mac) => mac.into(),
137 hir::PathResolution::Def(def) => def.into(),
140 let path = ctx.scope.module()?.find_use_path_prefixed(
143 ctx.config.insert_use.prefix_kind,
145 Some((path.len() > 1).then(|| ImportEdit {
146 import: LocatedImport::new(path.clone(), item, item, None),
147 scope: import_scope.clone(),
150 let mut res = Vec::with_capacity(requires.len());
151 for import in requires {
152 match resolve(import) {
153 Some(first) => res.extend(first),
164 ) -> Option<(Box<[GreenNode]>, String, Option<Box<str>>)> {
165 let mut imports = Vec::with_capacity(requires.len());
166 for path in requires.iter() {
167 let path = ast::Path::parse(path).ok()?;
168 let valid_use_path = path.segments().all(|seg| {
169 matches!(seg.kind(), Some(ast::PathSegmentKind::Name(_)))
170 || seg.generic_arg_list().is_none()
175 let green = path.syntax().green().into_owned();
178 let snippet = snippet.iter().join("\n");
179 let description = (!description.is_empty())
180 .then(|| description.split_once('\n').map_or(description, |(it, _)| it))
181 .map(ToOwned::to_owned)
183 Some((imports.into_boxed_slice(), snippet, description))