crates/completion/src/lib.rs

   1 //! `completions` crate provides utilities for generating completions of user input.
   2
   3 mod completion_config;
   4 mod completion_item;
   5 mod completion_context;
   6 mod presentation;
   7 mod patterns;
   8 mod generated_features;
   9 #[cfg(test)]
  10 mod test_utils;
  11
  12 mod complete_attribute;
  13 mod complete_dot;
  14 mod complete_record;
  15 mod complete_pattern;
  16 mod complete_fn_param;
  17 mod complete_keyword;
  18 mod complete_snippet;
  19 mod complete_qualified_path;
  20 mod complete_unqualified_path;
  21 mod complete_postfix;
  22 mod complete_macro_in_item_position;
  23 mod complete_trait_impl;
  24 mod complete_mod;
  25
  26 use base_db::FilePosition;
  27 use ide_db::RootDatabase;
  28
  29 use crate::{
  30     completion_context::CompletionContext,
  31     completion_item::{CompletionKind, Completions},
  32 };
  33
  34 pub use crate::{
  35     completion_config::CompletionConfig,
  36     completion_item::{CompletionItem, CompletionItemKind, CompletionScore, InsertTextFormat},
  37 };
  38
  39 //FIXME: split the following feature into fine-grained features.
  40
  41 // Feature: Magic Completions
  42 //
  43 // In addition to usual reference completion, rust-analyzer provides some ✨magic✨
  44 // completions as well:
  45 //
  46 // Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
  47 // is placed at the appropriate position. Even though `if` is easy to type, you
  48 // still want to complete it, to get ` { }` for free! `return` is inserted with a
  49 // space or `;` depending on the return type of the function.
  50 //
  51 // When completing a function call, `()` are automatically inserted. If a function
  52 // takes arguments, the cursor is positioned inside the parenthesis.
  53 //
  54 // There are postfix completions, which can be triggered by typing something like
  55 // `foo().if`. The word after `.` determines postfix completion. Possible variants are:
  56 //
  57 // - `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
  58 // - `expr.match` -> `match expr {}`
  59 // - `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
  60 // - `expr.ref` -> `&expr`
  61 // - `expr.refm` -> `&mut expr`
  62 // - `expr.not` -> `!expr`
  63 // - `expr.dbg` -> `dbg!(expr)`
  64 // - `expr.dbgr` -> `dbg!(&expr)`
  65 // - `expr.call` -> `(expr)`
  66 //
  67 // There also snippet completions:
  68 //
  69 // .Expressions
  70 // - `pd` -> `eprintln!(" = {:?}", );`
  71 // - `ppd` -> `eprintln!(" = {:#?}", );`
  72 //
  73 // .Items
  74 // - `tfn` -> `#[test] fn feature(){}`
  75 // - `tmod` ->
  76 // ```rust
  77 // #[cfg(test)]
  78 // mod tests {
  79 //     use super::*;
  80 //
  81 //     #[test]
  82 //     fn test_name() {}
  83 // }
  84 // ```
  85
  86 /// Main entry point for completion. We run completion as a two-phase process.
  87 ///
  88 /// First, we look at the position and collect a so-called `CompletionContext.
  89 /// This is a somewhat messy process, because, during completion, syntax tree is
  90 /// incomplete and can look really weird.
  91 ///
  92 /// Once the context is collected, we run a series of completion routines which
  93 /// look at the context and produce completion items. One subtlety about this
  94 /// phase is that completion engine should not filter by the substring which is
  95 /// already present, it should give all possible variants for the identifier at
  96 /// the caret. In other words, for
  97 ///
  98 /// ```no_run
  99 /// fn f() {
 100 ///     let foo = 92;
 101 ///     let _ = bar<|>
 102 /// }
 103 /// ```
 104 ///
 105 /// `foo` *should* be present among the completion variants. Filtering by
 106 /// identifier prefix/fuzzy match should be done higher in the stack, together
 107 /// with ordering of completions (currently this is done by the client).
 108 pub fn completions(
 109     db: &RootDatabase,
 110     config: &CompletionConfig,
 111     position: FilePosition,
 112 ) -> Option<Completions> {
 113     let ctx = CompletionContext::new(db, position, config)?;
 114
 115     if ctx.no_completion_required() {
 116         // No work required here.
 117         return None;
 118     }
 119
 120     let mut acc = Completions::default();
 121     complete_attribute::complete_attribute(&mut acc, &ctx);
 122     complete_fn_param::complete_fn_param(&mut acc, &ctx);
 123     complete_keyword::complete_expr_keyword(&mut acc, &ctx);
 124     complete_keyword::complete_use_tree_keyword(&mut acc, &ctx);
 125     complete_snippet::complete_expr_snippet(&mut acc, &ctx);
 126     complete_snippet::complete_item_snippet(&mut acc, &ctx);
 127     complete_qualified_path::complete_qualified_path(&mut acc, &ctx);
 128     complete_unqualified_path::complete_unqualified_path(&mut acc, &ctx);
 129     complete_dot::complete_dot(&mut acc, &ctx);
 130     complete_record::complete_record(&mut acc, &ctx);
 131     complete_pattern::complete_pattern(&mut acc, &ctx);
 132     complete_postfix::complete_postfix(&mut acc, &ctx);
 133     complete_macro_in_item_position::complete_macro_in_item_position(&mut acc, &ctx);
 134     complete_trait_impl::complete_trait_impl(&mut acc, &ctx);
 135     complete_mod::complete_mod(&mut acc, &ctx);
 136
 137     Some(acc)
 138 }
 139
 140 #[cfg(test)]
 141 mod tests {
 142     use crate::completion_config::CompletionConfig;
 143     use crate::test_utils;
 144
 145     struct DetailAndDocumentation<'a> {
 146         detail: &'a str,
 147         documentation: &'a str,
 148     }
 149
 150     fn check_detail_and_documentation(ra_fixture: &str, expected: DetailAndDocumentation) {
 151         let (db, position) = test_utils::position(ra_fixture);
 152         let config = CompletionConfig::default();
 153         let completions: Vec<_> = crate::completions(&db, &config, position).unwrap().into();
 154         for item in completions {
 155             if item.detail() == Some(expected.detail) {
 156                 let opt = item.documentation();
 157                 let doc = opt.as_ref().map(|it| it.as_str());
 158                 assert_eq!(doc, Some(expected.documentation));
 159                 return;
 160             }
 161         }
 162         panic!("completion detail not found: {}", expected.detail)
 163     }
 164
 165     fn check_no_completion(ra_fixture: &str) {
 166         let (db, position) = test_utils::position(ra_fixture);
 167         let config = CompletionConfig::default();
 168
 169         let completions: Option<Vec<String>> = crate::completions(&db, &config, position)
 170             .and_then(|completions| {
 171                 let completions: Vec<_> = completions.into();
 172                 if completions.is_empty() {
 173                     None
 174                 } else {
 175                     Some(completions)
 176                 }
 177             })
 178             .map(|completions| {
 179                 completions.into_iter().map(|completion| format!("{:?}", completion)).collect()
 180             });
 181
 182         // `assert_eq` instead of `assert!(completions.is_none())` to get the list of completions if test will panic.
 183         assert_eq!(completions, None, "Completions were generated, but weren't expected");
 184     }
 185
 186     #[test]
 187     fn test_completion_detail_from_macro_generated_struct_fn_doc_attr() {
 188         check_detail_and_documentation(
 189             r#"
 190             //- /lib.rs
 191             macro_rules! bar {
 192                 () => {
 193                     struct Bar;
 194                     impl Bar {
 195                         #[doc = "Do the foo"]
 196                         fn foo(&self) {}
 197                     }
 198                 }
 199             }
 200
 201             bar!();
 202
 203             fn foo() {
 204                 let bar = Bar;
 205                 bar.fo<|>;
 206             }
 207             "#,
 208             DetailAndDocumentation { detail: "fn foo(&self)", documentation: "Do the foo" },
 209         );
 210     }
 211
 212     #[test]
 213     fn test_completion_detail_from_macro_generated_struct_fn_doc_comment() {
 214         check_detail_and_documentation(
 215             r#"
 216             //- /lib.rs
 217             macro_rules! bar {
 218                 () => {
 219                     struct Bar;
 220                     impl Bar {
 221                         /// Do the foo
 222                         fn foo(&self) {}
 223                     }
 224                 }
 225             }
 226
 227             bar!();
 228
 229             fn foo() {
 230                 let bar = Bar;
 231                 bar.fo<|>;
 232             }
 233             "#,
 234             DetailAndDocumentation { detail: "fn foo(&self)", documentation: " Do the foo" },
 235         );
 236     }
 237
 238     #[test]
 239     fn test_no_completions_required() {
 240         // There must be no hint for 'in' keyword.
 241         check_no_completion(
 242             r#"
 243             fn foo() {
 244                 for i i<|>
 245             }
 246             "#,
 247         );
 248         // After 'in' keyword hints may be spawned.
 249         check_detail_and_documentation(
 250             r#"
 251             /// Do the foo
 252             fn foo() -> &'static str { "foo" }
 253
 254             fn bar() {
 255                 for c in fo<|>
 256             }
 257             "#,
 258             DetailAndDocumentation {
 259                 detail: "fn foo() -> &'static str",
 260                 documentation: "Do the foo",
 261             },
 262         );
 263     }
 264 }