1 //! See `CompletionItem` structure.
5 use hir::{Documentation, ModPath, Mutability};
7 insert_use::{self, ImportScope, MergeBehaviour},
10 use syntax::{algo, TextRange};
11 use text_edit::TextEdit;
13 use crate::config::SnippetCap;
15 /// `CompletionItem` describes a single completion variant in the editor pop-up.
16 /// It is basically a POD with various properties. To construct a
17 /// `CompletionItem`, use `new` method and the `Builder` struct.
19 pub struct CompletionItem {
20 /// Used only internally in tests, to check only specific kind of
21 /// completion (postfix, keyword, reference, etc).
23 pub(crate) completion_kind: CompletionKind,
24 /// Label in the completion pop up which identifies completion.
26 /// Range of identifier that is being completed.
28 /// It should be used primarily for UI, but we also use this to convert
29 /// genetic TextEdit into LSP's completion edit (see conv.rs).
31 /// `source_range` must contain the completion offset. `insert_text` should
32 /// start with what `source_range` points to, or VSCode will filter out the
33 /// completion silently.
34 source_range: TextRange,
35 /// What happens when user selects this item.
37 /// Typically, replaces `source_range` with new identifier.
40 insert_text_format: InsertTextFormat,
42 /// What item (struct, function, etc) are we completing.
43 kind: Option<CompletionItemKind>,
45 /// Lookup is used to check if completion item indeed can complete current
48 /// That is, in `foo.bar<|>` lookup of `abracadabra` will be accepted (it
49 /// contains `bar` sub sequence), and `quux` will rejected.
50 lookup: Option<String>,
52 /// Additional info to show in the UI pop up.
53 detail: Option<String>,
54 documentation: Option<Documentation>,
56 /// Whether this item is marked as deprecated
59 /// If completing a function call, ask the editor to show parameter popup
61 trigger_call_info: bool,
63 /// Score is useful to pre select or display in better order completion items
64 score: Option<CompletionScore>,
66 /// Indicates that a reference or mutable reference to this variable is a
68 ref_match: Option<(Mutability, CompletionScore)>,
70 /// The import data to add to completion's edits.
71 import_to_add: Option<ImportEdit>,
74 // We use custom debug for CompletionItem to make snapshot tests more readable.
75 impl fmt::Debug for CompletionItem {
76 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
77 let mut s = f.debug_struct("CompletionItem");
78 s.field("label", &self.label()).field("source_range", &self.source_range());
79 if self.text_edit().len() == 1 {
80 let atom = &self.text_edit().iter().next().unwrap();
81 s.field("delete", &atom.delete);
82 s.field("insert", &atom.insert);
84 s.field("text_edit", &self.text_edit);
86 if let Some(kind) = self.kind().as_ref() {
87 s.field("kind", kind);
89 if self.lookup() != self.label() {
90 s.field("lookup", &self.lookup());
92 if let Some(detail) = self.detail() {
93 s.field("detail", &detail);
95 if let Some(documentation) = self.documentation() {
96 s.field("documentation", &documentation);
99 s.field("deprecated", &true);
101 if let Some(score) = &self.score {
102 s.field("score", score);
104 if self.trigger_call_info {
105 s.field("trigger_call_info", &true);
111 #[derive(Debug, Clone, Copy, Ord, PartialOrd, Eq, PartialEq)]
112 pub enum CompletionScore {
113 /// If only type match
115 /// If type and name match
119 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
120 pub enum CompletionItemKind {
142 impl CompletionItemKind {
144 pub(crate) fn tag(&self) -> &'static str {
146 CompletionItemKind::Attribute => "at",
147 CompletionItemKind::Binding => "bn",
148 CompletionItemKind::BuiltinType => "bt",
149 CompletionItemKind::Const => "ct",
150 CompletionItemKind::Enum => "en",
151 CompletionItemKind::EnumVariant => "ev",
152 CompletionItemKind::Field => "fd",
153 CompletionItemKind::Function => "fn",
154 CompletionItemKind::Keyword => "kw",
155 CompletionItemKind::Macro => "ma",
156 CompletionItemKind::Method => "me",
157 CompletionItemKind::Module => "md",
158 CompletionItemKind::Snippet => "sn",
159 CompletionItemKind::Static => "sc",
160 CompletionItemKind::Struct => "st",
161 CompletionItemKind::Trait => "tt",
162 CompletionItemKind::TypeAlias => "ta",
163 CompletionItemKind::TypeParam => "tp",
164 CompletionItemKind::UnresolvedReference => "??",
169 #[derive(Debug, PartialEq, Eq, Copy, Clone)]
170 pub(crate) enum CompletionKind {
171 /// Parser-based keyword completion.
173 /// Your usual "complete all valid identifiers".
175 /// "Secret sauce" completions.
183 #[derive(Debug, PartialEq, Eq, Copy, Clone)]
184 pub enum InsertTextFormat {
189 impl CompletionItem {
191 completion_kind: CompletionKind,
192 source_range: TextRange,
193 label: impl Into<String>,
195 let label = label.into();
201 insert_text_format: InsertTextFormat::PlainText,
208 trigger_call_info: None,
212 resolve_import_lazily: false,
216 /// What user sees in pop-up in the UI.
217 pub fn label(&self) -> &str {
220 pub fn source_range(&self) -> TextRange {
224 pub fn insert_text_format(&self) -> InsertTextFormat {
225 self.insert_text_format
228 pub fn text_edit(&self) -> &TextEdit {
232 /// Short one-line additional information, like a type
233 pub fn detail(&self) -> Option<&str> {
234 self.detail.as_deref()
237 pub fn documentation(&self) -> Option<Documentation> {
238 self.documentation.clone()
240 /// What string is used for filtering.
241 pub fn lookup(&self) -> &str {
242 self.lookup.as_deref().unwrap_or(&self.label)
245 pub fn kind(&self) -> Option<CompletionItemKind> {
249 pub fn deprecated(&self) -> bool {
253 pub fn score(&self) -> Option<CompletionScore> {
257 pub fn trigger_call_info(&self) -> bool {
258 self.trigger_call_info
261 pub fn ref_match(&self) -> Option<(Mutability, CompletionScore)> {
265 pub fn import_to_add(&self) -> Option<&ImportEdit> {
266 self.import_to_add.as_ref()
270 /// An extra import to add after the completion is applied.
271 #[derive(Debug, Clone)]
272 pub struct ImportEdit {
273 pub import_path: ModPath,
274 pub import_scope: ImportScope,
275 pub merge_behaviour: Option<MergeBehaviour>,
279 /// Attempts to insert the import to the given scope, producing a text edit.
280 /// May return no edit in edge cases, such as scope already containing the import.
281 pub fn to_text_edit(&self) -> Option<TextEdit> {
282 let _p = profile::span("ImportEdit::to_edit");
284 let rewriter = insert_use::insert_use(
286 mod_path_to_ast(&self.import_path),
287 self.merge_behaviour,
289 let old_ast = rewriter.rewrite_root()?;
290 let mut import_insert = TextEdit::builder();
291 algo::diff(&old_ast, &rewriter.rewrite(&old_ast)).into_text_edit(&mut import_insert);
293 Some(import_insert.finish())
297 /// A helper to make `CompletionItem`s.
300 pub(crate) struct Builder {
301 source_range: TextRange,
302 completion_kind: CompletionKind,
303 import_to_add: Option<ImportEdit>,
304 resolve_import_lazily: bool,
306 insert_text: Option<String>,
307 insert_text_format: InsertTextFormat,
308 detail: Option<String>,
309 documentation: Option<Documentation>,
310 lookup: Option<String>,
311 kind: Option<CompletionItemKind>,
312 text_edit: Option<TextEdit>,
313 deprecated: Option<bool>,
314 trigger_call_info: Option<bool>,
315 score: Option<CompletionScore>,
316 ref_match: Option<(Mutability, CompletionScore)>,
320 pub(crate) fn build(self) -> CompletionItem {
321 let _p = profile::span("item::Builder::build");
323 let mut label = self.label;
324 let mut lookup = self.lookup;
325 let mut insert_text = self.insert_text;
327 if let Some(import_to_add) = self.import_to_add.as_ref() {
328 let mut import_path_without_last_segment = import_to_add.import_path.to_owned();
329 let _ = import_path_without_last_segment.segments.pop();
331 if !import_path_without_last_segment.segments.is_empty() {
332 if lookup.is_none() {
333 lookup = Some(label.clone());
335 if insert_text.is_none() {
336 insert_text = Some(label.clone());
338 label = format!("{}::{}", import_path_without_last_segment, label);
342 let mut text_edit = match self.text_edit {
345 TextEdit::replace(self.source_range, insert_text.unwrap_or_else(|| label.clone()))
349 if !self.resolve_import_lazily {
350 if let Some(import_edit) =
351 self.import_to_add.as_ref().and_then(|import_edit| import_edit.to_text_edit())
353 text_edit.union(import_edit).expect("Failed to unite import and completion edits");
358 source_range: self.source_range,
360 insert_text_format: self.insert_text_format,
363 documentation: self.documentation,
366 completion_kind: self.completion_kind,
367 deprecated: self.deprecated.unwrap_or(false),
368 trigger_call_info: self.trigger_call_info.unwrap_or(false),
370 ref_match: self.ref_match,
371 import_to_add: self.import_to_add,
374 pub(crate) fn lookup_by(mut self, lookup: impl Into<String>) -> Builder {
375 self.lookup = Some(lookup.into());
378 pub(crate) fn label(mut self, label: impl Into<String>) -> Builder {
379 self.label = label.into();
382 pub(crate) fn insert_text(mut self, insert_text: impl Into<String>) -> Builder {
383 self.insert_text = Some(insert_text.into());
386 pub(crate) fn insert_snippet(
389 snippet: impl Into<String>,
391 self.insert_text_format = InsertTextFormat::Snippet;
392 self.insert_text(snippet)
394 pub(crate) fn kind(mut self, kind: CompletionItemKind) -> Builder {
395 self.kind = Some(kind);
398 pub(crate) fn text_edit(mut self, edit: TextEdit) -> Builder {
399 self.text_edit = Some(edit);
402 pub(crate) fn snippet_edit(mut self, _cap: SnippetCap, edit: TextEdit) -> Builder {
403 self.insert_text_format = InsertTextFormat::Snippet;
407 pub(crate) fn detail(self, detail: impl Into<String>) -> Builder {
408 self.set_detail(Some(detail))
410 pub(crate) fn set_detail(mut self, detail: Option<impl Into<String>>) -> Builder {
411 self.detail = detail.map(Into::into);
415 pub(crate) fn documentation(self, docs: Documentation) -> Builder {
416 self.set_documentation(Some(docs))
418 pub(crate) fn set_documentation(mut self, docs: Option<Documentation>) -> Builder {
419 self.documentation = docs.map(Into::into);
422 pub(crate) fn set_deprecated(mut self, deprecated: bool) -> Builder {
423 self.deprecated = Some(deprecated);
426 pub(crate) fn set_score(mut self, score: CompletionScore) -> Builder {
427 self.score = Some(score);
430 pub(crate) fn trigger_call_info(mut self) -> Builder {
431 self.trigger_call_info = Some(true);
434 pub(crate) fn add_import(
436 import_to_add: Option<ImportEdit>,
437 resolve_import_lazily: bool,
439 self.import_to_add = import_to_add;
440 self.resolve_import_lazily = resolve_import_lazily;
443 pub(crate) fn set_ref_match(
445 ref_match: Option<(Mutability, CompletionScore)>,
447 self.ref_match = ref_match;
452 impl<'a> Into<CompletionItem> for Builder {
453 fn into(self) -> CompletionItem {