crates/ide_ssr/src/lib.rs

   1 //! Structural Search Replace
   2 //!
   3 //! Allows searching the AST for code that matches one or more patterns and then replacing that code
   4 //! based on a template.
   5
   6 // Feature: Structural Search and Replace
   7 //
   8 // Search and replace with named wildcards that will match any expression, type, path, pattern or item.
   9 // The syntax for a structural search replace command is `<search_pattern> ==>> <replace_pattern>`.
  10 // A `$<name>` placeholder in the search pattern will match any AST node and `$<name>` will reference it in the replacement.
  11 // Within a macro call, a placeholder will match up until whatever token follows the placeholder.
  12 //
  13 // All paths in both the search pattern and the replacement template must resolve in the context
  14 // in which this command is invoked. Paths in the search pattern will then match the code if they
  15 // resolve to the same item, even if they're written differently. For example if we invoke the
  16 // command in the module `foo` with a pattern of `Bar`, then code in the parent module that refers
  17 // to `foo::Bar` will match.
  18 //
  19 // Paths in the replacement template will be rendered appropriately for the context in which the
  20 // replacement occurs. For example if our replacement template is `foo::Bar` and we match some
  21 // code in the `foo` module, we'll insert just `Bar`.
  22 //
  23 // Inherent method calls should generally be written in UFCS form. e.g. `foo::Bar::baz($s, $a)` will
  24 // match `$s.baz($a)`, provided the method call `baz` resolves to the method `foo::Bar::baz`. When a
  25 // placeholder is the receiver of a method call in the search pattern (e.g. `$s.foo()`), but not in
  26 // the replacement template (e.g. `bar($s)`), then *, & and &mut will be added as needed to mirror
  27 // whatever autoderef and autoref was happening implicitly in the matched code.
  28 //
  29 // The scope of the search / replace will be restricted to the current selection if any, otherwise
  30 // it will apply to the whole workspace.
  31 //
  32 // Placeholders may be given constraints by writing them as `${<name>:<constraint1>:<constraint2>...}`.
  33 //
  34 // Supported constraints:
  35 //
  36 // |===
  37 // | Constraint    | Restricts placeholder
  38 //
  39 // | kind(literal) | Is a literal (e.g. `42` or `"forty two"`)
  40 // | not(a)        | Negates the constraint `a`
  41 // |===
  42 //
  43 // Available via the command `rust-analyzer.ssr`.
  44 //
  45 // ```rust
  46 // // Using structural search replace command [foo($a, $b) ==>> ($a).foo($b)]
  47 //
  48 // // BEFORE
  49 // String::from(foo(y + 5, z))
  50 //
  51 // // AFTER
  52 // String::from((y + 5).foo(z))
  53 // ```
  54 //
  55 // |===
  56 // | Editor  | Action Name
  57 //
  58 // | VS Code | **Rust Analyzer: Structural Search Replace**
  59 // |===
  60 //
  61 // Also available as an assist, by writing a comment containing the structural
  62 // search and replace rule. You will only see the assist if the comment can
  63 // be parsed as a valid structural search and replace rule.
  64 //
  65 // ```rust
  66 // // Place the cursor on the line below to see the assist 💡.
  67 // // foo($a, $b) ==>> ($a).foo($b)
  68 // ```
  69
  70 mod from_comment;
  71 mod matching;
  72 mod nester;
  73 mod parsing;
  74 mod fragments;
  75 mod replacing;
  76 mod resolving;
  77 mod search;
  78 #[macro_use]
  79 mod errors;
  80 #[cfg(test)]
  81 mod tests;
  82
  83 use crate::errors::bail;
  84 pub use crate::errors::SsrError;
  85 pub use crate::from_comment::ssr_from_comment;
  86 pub use crate::matching::Match;
  87 use crate::matching::MatchFailureReason;
  88 use hir::Semantics;
  89 use ide_db::base_db::{FileId, FilePosition, FileRange};
  90 use resolving::ResolvedRule;
  91 use rustc_hash::FxHashMap;
  92 use syntax::{ast, AstNode, SyntaxNode, TextRange};
  93 use text_edit::TextEdit;
  94
  95 // A structured search replace rule. Create by calling `parse` on a str.
  96 #[derive(Debug)]
  97 pub struct SsrRule {
  98     /// A structured pattern that we're searching for.
  99     pattern: parsing::RawPattern,
 100     /// What we'll replace it with.
 101     template: parsing::RawPattern,
 102     parsed_rules: Vec<parsing::ParsedRule>,
 103 }
 104
 105 #[derive(Debug)]
 106 pub struct SsrPattern {
 107     parsed_rules: Vec<parsing::ParsedRule>,
 108 }
 109
 110 #[derive(Debug, Default)]
 111 pub struct SsrMatches {
 112     pub matches: Vec<Match>,
 113 }
 114
 115 /// Searches a crate for pattern matches and possibly replaces them with something else.
 116 pub struct MatchFinder<'db> {
 117     /// Our source of information about the user's code.
 118     sema: Semantics<'db, ide_db::RootDatabase>,
 119     rules: Vec<ResolvedRule>,
 120     resolution_scope: resolving::ResolutionScope<'db>,
 121     restrict_ranges: Vec<FileRange>,
 122 }
 123
 124 impl<'db> MatchFinder<'db> {
 125     /// Constructs a new instance where names will be looked up as if they appeared at
 126     /// `lookup_context`.
 127     pub fn in_context(
 128         db: &'db ide_db::RootDatabase,
 129         lookup_context: FilePosition,
 130         mut restrict_ranges: Vec<FileRange>,
 131     ) -> Result<MatchFinder<'db>, SsrError> {
 132         restrict_ranges.retain(|range| !range.range.is_empty());
 133         let sema = Semantics::new(db);
 134         let resolution_scope = resolving::ResolutionScope::new(&sema, lookup_context)
 135             .ok_or_else(|| SsrError("no resolution scope for file".into()))?;
 136         Ok(MatchFinder { sema, rules: Vec::new(), resolution_scope, restrict_ranges })
 137     }
 138
 139     /// Constructs an instance using the start of the first file in `db` as the lookup context.
 140     pub fn at_first_file(db: &'db ide_db::RootDatabase) -> Result<MatchFinder<'db>, SsrError> {
 141         use ide_db::base_db::SourceDatabaseExt;
 142         use ide_db::symbol_index::SymbolsDatabase;
 143         if let Some(first_file_id) =
 144             db.local_roots().iter().next().and_then(|root| db.source_root(*root).iter().next())
 145         {
 146             MatchFinder::in_context(
 147                 db,
 148                 FilePosition { file_id: first_file_id, offset: 0.into() },
 149                 vec![],
 150             )
 151         } else {
 152             bail!("No files to search");
 153         }
 154     }
 155
 156     /// Adds a rule to be applied. The order in which rules are added matters. Earlier rules take
 157     /// precedence. If a node is matched by an earlier rule, then later rules won't be permitted to
 158     /// match to it.
 159     pub fn add_rule(&mut self, rule: SsrRule) -> Result<(), SsrError> {
 160         for parsed_rule in rule.parsed_rules {
 161             self.rules.push(ResolvedRule::new(
 162                 parsed_rule,
 163                 &self.resolution_scope,
 164                 self.rules.len(),
 165             )?);
 166         }
 167         Ok(())
 168     }
 169
 170     /// Finds matches for all added rules and returns edits for all found matches.
 171     pub fn edits(&self) -> FxHashMap<FileId, TextEdit> {
 172         use ide_db::base_db::SourceDatabaseExt;
 173         let mut matches_by_file = FxHashMap::default();
 174         for m in self.matches().matches {
 175             matches_by_file
 176                 .entry(m.range.file_id)
 177                 .or_insert_with(SsrMatches::default)
 178                 .matches
 179                 .push(m);
 180         }
 181         matches_by_file
 182             .into_iter()
 183             .map(|(file_id, matches)| {
 184                 (
 185                     file_id,
 186                     replacing::matches_to_edit(
 187                         &matches,
 188                         &self.sema.db.file_text(file_id),
 189                         &self.rules,
 190                     ),
 191                 )
 192             })
 193             .collect()
 194     }
 195
 196     /// Adds a search pattern. For use if you intend to only call `find_matches_in_file`. If you
 197     /// intend to do replacement, use `add_rule` instead.
 198     pub fn add_search_pattern(&mut self, pattern: SsrPattern) -> Result<(), SsrError> {
 199         for parsed_rule in pattern.parsed_rules {
 200             self.rules.push(ResolvedRule::new(
 201                 parsed_rule,
 202                 &self.resolution_scope,
 203                 self.rules.len(),
 204             )?);
 205         }
 206         Ok(())
 207     }
 208
 209     /// Returns matches for all added rules.
 210     pub fn matches(&self) -> SsrMatches {
 211         let mut matches = Vec::new();
 212         let mut usage_cache = search::UsageCache::default();
 213         for rule in &self.rules {
 214             self.find_matches_for_rule(rule, &mut usage_cache, &mut matches);
 215         }
 216         nester::nest_and_remove_collisions(matches, &self.sema)
 217     }
 218
 219     /// Finds all nodes in `file_id` whose text is exactly equal to `snippet` and attempts to match
 220     /// them, while recording reasons why they don't match. This API is useful for command
 221     /// line-based debugging where providing a range is difficult.
 222     pub fn debug_where_text_equal(&self, file_id: FileId, snippet: &str) -> Vec<MatchDebugInfo> {
 223         use ide_db::base_db::SourceDatabaseExt;
 224         let file = self.sema.parse(file_id);
 225         let mut res = Vec::new();
 226         let file_text = self.sema.db.file_text(file_id);
 227         let mut remaining_text = file_text.as_str();
 228         let mut base = 0;
 229         let len = snippet.len() as u32;
 230         while let Some(offset) = remaining_text.find(snippet) {
 231             let start = base + offset as u32;
 232             let end = start + len;
 233             self.output_debug_for_nodes_at_range(
 234                 file.syntax(),
 235                 FileRange { file_id, range: TextRange::new(start.into(), end.into()) },
 236                 &None,
 237                 &mut res,
 238             );
 239             remaining_text = &remaining_text[offset + snippet.len()..];
 240             base = end;
 241         }
 242         res
 243     }
 244
 245     fn output_debug_for_nodes_at_range(
 246         &self,
 247         node: &SyntaxNode,
 248         range: FileRange,
 249         restrict_range: &Option<FileRange>,
 250         out: &mut Vec<MatchDebugInfo>,
 251     ) {
 252         for node in node.children() {
 253             let node_range = self.sema.original_range(&node);
 254             if node_range.file_id != range.file_id || !node_range.range.contains_range(range.range)
 255             {
 256                 continue;
 257             }
 258             if node_range.range == range.range {
 259                 for rule in &self.rules {
 260                     // For now we ignore rules that have a different kind than our node, otherwise
 261                     // we get lots of noise. If at some point we add support for restricting rules
 262                     // to a particular kind of thing (e.g. only match type references), then we can
 263                     // relax this. We special-case expressions, since function calls can match
 264                     // method calls.
 265                     if rule.pattern.node.kind() != node.kind()
 266                         && !(ast::Expr::can_cast(rule.pattern.node.kind())
 267                             && ast::Expr::can_cast(node.kind()))
 268                     {
 269                         continue;
 270                     }
 271                     out.push(MatchDebugInfo {
 272                         matched: matching::get_match(true, rule, &node, restrict_range, &self.sema)
 273                             .map_err(|e| MatchFailureReason {
 274                                 reason: e.reason.unwrap_or_else(|| {
 275                                     "Match failed, but no reason was given".to_owned()
 276                                 }),
 277                             }),
 278                         pattern: rule.pattern.node.clone(),
 279                         node: node.clone(),
 280                     });
 281                 }
 282             } else if let Some(macro_call) = ast::MacroCall::cast(node.clone()) {
 283                 if let Some(expanded) = self.sema.expand(&macro_call) {
 284                     if let Some(tt) = macro_call.token_tree() {
 285                         self.output_debug_for_nodes_at_range(
 286                             &expanded,
 287                             range,
 288                             &Some(self.sema.original_range(tt.syntax())),
 289                             out,
 290                         );
 291                     }
 292                 }
 293             }
 294             self.output_debug_for_nodes_at_range(&node, range, restrict_range, out);
 295         }
 296     }
 297 }
 298
 299 pub struct MatchDebugInfo {
 300     node: SyntaxNode,
 301     /// Our search pattern parsed as an expression or item, etc
 302     pattern: SyntaxNode,
 303     matched: Result<Match, MatchFailureReason>,
 304 }
 305
 306 impl std::fmt::Debug for MatchDebugInfo {
 307     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
 308         match &self.matched {
 309             Ok(_) => writeln!(f, "Node matched")?,
 310             Err(reason) => writeln!(f, "Node failed to match because: {}", reason.reason)?,
 311         }
 312         writeln!(
 313             f,
 314             "============ AST ===========\n\
 315             {:#?}",
 316             self.node
 317         )?;
 318         writeln!(f, "========= PATTERN ==========")?;
 319         writeln!(f, "{:#?}", self.pattern)?;
 320         writeln!(f, "============================")?;
 321         Ok(())
 322     }
 323 }
 324
 325 impl SsrMatches {
 326     /// Returns `self` with any nested matches removed and made into top-level matches.
 327     pub fn flattened(self) -> SsrMatches {
 328         let mut out = SsrMatches::default();
 329         self.flatten_into(&mut out);
 330         out
 331     }
 332
 333     fn flatten_into(self, out: &mut SsrMatches) {
 334         for mut m in self.matches {
 335             for p in m.placeholder_values.values_mut() {
 336                 std::mem::take(&mut p.inner_matches).flatten_into(out);
 337             }
 338             out.matches.push(m);
 339         }
 340     }
 341 }
 342
 343 impl Match {
 344     pub fn matched_text(&self) -> String {
 345         self.matched_node.text().to_string()
 346     }
 347 }
 348
 349 impl std::error::Error for SsrError {}
 350
 351 #[cfg(test)]
 352 impl MatchDebugInfo {
 353     pub(crate) fn match_failure_reason(&self) -> Option<&str> {
 354         self.matched.as_ref().err().map(|r| r.reason.as_str())
 355     }
 356 }