1 //! ide crate provides "ide-centric" APIs for the rust-analyzer. That is,
2 //! it generally operates with files and text ranges, and returns results as
3 //! Strings, suitable for displaying to the human.
5 //! What powers this API are the `RootDatabase` struct, which defines a `salsa`
6 //! database, and the `hir` crate, where majority of the analysis happens.
7 //! However, IDE specific bits of the analysis (most notably completion) happen
10 // For proving that RootDatabase is RefUnwindSafe.
11 #![recursion_limit = "128"]
12 #![warn(rust_2018_idioms, unused_lifetimes, semicolon_in_expressions_from_macros)]
15 macro_rules! eprintln {
16 ($($tt:tt)*) => { stdx::eprintln!($($tt)*) };
24 mod navigation_target;
30 mod highlight_related;
38 mod goto_implementation;
39 mod goto_type_definition;
54 mod syntax_highlighting;
60 mod shuffle_crate_graph;
67 salsa::{self, ParallelDatabase},
68 CrateOrigin, Env, FileLoader, FileSet, SourceDatabase, VfsPath,
70 symbol_index, LineIndexDatabase,
72 use syntax::SourceFile;
74 use crate::navigation_target::{ToNav, TryToNav};
77 annotations::{Annotation, AnnotationConfig, AnnotationKind},
78 call_hierarchy::CallItem,
79 expand_macro::ExpandedMacro,
80 file_structure::{StructureNode, StructureNodeKind},
81 folding_ranges::{Fold, FoldKind},
82 highlight_related::{HighlightRelatedConfig, HighlightedRange},
83 hover::{HoverAction, HoverConfig, HoverDocFormat, HoverGotoTypeData, HoverResult},
85 ClosureReturnTypeHints, InlayHint, InlayHintsConfig, InlayKind, InlayTooltip,
86 LifetimeElisionHints, ReborrowHints,
88 join_lines::JoinLinesConfig,
90 moniker::{MonikerKind, MonikerResult, PackageInformation},
92 navigation_target::NavigationTarget,
93 prime_caches::ParallelPrimeCachesProgress,
94 references::ReferenceSearchResult,
96 runnables::{Runnable, RunnableKind, TestId},
97 signature_help::SignatureHelp,
98 static_index::{StaticIndex, StaticIndexedFile, TokenId, TokenStaticData},
99 syntax_highlighting::{
100 tags::{Highlight, HlMod, HlMods, HlOperator, HlPunct, HlTag},
104 pub use hir::{Documentation, Semantics};
105 pub use ide_assists::{
106 Assist, AssistConfig, AssistId, AssistKind, AssistResolveStrategy, SingleResolve,
108 pub use ide_completion::{
109 CallableSnippets, CompletionConfig, CompletionItem, CompletionItemKind, CompletionRelevance,
110 Snippet, SnippetScope,
114 Cancelled, Change, CrateGraph, CrateId, Edition, FileId, FilePosition, FileRange,
115 SourceRoot, SourceRootId,
118 line_index::{LineCol, LineColUtf16, LineIndex},
119 search::{ReferenceCategory, SearchScope},
120 source_change::{FileSystemEdit, SourceChange},
122 RootDatabase, SymbolKind,
124 pub use ide_diagnostics::{Diagnostic, DiagnosticsConfig, ExprFillDefaultMode, Severity};
125 pub use ide_ssr::SsrError;
126 pub use syntax::{TextRange, TextSize};
127 pub use text_edit::{Indel, TextEdit};
129 pub type Cancellable<T> = Result<T, Cancelled>;
131 /// Info associated with a text range.
133 pub struct RangeInfo<T> {
134 pub range: TextRange,
138 impl<T> RangeInfo<T> {
139 pub fn new(range: TextRange, info: T) -> RangeInfo<T> {
140 RangeInfo { range, info }
144 /// `AnalysisHost` stores the current state of the world.
146 pub struct AnalysisHost {
151 pub fn new(lru_capacity: Option<usize>) -> AnalysisHost {
152 AnalysisHost { db: RootDatabase::new(lru_capacity) }
155 pub fn update_lru_capacity(&mut self, lru_capacity: Option<usize>) {
156 self.db.update_lru_capacity(lru_capacity);
159 /// Returns a snapshot of the current state, which you can query for
160 /// semantic information.
161 pub fn analysis(&self) -> Analysis {
162 Analysis { db: self.db.snapshot() }
165 /// Applies changes to the current state of the world. If there are
166 /// outstanding snapshots, they will be canceled.
167 pub fn apply_change(&mut self, change: Change) {
168 self.db.apply_change(change)
171 /// NB: this clears the database
172 pub fn per_query_memory_usage(&mut self) -> Vec<(String, profile::Bytes)> {
173 self.db.per_query_memory_usage()
175 pub fn request_cancellation(&mut self) {
176 self.db.request_cancellation();
178 pub fn raw_database(&self) -> &RootDatabase {
181 pub fn raw_database_mut(&mut self) -> &mut RootDatabase {
185 pub fn shuffle_crate_graph(&mut self) {
186 shuffle_crate_graph::shuffle_crate_graph(&mut self.db);
190 impl Default for AnalysisHost {
191 fn default() -> AnalysisHost {
192 AnalysisHost::new(None)
196 /// Analysis is a snapshot of a world state at a moment in time. It is the main
197 /// entry point for asking semantic information about the world. When the world
198 /// state is advanced using `AnalysisHost::apply_change` method, all existing
199 /// `Analysis` are canceled (most method return `Err(Canceled)`).
201 pub struct Analysis {
202 db: salsa::Snapshot<RootDatabase>,
205 // As a general design guideline, `Analysis` API are intended to be independent
206 // from the language server protocol. That is, when exposing some functionality
207 // we should think in terms of "what API makes most sense" and not in terms of
208 // "what types LSP uses". Although currently LSP is the only consumer of the
209 // API, the API should in theory be usable as a library, or via a different
212 // Creates an analysis instance for a single file, without any external
213 // dependencies, stdlib support or ability to apply changes. See
214 // `AnalysisHost` for creating a fully-featured analysis.
215 pub fn from_single_file(text: String) -> (Analysis, FileId) {
216 let mut host = AnalysisHost::default();
217 let file_id = FileId(0);
218 let mut file_set = FileSet::default();
219 file_set.insert(file_id, VfsPath::new_virtual_path("/main.rs".to_string()));
220 let source_root = SourceRoot::new_local(file_set);
222 let mut change = Change::new();
223 change.set_roots(vec![source_root]);
224 let mut crate_graph = CrateGraph::default();
225 // FIXME: cfg options
226 // Default to enable test for single file.
227 let mut cfg_options = CfgOptions::default();
228 cfg_options.insert_atom("test".into());
229 crate_graph.add_crate_root(
239 CrateOrigin::CratesIo { repo: None },
241 change.change_file(file_id, Some(Arc::new(text)));
242 change.set_crate_graph(crate_graph);
243 host.apply_change(change);
244 (host.analysis(), file_id)
247 /// Debug info about the current state of the analysis.
248 pub fn status(&self, file_id: Option<FileId>) -> Cancellable<String> {
249 self.with_db(|db| status::status(&*db, file_id))
252 pub fn parallel_prime_caches<F>(&self, num_worker_threads: u8, cb: F) -> Cancellable<()>
254 F: Fn(ParallelPrimeCachesProgress) + Sync + std::panic::UnwindSafe,
256 self.with_db(move |db| prime_caches::parallel_prime_caches(db, num_worker_threads, &cb))
259 /// Gets the text of the source file.
260 pub fn file_text(&self, file_id: FileId) -> Cancellable<Arc<String>> {
261 self.with_db(|db| db.file_text(file_id))
264 /// Gets the syntax tree of the file.
265 pub fn parse(&self, file_id: FileId) -> Cancellable<SourceFile> {
266 self.with_db(|db| db.parse(file_id).tree())
269 /// Returns true if this file belongs to an immutable library.
270 pub fn is_library_file(&self, file_id: FileId) -> Cancellable<bool> {
271 use ide_db::base_db::SourceDatabaseExt;
272 self.with_db(|db| db.source_root(db.file_source_root(file_id)).is_library)
275 /// Gets the file's `LineIndex`: data structure to convert between absolute
276 /// offsets and line/column representation.
277 pub fn file_line_index(&self, file_id: FileId) -> Cancellable<Arc<LineIndex>> {
278 self.with_db(|db| db.line_index(file_id))
281 /// Selects the next syntactic nodes encompassing the range.
282 pub fn extend_selection(&self, frange: FileRange) -> Cancellable<TextRange> {
283 self.with_db(|db| extend_selection::extend_selection(db, frange))
286 /// Returns position of the matching brace (all types of braces are
288 pub fn matching_brace(&self, position: FilePosition) -> Cancellable<Option<TextSize>> {
290 let parse = db.parse(position.file_id);
291 let file = parse.tree();
292 matching_brace::matching_brace(&file, position.offset)
296 /// Returns a syntax tree represented as `String`, for debug purposes.
297 // FIXME: use a better name here.
301 text_range: Option<TextRange>,
302 ) -> Cancellable<String> {
303 self.with_db(|db| syntax_tree::syntax_tree(db, file_id, text_range))
306 pub fn view_hir(&self, position: FilePosition) -> Cancellable<String> {
307 self.with_db(|db| view_hir::view_hir(db, position))
310 pub fn view_item_tree(&self, file_id: FileId) -> Cancellable<String> {
311 self.with_db(|db| view_item_tree::view_item_tree(db, file_id))
314 /// Renders the crate graph to GraphViz "dot" syntax.
315 pub fn view_crate_graph(&self, full: bool) -> Cancellable<Result<String, String>> {
316 self.with_db(|db| view_crate_graph::view_crate_graph(db, full))
319 pub fn expand_macro(&self, position: FilePosition) -> Cancellable<Option<ExpandedMacro>> {
320 self.with_db(|db| expand_macro::expand_macro(db, position))
323 /// Returns an edit to remove all newlines in the range, cleaning up minor
324 /// stuff like trailing commas.
325 pub fn join_lines(&self, config: &JoinLinesConfig, frange: FileRange) -> Cancellable<TextEdit> {
327 let parse = db.parse(frange.file_id);
328 join_lines::join_lines(config, &parse.tree(), frange.range)
332 /// Returns an edit which should be applied when opening a new line, fixing
333 /// up minor stuff like continuing the comment.
334 /// The edit will be a snippet (with `$0`).
335 pub fn on_enter(&self, position: FilePosition) -> Cancellable<Option<TextEdit>> {
336 self.with_db(|db| typing::on_enter(db, position))
339 /// Returns an edit which should be applied after a character was typed.
341 /// This is useful for some on-the-fly fixups, like adding `;` to `let =`
343 pub fn on_char_typed(
345 position: FilePosition,
348 ) -> Cancellable<Option<SourceChange>> {
349 // Fast path to not even parse the file.
350 if !typing::TRIGGER_CHARS.contains(char_typed) {
353 if char_typed == '<' && !autoclose {
357 self.with_db(|db| typing::on_char_typed(db, position, char_typed))
360 /// Returns a tree representation of symbols in the file. Useful to draw a
362 pub fn file_structure(&self, file_id: FileId) -> Cancellable<Vec<StructureNode>> {
363 self.with_db(|db| file_structure::file_structure(&db.parse(file_id).tree()))
366 /// Returns a list of the places in the file where type hints can be displayed.
369 config: &InlayHintsConfig,
371 range: Option<FileRange>,
372 ) -> Cancellable<Vec<InlayHint>> {
373 self.with_db(|db| inlay_hints::inlay_hints(db, file_id, range, config))
376 /// Returns the set of folding ranges.
377 pub fn folding_ranges(&self, file_id: FileId) -> Cancellable<Vec<Fold>> {
378 self.with_db(|db| folding_ranges::folding_ranges(&db.parse(file_id).tree()))
381 /// Fuzzy searches for a symbol.
382 pub fn symbol_search(&self, query: Query) -> Cancellable<Vec<NavigationTarget>> {
384 symbol_index::world_symbols(db, query)
385 .into_iter() // xx: should we make this a par iter?
386 .filter_map(|s| s.try_to_nav(db))
391 /// Returns the definitions from the symbol at `position`.
392 pub fn goto_definition(
394 position: FilePosition,
395 ) -> Cancellable<Option<RangeInfo<Vec<NavigationTarget>>>> {
396 self.with_db(|db| goto_definition::goto_definition(db, position))
399 /// Returns the declaration from the symbol at `position`.
400 pub fn goto_declaration(
402 position: FilePosition,
403 ) -> Cancellable<Option<RangeInfo<Vec<NavigationTarget>>>> {
404 self.with_db(|db| goto_declaration::goto_declaration(db, position))
407 /// Returns the impls from the symbol at `position`.
408 pub fn goto_implementation(
410 position: FilePosition,
411 ) -> Cancellable<Option<RangeInfo<Vec<NavigationTarget>>>> {
412 self.with_db(|db| goto_implementation::goto_implementation(db, position))
415 /// Returns the type definitions for the symbol at `position`.
416 pub fn goto_type_definition(
418 position: FilePosition,
419 ) -> Cancellable<Option<RangeInfo<Vec<NavigationTarget>>>> {
420 self.with_db(|db| goto_type_definition::goto_type_definition(db, position))
423 /// Finds all usages of the reference at point.
424 pub fn find_all_refs(
426 position: FilePosition,
427 search_scope: Option<SearchScope>,
428 ) -> Cancellable<Option<Vec<ReferenceSearchResult>>> {
429 self.with_db(|db| references::find_all_refs(&Semantics::new(db), position, search_scope))
432 /// Finds all methods and free functions for the file. Does not return tests!
433 pub fn find_all_methods(&self, file_id: FileId) -> Cancellable<Vec<FileRange>> {
434 self.with_db(|db| fn_references::find_all_methods(db, file_id))
437 /// Returns a short text describing element at position.
440 config: &HoverConfig,
442 ) -> Cancellable<Option<RangeInfo<HoverResult>>> {
443 self.with_db(|db| hover::hover(db, range, config))
446 /// Returns moniker of symbol at position.
449 position: FilePosition,
450 ) -> Cancellable<Option<RangeInfo<Vec<moniker::MonikerResult>>>> {
451 self.with_db(|db| moniker::moniker(db, position))
454 /// Return URL(s) for the documentation of the symbol under the cursor.
455 pub fn external_docs(
457 position: FilePosition,
458 ) -> Cancellable<Option<doc_links::DocumentationLink>> {
459 self.with_db(|db| doc_links::external_docs(db, &position))
462 /// Computes parameter information at the given position.
463 pub fn signature_help(&self, position: FilePosition) -> Cancellable<Option<SignatureHelp>> {
464 self.with_db(|db| signature_help::signature_help(db, position))
467 /// Computes call hierarchy candidates for the given file position.
468 pub fn call_hierarchy(
470 position: FilePosition,
471 ) -> Cancellable<Option<RangeInfo<Vec<NavigationTarget>>>> {
472 self.with_db(|db| call_hierarchy::call_hierarchy(db, position))
475 /// Computes incoming calls for the given file position.
476 pub fn incoming_calls(&self, position: FilePosition) -> Cancellable<Option<Vec<CallItem>>> {
477 self.with_db(|db| call_hierarchy::incoming_calls(db, position))
480 /// Computes outgoing calls for the given file position.
481 pub fn outgoing_calls(&self, position: FilePosition) -> Cancellable<Option<Vec<CallItem>>> {
482 self.with_db(|db| call_hierarchy::outgoing_calls(db, position))
485 /// Returns a `mod name;` declaration which created the current module.
486 pub fn parent_module(&self, position: FilePosition) -> Cancellable<Vec<NavigationTarget>> {
487 self.with_db(|db| parent_module::parent_module(db, position))
490 /// Returns crates this file belongs too.
491 pub fn crate_for(&self, file_id: FileId) -> Cancellable<Vec<CrateId>> {
492 self.with_db(|db| parent_module::crate_for(db, file_id))
495 /// Returns the edition of the given crate.
496 pub fn crate_edition(&self, crate_id: CrateId) -> Cancellable<Edition> {
497 self.with_db(|db| db.crate_graph()[crate_id].edition)
500 /// Returns the root file of the given crate.
501 pub fn crate_root(&self, crate_id: CrateId) -> Cancellable<FileId> {
502 self.with_db(|db| db.crate_graph()[crate_id].root_file_id)
505 /// Returns the set of possible targets to run for the current file.
506 pub fn runnables(&self, file_id: FileId) -> Cancellable<Vec<Runnable>> {
507 self.with_db(|db| runnables::runnables(db, file_id))
510 /// Returns the set of tests for the given file position.
511 pub fn related_tests(
513 position: FilePosition,
514 search_scope: Option<SearchScope>,
515 ) -> Cancellable<Vec<Runnable>> {
516 self.with_db(|db| runnables::related_tests(db, position, search_scope))
519 /// Computes syntax highlighting for the given file
520 pub fn highlight(&self, file_id: FileId) -> Cancellable<Vec<HlRange>> {
521 self.with_db(|db| syntax_highlighting::highlight(db, file_id, None, false))
524 /// Computes all ranges to highlight for a given item in a file.
525 pub fn highlight_related(
527 config: HighlightRelatedConfig,
528 position: FilePosition,
529 ) -> Cancellable<Option<Vec<HighlightedRange>>> {
531 highlight_related::highlight_related(&Semantics::new(db), config, position)
535 /// Computes syntax highlighting for the given file range.
536 pub fn highlight_range(&self, frange: FileRange) -> Cancellable<Vec<HlRange>> {
538 syntax_highlighting::highlight(db, frange.file_id, Some(frange.range), false)
542 /// Computes syntax highlighting for the given file.
543 pub fn highlight_as_html(&self, file_id: FileId, rainbow: bool) -> Cancellable<String> {
544 self.with_db(|db| syntax_highlighting::highlight_as_html(db, file_id, rainbow))
547 /// Computes completions at the given position.
550 config: &CompletionConfig,
551 position: FilePosition,
552 trigger_character: Option<char>,
553 ) -> Cancellable<Option<Vec<CompletionItem>>> {
555 ide_completion::completions(db, config, position, trigger_character).map(Into::into)
559 /// Resolves additional completion data at the position given.
560 pub fn resolve_completion_edits(
562 config: &CompletionConfig,
563 position: FilePosition,
564 imports: impl IntoIterator<Item = (String, String)> + std::panic::UnwindSafe,
565 ) -> Cancellable<Vec<TextEdit>> {
567 .with_db(|db| ide_completion::resolve_completion_edits(db, config, position, imports))?
568 .unwrap_or_default())
571 /// Computes the set of diagnostics for the given file.
574 config: &DiagnosticsConfig,
575 resolve: AssistResolveStrategy,
577 ) -> Cancellable<Vec<Diagnostic>> {
578 self.with_db(|db| ide_diagnostics::diagnostics(db, config, &resolve, file_id))
581 /// Convenience function to return assists + quick fixes for diagnostics
582 pub fn assists_with_fixes(
584 assist_config: &AssistConfig,
585 diagnostics_config: &DiagnosticsConfig,
586 resolve: AssistResolveStrategy,
588 ) -> Cancellable<Vec<Assist>> {
589 let include_fixes = match &assist_config.allowed {
590 Some(it) => it.iter().any(|&it| it == AssistKind::None || it == AssistKind::QuickFix),
595 let diagnostic_assists = if include_fixes {
596 ide_diagnostics::diagnostics(db, diagnostics_config, &resolve, frange.file_id)
598 .flat_map(|it| it.fixes.unwrap_or_default())
599 .filter(|it| it.target.intersect(frange.range).is_some())
604 let ssr_assists = ssr::ssr_assists(db, &resolve, frange);
605 let assists = ide_assists::assists(db, assist_config, resolve, frange);
607 let mut res = diagnostic_assists;
608 res.extend(ssr_assists.into_iter());
609 res.extend(assists.into_iter());
615 /// Returns the edit required to rename reference at the position to the new
619 position: FilePosition,
621 ) -> Cancellable<Result<SourceChange, RenameError>> {
622 self.with_db(|db| rename::rename(db, position, new_name))
625 pub fn prepare_rename(
627 position: FilePosition,
628 ) -> Cancellable<Result<RangeInfo<()>, RenameError>> {
629 self.with_db(|db| rename::prepare_rename(db, position))
632 pub fn will_rename_file(
636 ) -> Cancellable<Option<SourceChange>> {
637 self.with_db(|db| rename::will_rename_file(db, file_id, new_name_stem))
640 pub fn structural_search_replace(
644 resolve_context: FilePosition,
645 selections: Vec<FileRange>,
646 ) -> Cancellable<Result<SourceChange, SsrError>> {
648 let rule: ide_ssr::SsrRule = query.parse()?;
649 let mut match_finder =
650 ide_ssr::MatchFinder::in_context(db, resolve_context, selections)?;
651 match_finder.add_rule(rule)?;
652 let edits = if parse_only { Default::default() } else { match_finder.edits() };
653 Ok(SourceChange::from(edits))
659 config: &AnnotationConfig,
661 ) -> Cancellable<Vec<Annotation>> {
662 self.with_db(|db| annotations::annotations(db, config, file_id))
665 pub fn resolve_annotation(&self, annotation: Annotation) -> Cancellable<Annotation> {
666 self.with_db(|db| annotations::resolve_annotation(db, annotation))
672 direction: Direction,
673 ) -> Cancellable<Option<TextEdit>> {
674 self.with_db(|db| move_item::move_item(db, range, direction))
677 /// Performs an operation on the database that may be canceled.
679 /// rust-analyzer needs to be able to answer semantic questions about the
680 /// code while the code is being modified. A common problem is that a
681 /// long-running query is being calculated when a new change arrives.
683 /// We can't just apply the change immediately: this will cause the pending
684 /// query to see inconsistent state (it will observe an absence of
685 /// repeatable read). So what we do is we **cancel** all pending queries
686 /// before applying the change.
688 /// Salsa implements cancellation by unwinding with a special value and
689 /// catching it on the API boundary.
690 fn with_db<F, T>(&self, f: F) -> Cancellable<T>
692 F: FnOnce(&RootDatabase) -> T + std::panic::UnwindSafe,
694 Cancelled::catch(|| f(&self.db))
699 fn analysis_is_send() {
700 fn is_send<T: Send>() {}
701 is_send::<Analysis>();