crates/ide/src/display/navigation_target.rs

   1 //! FIXME: write short doc here
   2
   3 use std::fmt;
   4
   5 use either::Either;
   6 use hir::{
   7     AssocItem, Documentation, FieldSource, HasAttrs, HasSource, HirDisplay, InFile, ModuleSource,
   8     Semantics,
   9 };
  10 use ide_db::{
  11     base_db::{FileId, FileRange},
  12     symbol_index::FileSymbolKind,
  13     SymbolKind,
  14 };
  15 use ide_db::{defs::Definition, RootDatabase};
  16 use syntax::{
  17     ast::{self, NameOwner},
  18     match_ast, AstNode, SmolStr, TextRange,
  19 };
  20
  21 use crate::FileSymbol;
  22
  23 /// `NavigationTarget` represents and element in the editor's UI which you can
  24 /// click on to navigate to a particular piece of code.
  25 ///
  26 /// Typically, a `NavigationTarget` corresponds to some element in the source
  27 /// code, like a function or a struct, but this is not strictly required.
  28 #[derive(Clone, PartialEq, Eq, Hash)]
  29 pub struct NavigationTarget {
  30     pub file_id: FileId,
  31     /// Range which encompasses the whole element.
  32     ///
  33     /// Should include body, doc comments, attributes, etc.
  34     ///
  35     /// Clients should use this range to answer "is the cursor inside the
  36     /// element?" question.
  37     pub full_range: TextRange,
  38     /// A "most interesting" range withing the `full_range`.
  39     ///
  40     /// Typically, `full_range` is the whole syntax node, including doc
  41     /// comments, and `focus_range` is the range of the identifier. "Most
  42     /// interesting" range within the full range, typically the range of
  43     /// identifier.
  44     ///
  45     /// Clients should place the cursor on this range when navigating to this target.
  46     pub focus_range: Option<TextRange>,
  47     pub name: SmolStr,
  48     pub kind: Option<SymbolKind>,
  49     pub container_name: Option<SmolStr>,
  50     pub description: Option<String>,
  51     pub docs: Option<Documentation>,
  52 }
  53
  54 impl fmt::Debug for NavigationTarget {
  55     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  56         let mut f = f.debug_struct("NavigationTarget");
  57         macro_rules! opt {
  58             ($($name:ident)*) => {$(
  59                 if let Some(it) = &self.$name {
  60                     f.field(stringify!($name), it);
  61                 }
  62             )*}
  63         }
  64         f.field("file_id", &self.file_id).field("full_range", &self.full_range);
  65         opt!(focus_range);
  66         f.field("name", &self.name);
  67         opt!(kind container_name description docs);
  68         f.finish()
  69     }
  70 }
  71
  72 pub(crate) trait ToNav {
  73     fn to_nav(&self, db: &RootDatabase) -> NavigationTarget;
  74 }
  75
  76 pub(crate) trait TryToNav {
  77     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget>;
  78 }
  79
  80 impl NavigationTarget {
  81     pub fn focus_or_full_range(&self) -> TextRange {
  82         self.focus_range.unwrap_or(self.full_range)
  83     }
  84
  85     pub(crate) fn from_module_to_decl(db: &RootDatabase, module: hir::Module) -> NavigationTarget {
  86         let name = module.name(db).map(|it| it.to_string().into()).unwrap_or_default();
  87         if let Some(src) = module.declaration_source(db) {
  88             let node = src.as_ref().map(|it| it.syntax());
  89             let full_range = node.original_file_range(db);
  90             let focus_range = src
  91                 .value
  92                 .name()
  93                 .map(|name| src.with_value(name.syntax()).original_file_range(db).range);
  94             let mut res = NavigationTarget::from_syntax(
  95                 full_range.file_id,
  96                 name,
  97                 focus_range,
  98                 full_range.range,
  99                 SymbolKind::Module,
 100             );
 101             res.docs = module.attrs(db).docs();
 102             res.description = Some(module.display(db).to_string());
 103             return res;
 104         }
 105         module.to_nav(db)
 106     }
 107
 108     #[cfg(test)]
 109     pub(crate) fn assert_match(&self, expected: &str) {
 110         let actual = self.debug_render();
 111         test_utils::assert_eq_text!(expected.trim(), actual.trim(),);
 112     }
 113
 114     #[cfg(test)]
 115     pub(crate) fn debug_render(&self) -> String {
 116         let mut buf = format!(
 117             "{} {:?} {:?} {:?}",
 118             self.name,
 119             self.kind.unwrap(),
 120             self.file_id,
 121             self.full_range
 122         );
 123         if let Some(focus_range) = self.focus_range {
 124             buf.push_str(&format!(" {:?}", focus_range))
 125         }
 126         if let Some(container_name) = &self.container_name {
 127             buf.push_str(&format!(" {}", container_name))
 128         }
 129         buf
 130     }
 131
 132     /// Allows `NavigationTarget` to be created from a `NameOwner`
 133     pub(crate) fn from_named(
 134         db: &RootDatabase,
 135         node: InFile<&dyn ast::NameOwner>,
 136         kind: SymbolKind,
 137     ) -> NavigationTarget {
 138         let name = node.value.name().map(|it| it.text().into()).unwrap_or_else(|| "_".into());
 139         let focus_range =
 140             node.value.name().map(|it| node.with_value(it.syntax()).original_file_range(db).range);
 141         let frange = node.map(|it| it.syntax()).original_file_range(db);
 142
 143         NavigationTarget::from_syntax(frange.file_id, name, focus_range, frange.range, kind)
 144     }
 145
 146     fn from_syntax(
 147         file_id: FileId,
 148         name: SmolStr,
 149         focus_range: Option<TextRange>,
 150         full_range: TextRange,
 151         kind: SymbolKind,
 152     ) -> NavigationTarget {
 153         NavigationTarget {
 154             file_id,
 155             name,
 156             kind: Some(kind),
 157             full_range,
 158             focus_range,
 159             container_name: None,
 160             description: None,
 161             docs: None,
 162         }
 163     }
 164 }
 165
 166 impl ToNav for FileSymbol {
 167     fn to_nav(&self, db: &RootDatabase) -> NavigationTarget {
 168         NavigationTarget {
 169             file_id: self.file_id,
 170             name: self.name.clone(),
 171             kind: Some(match self.kind {
 172                 FileSymbolKind::Function => SymbolKind::Function,
 173                 FileSymbolKind::Struct => SymbolKind::Struct,
 174                 FileSymbolKind::Enum => SymbolKind::Enum,
 175                 FileSymbolKind::Trait => SymbolKind::Trait,
 176                 FileSymbolKind::Module => SymbolKind::Module,
 177                 FileSymbolKind::TypeAlias => SymbolKind::TypeAlias,
 178                 FileSymbolKind::Const => SymbolKind::Const,
 179                 FileSymbolKind::Static => SymbolKind::Static,
 180                 FileSymbolKind::Macro => SymbolKind::Macro,
 181                 FileSymbolKind::Union => SymbolKind::Union,
 182             }),
 183             full_range: self.range,
 184             focus_range: self.name_range,
 185             container_name: self.container_name.clone(),
 186             description: description_from_symbol(db, self),
 187             docs: None,
 188         }
 189     }
 190 }
 191
 192 impl TryToNav for Definition {
 193     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 194         match self {
 195             Definition::Macro(it) => it.try_to_nav(db),
 196             Definition::Field(it) => it.try_to_nav(db),
 197             Definition::ModuleDef(it) => it.try_to_nav(db),
 198             Definition::SelfType(it) => it.try_to_nav(db),
 199             Definition::Local(it) => Some(it.to_nav(db)),
 200             Definition::GenericParam(it) => it.try_to_nav(db),
 201             Definition::Label(it) => Some(it.to_nav(db)),
 202         }
 203     }
 204 }
 205
 206 impl TryToNav for hir::ModuleDef {
 207     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 208         match self {
 209             hir::ModuleDef::Module(it) => Some(it.to_nav(db)),
 210             hir::ModuleDef::Function(it) => it.try_to_nav(db),
 211             hir::ModuleDef::Adt(it) => it.try_to_nav(db),
 212             hir::ModuleDef::Variant(it) => it.try_to_nav(db),
 213             hir::ModuleDef::Const(it) => it.try_to_nav(db),
 214             hir::ModuleDef::Static(it) => it.try_to_nav(db),
 215             hir::ModuleDef::Trait(it) => it.try_to_nav(db),
 216             hir::ModuleDef::TypeAlias(it) => it.try_to_nav(db),
 217             hir::ModuleDef::BuiltinType(_) => None,
 218         }
 219     }
 220 }
 221
 222 pub(crate) trait ToNavFromAst {
 223     const KIND: SymbolKind;
 224 }
 225 impl ToNavFromAst for hir::Function {
 226     const KIND: SymbolKind = SymbolKind::Function;
 227 }
 228 impl ToNavFromAst for hir::Const {
 229     const KIND: SymbolKind = SymbolKind::Const;
 230 }
 231 impl ToNavFromAst for hir::Static {
 232     const KIND: SymbolKind = SymbolKind::Static;
 233 }
 234 impl ToNavFromAst for hir::Struct {
 235     const KIND: SymbolKind = SymbolKind::Struct;
 236 }
 237 impl ToNavFromAst for hir::Enum {
 238     const KIND: SymbolKind = SymbolKind::Enum;
 239 }
 240 impl ToNavFromAst for hir::Variant {
 241     const KIND: SymbolKind = SymbolKind::Variant;
 242 }
 243 impl ToNavFromAst for hir::Union {
 244     const KIND: SymbolKind = SymbolKind::Union;
 245 }
 246 impl ToNavFromAst for hir::TypeAlias {
 247     const KIND: SymbolKind = SymbolKind::TypeAlias;
 248 }
 249 impl ToNavFromAst for hir::Trait {
 250     const KIND: SymbolKind = SymbolKind::Trait;
 251 }
 252
 253 impl<D> TryToNav for D
 254 where
 255     D: HasSource + ToNavFromAst + Copy + HasAttrs + HirDisplay,
 256     D::Ast: ast::NameOwner,
 257 {
 258     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 259         let src = self.source(db)?;
 260         let mut res = NavigationTarget::from_named(
 261             db,
 262             src.as_ref().map(|it| it as &dyn ast::NameOwner),
 263             D::KIND,
 264         );
 265         res.docs = self.docs(db);
 266         res.description = Some(self.display(db).to_string());
 267         Some(res)
 268     }
 269 }
 270
 271 impl ToNav for hir::Module {
 272     fn to_nav(&self, db: &RootDatabase) -> NavigationTarget {
 273         let src = self.definition_source(db);
 274         let name = self.name(db).map(|it| it.to_string().into()).unwrap_or_default();
 275         let (syntax, focus) = match &src.value {
 276             ModuleSource::SourceFile(node) => (node.syntax(), None),
 277             ModuleSource::Module(node) => {
 278                 (node.syntax(), node.name().map(|it| it.syntax().text_range()))
 279             }
 280             ModuleSource::BlockExpr(node) => (node.syntax(), None),
 281         };
 282         let frange = src.with_value(syntax).original_file_range(db);
 283         NavigationTarget::from_syntax(frange.file_id, name, focus, frange.range, SymbolKind::Module)
 284     }
 285 }
 286
 287 impl TryToNav for hir::Impl {
 288     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 289         let src = self.source(db)?;
 290         let derive_attr = self.is_builtin_derive(db);
 291         let frange = if let Some(item) = &derive_attr {
 292             item.syntax().original_file_range(db)
 293         } else {
 294             src.as_ref().map(|it| it.syntax()).original_file_range(db)
 295         };
 296         let focus_range = if derive_attr.is_some() {
 297             None
 298         } else {
 299             src.value.self_ty().map(|ty| src.with_value(ty.syntax()).original_file_range(db).range)
 300         };
 301
 302         Some(NavigationTarget::from_syntax(
 303             frange.file_id,
 304             "impl".into(),
 305             focus_range,
 306             frange.range,
 307             SymbolKind::Impl,
 308         ))
 309     }
 310 }
 311
 312 impl TryToNav for hir::Field {
 313     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 314         let src = self.source(db)?;
 315
 316         let field_source = match &src.value {
 317             FieldSource::Named(it) => {
 318                 let mut res =
 319                     NavigationTarget::from_named(db, src.with_value(it), SymbolKind::Field);
 320                 res.docs = self.docs(db);
 321                 res.description = Some(self.display(db).to_string());
 322                 res
 323             }
 324             FieldSource::Pos(it) => {
 325                 let frange = src.with_value(it.syntax()).original_file_range(db);
 326                 NavigationTarget::from_syntax(
 327                     frange.file_id,
 328                     "".into(),
 329                     None,
 330                     frange.range,
 331                     SymbolKind::Field,
 332                 )
 333             }
 334         };
 335         Some(field_source)
 336     }
 337 }
 338
 339 impl TryToNav for hir::MacroDef {
 340     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 341         let src = self.source(db)?;
 342         let name_owner: &dyn ast::NameOwner = match &src.value {
 343             Either::Left(it) => it,
 344             Either::Right(it) => it,
 345         };
 346         log::debug!("nav target {:#?}", name_owner.syntax());
 347         let mut res = NavigationTarget::from_named(
 348             db,
 349             src.as_ref().with_value(name_owner),
 350             SymbolKind::Macro,
 351         );
 352         res.docs = self.docs(db);
 353         Some(res)
 354     }
 355 }
 356
 357 impl TryToNav for hir::Adt {
 358     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 359         match self {
 360             hir::Adt::Struct(it) => it.try_to_nav(db),
 361             hir::Adt::Union(it) => it.try_to_nav(db),
 362             hir::Adt::Enum(it) => it.try_to_nav(db),
 363         }
 364     }
 365 }
 366
 367 impl TryToNav for hir::AssocItem {
 368     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 369         match self {
 370             AssocItem::Function(it) => it.try_to_nav(db),
 371             AssocItem::Const(it) => it.try_to_nav(db),
 372             AssocItem::TypeAlias(it) => it.try_to_nav(db),
 373         }
 374     }
 375 }
 376
 377 impl TryToNav for hir::GenericParam {
 378     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 379         match self {
 380             hir::GenericParam::TypeParam(it) => it.try_to_nav(db),
 381             hir::GenericParam::ConstParam(it) => it.try_to_nav(db),
 382             hir::GenericParam::LifetimeParam(it) => it.try_to_nav(db),
 383         }
 384     }
 385 }
 386
 387 impl ToNav for hir::Local {
 388     fn to_nav(&self, db: &RootDatabase) -> NavigationTarget {
 389         let src = self.source(db);
 390         let (node, name) = match &src.value {
 391             Either::Left(bind_pat) => (bind_pat.syntax().clone(), bind_pat.name()),
 392             Either::Right(it) => (it.syntax().clone(), it.name()),
 393         };
 394         let focus_range =
 395             name.map(|it| src.with_value(&it.syntax().clone()).original_file_range(db).range);
 396
 397         let full_range = src.with_value(&node).original_file_range(db);
 398         let name = match self.name(db) {
 399             Some(it) => it.to_string().into(),
 400             None => "".into(),
 401         };
 402         let kind = if self.is_self(db) {
 403             SymbolKind::SelfParam
 404         } else if self.is_param(db) {
 405             SymbolKind::ValueParam
 406         } else {
 407             SymbolKind::Local
 408         };
 409         NavigationTarget {
 410             file_id: full_range.file_id,
 411             name,
 412             kind: Some(kind),
 413             full_range: full_range.range,
 414             focus_range,
 415             container_name: None,
 416             description: None,
 417             docs: None,
 418         }
 419     }
 420 }
 421
 422 impl ToNav for hir::Label {
 423     fn to_nav(&self, db: &RootDatabase) -> NavigationTarget {
 424         let src = self.source(db);
 425         let node = src.value.syntax();
 426         let FileRange { file_id, range } = src.with_value(node).original_file_range(db);
 427         let focus_range =
 428             src.value.lifetime().and_then(|lt| lt.lifetime_ident_token()).map(|lt| lt.text_range());
 429         let name = self.name(db).to_string().into();
 430         NavigationTarget {
 431             file_id,
 432             name,
 433             kind: Some(SymbolKind::Label),
 434             full_range: range,
 435             focus_range,
 436             container_name: None,
 437             description: None,
 438             docs: None,
 439         }
 440     }
 441 }
 442
 443 impl TryToNav for hir::TypeParam {
 444     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 445         let src = self.source(db)?;
 446         let full_range = match &src.value {
 447             Either::Left(it) => it
 448                 .name()
 449                 .map_or_else(|| it.syntax().text_range(), |name| name.syntax().text_range()),
 450             Either::Right(it) => it.syntax().text_range(),
 451         };
 452         let focus_range = match &src.value {
 453             Either::Left(it) => it.name(),
 454             Either::Right(it) => it.name(),
 455         }
 456         .map(|it| it.syntax().text_range());
 457         Some(NavigationTarget {
 458             file_id: src.file_id.original_file(db),
 459             name: self.name(db).to_string().into(),
 460             kind: Some(SymbolKind::TypeParam),
 461             full_range,
 462             focus_range,
 463             container_name: None,
 464             description: None,
 465             docs: None,
 466         })
 467     }
 468 }
 469
 470 impl TryToNav for hir::LifetimeParam {
 471     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 472         let src = self.source(db)?;
 473         let full_range = src.value.syntax().text_range();
 474         Some(NavigationTarget {
 475             file_id: src.file_id.original_file(db),
 476             name: self.name(db).to_string().into(),
 477             kind: Some(SymbolKind::LifetimeParam),
 478             full_range,
 479             focus_range: Some(full_range),
 480             container_name: None,
 481             description: None,
 482             docs: None,
 483         })
 484     }
 485 }
 486
 487 impl TryToNav for hir::ConstParam {
 488     fn try_to_nav(&self, db: &RootDatabase) -> Option<NavigationTarget> {
 489         let src = self.source(db)?;
 490         let full_range = src.value.syntax().text_range();
 491         Some(NavigationTarget {
 492             file_id: src.file_id.original_file(db),
 493             name: self.name(db).to_string().into(),
 494             kind: Some(SymbolKind::ConstParam),
 495             full_range,
 496             focus_range: src.value.name().map(|n| n.syntax().text_range()),
 497             container_name: None,
 498             description: None,
 499             docs: None,
 500         })
 501     }
 502 }
 503
 504 /// Get a description of a symbol.
 505 ///
 506 /// e.g. `struct Name`, `enum Name`, `fn Name`
 507 pub(crate) fn description_from_symbol(db: &RootDatabase, symbol: &FileSymbol) -> Option<String> {
 508     let sema = Semantics::new(db);
 509     let parse = sema.parse(symbol.file_id);
 510     let node = symbol.ptr.to_node(parse.syntax());
 511
 512     match_ast! {
 513         match node {
 514             ast::Fn(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 515             ast::Struct(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 516             ast::Enum(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 517             ast::Trait(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 518             ast::Module(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 519             ast::TypeAlias(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 520             ast::Const(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 521             ast::Static(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 522             ast::RecordField(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 523             ast::Variant(it) => sema.to_def(&it).map(|it| it.display(db).to_string()),
 524             _ => None,
 525         }
 526     }
 527 }
 528
 529 #[cfg(test)]
 530 mod tests {
 531     use expect_test::expect;
 532
 533     use crate::{fixture, Query};
 534
 535     #[test]
 536     fn test_nav_for_symbol() {
 537         let (analysis, _) = fixture::file(
 538             r#"
 539 enum FooInner { }
 540 fn foo() { enum FooInner { } }
 541 "#,
 542         );
 543
 544         let navs = analysis.symbol_search(Query::new("FooInner".to_string())).unwrap();
 545         expect![[r#"
 546             [
 547                 NavigationTarget {
 548                     file_id: FileId(
 549                         0,
 550                     ),
 551                     full_range: 0..17,
 552                     focus_range: 5..13,
 553                     name: "FooInner",
 554                     kind: Enum,
 555                     description: "enum FooInner",
 556                 },
 557                 NavigationTarget {
 558                     file_id: FileId(
 559                         0,
 560                     ),
 561                     full_range: 29..46,
 562                     focus_range: 34..42,
 563                     name: "FooInner",
 564                     kind: Enum,
 565                     container_name: "foo",
 566                     description: "enum FooInner",
 567                 },
 568             ]
 569         "#]]
 570         .assert_debug_eq(&navs);
 571     }
 572
 573     #[test]
 574     fn test_world_symbols_are_case_sensitive() {
 575         let (analysis, _) = fixture::file(
 576             r#"
 577 fn foo() {}
 578 struct Foo;
 579 "#,
 580         );
 581
 582         let navs = analysis.symbol_search(Query::new("foo".to_string())).unwrap();
 583         assert_eq!(navs.len(), 2)
 584     }
 585 }