crates/ide/src/display/navigation_target.rs

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