Bring the implementation closer to VSCode snippet definitions

crates/ide_completion/src/completions/postfix.rs

@@ -56,7 +56,7 @@ pub(crate) fn complete_postfix(acc: &mut Completions, ctx: &CompletionContext) {
 
     let postfix_snippet = build_postfix_snippet_builder(ctx, cap, &dot_receiver);
 
-    if !ctx.config.postfix_snippets.is_empty() {
+    if !ctx.config.snippets.is_empty() {
         add_custom_postfix_completions(acc, ctx, &postfix_snippet, &receiver_text);
     }
 
@@ -230,21 +230,23 @@ fn add_custom_postfix_completions(
 ) -> Option<()> {
     let import_scope =
         ImportScope::find_insert_use_container_with_macros(&ctx.token.parent()?, &ctx.sema)?;
-    ctx.config.postfix_snippets.iter().for_each(|snippet| {
-        let imports = match snippet.imports(ctx, &import_scope) {
-            Some(imports) => imports,
-            None => return,
-        };
-        let mut builder = postfix_snippet(
-            &snippet.label,
-            snippet.description.as_deref().unwrap_or_default(),
-            &format!("{}", snippet.snippet(&receiver_text)),
-        );
-        for import in imports.into_iter() {
-            builder.add_import(import);
-        }
-        builder.add_to(acc);
-    });
+    ctx.config.postfix_snippets().filter(|(_, snip)| snip.is_expr()).for_each(
+        |(trigger, snippet)| {
+            let imports = match snippet.imports(ctx, &import_scope) {
+                Some(imports) => imports,
+                None => return,
+            };
+            let mut builder = postfix_snippet(
+                trigger,
+                snippet.description.as_deref().unwrap_or_default(),
+                &snippet.postfix_snippet(&receiver_text),
+            );
+            for import in imports.into_iter() {
+                builder.add_import(import);
+            }
+            builder.add_to(acc);
+        },
+    );
     None
 }
 
@@ -254,7 +256,7 @@ mod tests {
 
     use crate::{
         tests::{check_edit, check_edit_with_config, filtered_completion_list, TEST_CONFIG},
-        CompletionConfig, CompletionKind, PostfixSnippet,
+        CompletionConfig, CompletionKind, Snippet,
     };
 
     fn check(ra_fixture: &str, expect: Expect) {
@@ -476,12 +478,13 @@ fn main() {
     fn custom_postfix_completion() {
         check_edit_with_config(
             CompletionConfig {
-                postfix_snippets: vec![PostfixSnippet::new(
-                    "break".into(),
-                    &["ControlFlow::Break($receiver)".into()],
+                snippets: vec![Snippet::new(
                     &[],
+                    &["break".into()],
+                    &["ControlFlow::Break($receiver)".into()],
+                    "",
                     &["core::ops::ControlFlow".into()],
-                    crate::PostfixSnippetScope::Expr,
+                    crate::SnippetScope::Expr,
                 )
                 .unwrap()],
                 ..TEST_CONFIG

crates/ide_completion/src/completions/snippet.rs

@@ -103,18 +103,20 @@ fn add_custom_completions(
 ) -> Option<()> {
     let import_scope =
         ImportScope::find_insert_use_container_with_macros(&ctx.token.parent()?, &ctx.sema)?;
-    ctx.config.snippets.iter().filter(|snip| snip.scope == scope).for_each(|snip| {
-        let imports = match snip.imports(ctx, &import_scope) {
-            Some(imports) => imports,
-            None => return,
-        };
-        let mut builder = snippet(ctx, cap, &snip.label, &snip.snippet);
-        for import in imports.into_iter() {
-            builder.add_import(import);
-        }
-        builder.detail(snip.description.as_deref().unwrap_or_default());
-        builder.add_to(acc);
-    });
+    ctx.config.prefix_snippets().filter(|(_, snip)| snip.scope == scope).for_each(
+        |(trigger, snip)| {
+            let imports = match snip.imports(ctx, &import_scope) {
+                Some(imports) => imports,
+                None => return,
+            };
+            let mut builder = snippet(ctx, cap, &trigger, &snip.snippet());
+            for import in imports.into_iter() {
+                builder.add_import(import);
+            }
+            builder.detail(snip.description.as_deref().unwrap_or_default());
+            builder.add_to(acc);
+        },
+    );
     None
 }
 
@@ -130,9 +132,10 @@ mod tests {
         check_edit_with_config(
             CompletionConfig {
                 snippets: vec![Snippet::new(
-                    "break".into(),
-                    &["ControlFlow::Break(())".into()],
+                    &["break".into()],
                     &[],
+                    &["ControlFlow::Break(())".into()],
+                    "",
                     &["core::ops::ControlFlow".into()],
                     crate::SnippetScope::Expr,
                 )

crates/ide_completion/src/config.rs

@@ -6,7 +6,7 @@
 
 use ide_db::helpers::{insert_use::InsertUseConfig, SnippetCap};
 
-use crate::snippet::{PostfixSnippet, Snippet};
+use crate::snippet::Snippet;
 
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct CompletionConfig {
@@ -17,6 +17,18 @@ pub struct CompletionConfig {
     pub add_call_argument_snippets: bool,
     pub snippet_cap: Option<SnippetCap>,
     pub insert_use: InsertUseConfig,
-    pub postfix_snippets: Vec<PostfixSnippet>,
     pub snippets: Vec<Snippet>,
 }
+
+impl CompletionConfig {
+    pub fn postfix_snippets(&self) -> impl Iterator<Item = (&str, &Snippet)> {
+        self.snippets.iter().flat_map(|snip| {
+            snip.postfix_triggers.iter().map(move |trigger| (trigger.as_str(), snip))
+        })
+    }
+    pub fn prefix_snippets(&self) -> impl Iterator<Item = (&str, &Snippet)> {
+        self.snippets.iter().flat_map(|snip| {
+            snip.prefix_triggers.iter().map(move |trigger| (trigger.as_str(), snip))
+        })
+    }
+}

crates/ide_completion/src/lib.rs

@@ -29,7 +29,7 @@ use crate::{completions::Completions, context::CompletionContext, item::Completi
 pub use crate::{
     config::CompletionConfig,
     item::{CompletionItem, CompletionItemKind, CompletionRelevance, ImportEdit},
-    snippet::{PostfixSnippet, PostfixSnippetScope, Snippet, SnippetScope},
+    snippet::{Snippet, SnippetScope},
 };
 
 //FIXME: split the following feature into fine-grained features.

crates/ide_completion/src/snippet.rs

@@ -1,6 +1,57 @@
 //! User (postfix)-snippet definitions.
 //!
 //! Actual logic is implemented in [`crate::completions::postfix`] and [`crate::completions::snippet`].
+
+// Feature: User Snippet Completions
+//
+// 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.
+//
+// A custom snippet can be defined by adding it to the `rust-analyzer.completion.snippets` object respectively.
+//
+// [source,json]
+// ----
+// {
+//   "rust-analyzer.completion.snippets": {
+//     "thread spawn": {
+//       "prefix": ["spawn", "tspawn"],
+//       "body": [
+//         "thread::spawn(move || {",
+//         "\t$0",
+//         ")};",
+//       ],
+//       "description": "Insert a thread::spawn call",
+//       "requires": "std::thread",
+//       "scope": "expr",
+//     }
+//   }
+// }
+// ----
+//
+// In the example above:
+//
+// * `"thread spawn"` is the name of the snippet.
+//
+// * `prefix` defines one or more trigger words that will trigger the snippets completion.
+// Using `postfix` will instead create a postfix snippet.
+//
+// * `body` is one or more lines of content joined via newlines for the final output.
+//
+// * `description` is an optional description of the snippet, if unset the snippet name will be used.
+//
+// * `requires` is an optional list of item paths that have to be resolvable in the current crate where the completion is rendered.
+// On failure of resolution the snippet won't be applicable, otherwise the snippet will insert an import for the items on insertion if
+// the items aren't yet in scope.
+//
+// * `scope` is an optional filter for when the snippet should be applicable. Possible values are:
+// ** for Snippet-Scopes: `expr`, `item` (default: `item`)
+// ** for Postfix-Snippet-Scopes: `expr`, `type` (default: `expr`)
+//
+// The `body` field also has access to placeholders as visible in the example as `$0`.
+// These placeholders take the form of `$number` or `${number:placeholder_text}` which can be traversed as tabstop in ascending order starting from 1,
+// with `$0` being a special case that always comes last.
+//
+// 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.
+// It does not act as a tabstop.
 use ide_db::helpers::{import_assets::LocatedImport, insert_use::ImportScope};
 use itertools::Itertools;
 use syntax::ast;
@@ -8,50 +59,40 @@ use syntax::ast;
 use crate::{context::CompletionContext, ImportEdit};
 
 #[derive(Clone, Debug, PartialEq, Eq)]
-pub enum PostfixSnippetScope {
+pub enum SnippetScope {
+    Item,
     Expr,
     Type,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq)]
-pub enum SnippetScope {
-    Item,
-    Expr,
-}
-
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct PostfixSnippet {
-    pub scope: PostfixSnippetScope,
-    pub label: String,
+pub struct Snippet {
+    pub postfix_triggers: Box<[String]>,
+    pub prefix_triggers: Box<[String]>,
+    pub scope: SnippetScope,
     snippet: String,
     pub description: Option<String>,
     pub requires: Box<[String]>,
 }
 
-#[derive(Clone, Debug, PartialEq, Eq)]
-#[non_exhaustive]
-pub struct Snippet {
-    pub scope: SnippetScope,
-    pub label: String,
-    pub snippet: String,
-    pub description: Option<String>,
-    pub requires: Box<[String]>,
-}
 impl Snippet {
     pub fn new(
-        label: String,
+        prefix_triggers: &[String],
+        postfix_triggers: &[String],
         snippet: &[String],
-        description: &[String],
+        description: &str,
         requires: &[String],
         scope: SnippetScope,
     ) -> Option<Self> {
         let (snippet, description) = validate_snippet(snippet, description, requires)?;
         Some(Snippet {
+            // Box::into doesn't work as that has a Copy bound 😒
+            postfix_triggers: postfix_triggers.iter().cloned().collect(),
+            prefix_triggers: prefix_triggers.iter().cloned().collect(),
             scope,
-            label,
             snippet,
             description,
-            requires: requires.iter().cloned().collect(), // Box::into doesn't work as that has a Copy bound 😒
+            requires: requires.iter().cloned().collect(),
         })
     }
 
@@ -64,6 +105,14 @@ impl Snippet {
         import_edits(ctx, import_scope, &self.requires)
     }
 
+    pub fn snippet(&self) -> String {
+        self.snippet.replace("${receiver}", "")
+    }
+
+    pub fn postfix_snippet(&self, receiver: &str) -> String {
+        self.snippet.replace("${receiver}", receiver)
+    }
+
     pub fn is_item(&self) -> bool {
         self.scope == SnippetScope::Item
     }
@@ -73,46 +122,6 @@ impl Snippet {
     }
 }
 
-impl PostfixSnippet {
-    pub fn new(
-        label: String,
-        snippet: &[String],
-        description: &[String],
-        requires: &[String],
-        scope: PostfixSnippetScope,
-    ) -> Option<Self> {
-        let (snippet, description) = validate_snippet(snippet, description, requires)?;
-        Some(PostfixSnippet {
-            scope,
-            label,
-            snippet,
-            description,
-            requires: requires.iter().cloned().collect(), // Box::into doesn't work as that has a Copy bound 😒
-        })
-    }
-
-    /// Returns None if the required items do not resolve.
-    pub(crate) fn imports(
-        &self,
-        ctx: &CompletionContext,
-        import_scope: &ImportScope,
-    ) -> Option<Vec<ImportEdit>> {
-        import_edits(ctx, import_scope, &self.requires)
-    }
-
-    pub fn snippet(&self, receiver: &str) -> String {
-        self.snippet.replace("$receiver", receiver)
-    }
-
-    pub fn is_item(&self) -> bool {
-        self.scope == PostfixSnippetScope::Type
-    }
-
-    pub fn is_expr(&self) -> bool {
-        self.scope == PostfixSnippetScope::Expr
-    }
-}
-
 fn import_edits(
     ctx: &CompletionContext,
     import_scope: &ImportScope,
@@ -147,7 +156,7 @@ fn import_edits(
 
 fn validate_snippet(
     snippet: &[String],
-    description: &[String],
+    description: &str,
     requires: &[String],
 ) -> Option<(String, Option<String>)> {
     // validate that these are indeed simple paths
@@ -162,7 +171,6 @@ fn validate_snippet(
         return None;
     }
     let snippet = snippet.iter().join("\n");
-    let description = description.iter().join("\n");
-    let description = if description.is_empty() { None } else { Some(description) };
+    let description = if description.is_empty() { None } else { Some(description.to_owned()) };
     Some((snippet, description))
 }

crates/ide_completion/src/tests.rs

@@ -74,7 +74,6 @@ pub(crate) const TEST_CONFIG: CompletionConfig = CompletionConfig {
         group: true,
         skip_glob_imports: true,
     },
-    postfix_snippets: Vec::new(),
     snippets: Vec::new(),
 };