1 //! User (postfix)-snippet definitions.
3 //! Actual logic is implemented in [`crate::completions::postfix`] and [`crate::completions::snippet`] respectively.
5 // Feature: User Snippet Completions
7 // 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.
9 // A custom snippet can be defined by adding it to the `rust-analyzer.completion.snippets.custom` object respectively.
14 // "rust-analyzer.completion.snippets.custom": {
16 // "prefix": ["spawn", "tspawn"],
18 // "thread::spawn(move || {",
22 // "description": "Insert a thread::spawn call",
23 // "requires": "std::thread",
30 // In the example above:
32 // * `"thread spawn"` is the name of the snippet.
34 // * `prefix` defines one or more trigger words that will trigger the snippets completion.
35 // Using `postfix` will instead create a postfix snippet.
37 // * `body` is one or more lines of content joined via newlines for the final output.
39 // * `description` is an optional description of the snippet, if unset the snippet name will be used.
41 // * `requires` is an optional list of item paths that have to be resolvable in the current crate where the completion is rendered.
42 // On failure of resolution the snippet won't be applicable, otherwise the snippet will insert an import for the items on insertion if
43 // the items aren't yet in scope.
45 // * `scope` is an optional filter for when the snippet should be applicable. Possible values are:
46 // ** for Snippet-Scopes: `expr`, `item` (default: `item`)
47 // ** for Postfix-Snippet-Scopes: `expr`, `type` (default: `expr`)
49 // The `body` field also has access to placeholders as visible in the example as `$0`.
50 // These placeholders take the form of `$number` or `${number:placeholder_text}` which can be traversed as tabstop in ascending order starting from 1,
51 // with `$0` being a special case that always comes last.
53 // There is also a special placeholder, `${receiver}`, which will be replaced by the receiver expression for postfix snippets, or a `$0` tabstop in case of normal snippets.
54 // This replacement for normal snippets allows you to reuse a snippet for both post- and prefix in a single definition.
56 // For the VSCode editor, rust-analyzer also ships with a small set of defaults which can be removed
57 // by overwriting the settings object mentioned above, the defaults are:
63 // "body": "Arc::new(${receiver})",
64 // "requires": "std::sync::Arc",
65 // "description": "Put the expression into an `Arc`",
70 // "body": "Rc::new(${receiver})",
71 // "requires": "std::rc::Rc",
72 // "description": "Put the expression into an `Rc`",
76 // "postfix": "pinbox",
77 // "body": "Box::pin(${receiver})",
78 // "requires": "std::boxed::Box",
79 // "description": "Put the expression into a pinned `Box`",
84 // "body": "Ok(${receiver})",
85 // "description": "Wrap the expression in a `Result::Ok`",
90 // "body": "Err(${receiver})",
91 // "description": "Wrap the expression in a `Result::Err`",
96 // "body": "Some(${receiver})",
97 // "description": "Wrap the expression in an `Option::Some`",
103 use ide_db::imports::import_assets::LocatedImport;
104 use itertools::Itertools;
105 use syntax::{ast, AstNode, GreenNode, SyntaxNode};
107 use crate::context::CompletionContext;
109 /// A snippet scope describing where a snippet may apply to.
110 /// These may differ slightly in meaning depending on the snippet trigger.
111 #[derive(Clone, Debug, PartialEq, Eq)]
112 pub enum SnippetScope {
118 /// A user supplied snippet.
119 #[derive(Clone, Debug, PartialEq, Eq)]
121 pub postfix_triggers: Box<[Box<str>]>,
122 pub prefix_triggers: Box<[Box<str>]>,
123 pub scope: SnippetScope,
124 pub description: Option<Box<str>>,
126 // These are `ast::Path`'s but due to SyntaxNodes not being Send we store these
127 // and reconstruct them on demand instead. This is cheaper than reparsing them
129 requires: Box<[GreenNode]>,
134 prefix_triggers: &[String],
135 postfix_triggers: &[String],
141 if prefix_triggers.is_empty() && postfix_triggers.is_empty() {
144 let (requires, snippet, description) = validate_snippet(snippet, description, requires)?;
146 // Box::into doesn't work as that has a Copy bound 😒
147 postfix_triggers: postfix_triggers.iter().map(String::as_str).map(Into::into).collect(),
148 prefix_triggers: prefix_triggers.iter().map(String::as_str).map(Into::into).collect(),
156 /// Returns [`None`] if the required items do not resolve.
157 pub(crate) fn imports(&self, ctx: &CompletionContext<'_>) -> Option<Vec<LocatedImport>> {
158 import_edits(ctx, &self.requires)
161 pub fn snippet(&self) -> String {
162 self.snippet.replace("${receiver}", "$0")
165 pub fn postfix_snippet(&self, receiver: &str) -> String {
166 self.snippet.replace("${receiver}", receiver)
170 fn import_edits(ctx: &CompletionContext<'_>, requires: &[GreenNode]) -> Option<Vec<LocatedImport>> {
171 let resolve = |import: &GreenNode| {
172 let path = ast::Path::cast(SyntaxNode::new_root(import.clone()))?;
173 let item = match ctx.scope.speculative_resolve(&path)? {
174 hir::PathResolution::Def(def) => def.into(),
177 let path = ctx.module.find_use_path_prefixed(
180 ctx.config.insert_use.prefix_kind,
181 ctx.config.prefer_no_std,
183 Some((path.len() > 1).then(|| LocatedImport::new(path.clone(), item, item, None)))
185 let mut res = Vec::with_capacity(requires.len());
186 for import in requires {
187 match resolve(import) {
188 Some(first) => res.extend(first),
199 ) -> Option<(Box<[GreenNode]>, String, Option<Box<str>>)> {
200 let mut imports = Vec::with_capacity(requires.len());
201 for path in requires.iter() {
202 let use_path = ast::SourceFile::parse(&format!("use {};", path))
205 .find_map(ast::Path::cast)?;
206 if use_path.syntax().text() != path.as_str() {
209 let green = use_path.syntax().green().into_owned();
212 let snippet = snippet.iter().join("\n");
213 let description = (!description.is_empty())
214 .then(|| description.split_once('\n').map_or(description, |(it, _)| it))
215 .map(ToOwned::to_owned)
217 Some((imports.into_boxed_slice(), snippet, description))