1 //! Structural Search Replace
3 //! Allows searching the AST for code that matches one or more patterns and then replacing that code
4 //! based on a template.
6 // Feature: Structural Search and Replace
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.
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.
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`.
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.
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.
32 // Placeholders may be given constraints by writing them as `${<name>:<constraint1>:<constraint2>...}`.
34 // Supported constraints:
37 // | Constraint | Restricts placeholder
39 // | kind(literal) | Is a literal (e.g. `42` or `"forty two"`)
40 // | not(a) | Negates the constraint `a`
43 // Available via the command `rust-analyzer.ssr`.
46 // // Using structural search replace command [foo($a, $b) ==>> ($a).foo($b)]
49 // String::from(foo(y + 5, z))
52 // String::from((y + 5).foo(z))
56 // | Editor | Action Name
58 // | VS Code | **Rust Analyzer: Structural Search Replace**
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.
66 // // Place the cursor on the line below to see the assist 💡.
67 // // foo($a, $b) ==>> ($a).foo($b)
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;
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;
95 // A structured search replace rule. Create by calling `parse` on a str.
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>,
106 pub struct SsrPattern {
107 parsed_rules: Vec<parsing::ParsedRule>,
110 #[derive(Debug, Default)]
111 pub struct SsrMatches {
112 pub matches: Vec<Match>,
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>,
124 impl<'db> MatchFinder<'db> {
125 /// Constructs a new instance where names will be looked up as if they appeared at
126 /// `lookup_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 })
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())
146 MatchFinder::in_context(
148 FilePosition { file_id: first_file_id, offset: 0.into() },
152 bail!("No files to search");
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
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(
163 &self.resolution_scope,
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 {
176 .entry(m.range.file_id)
177 .or_insert_with(SsrMatches::default)
183 .map(|(file_id, matches)| {
186 replacing::matches_to_edit(
188 &self.sema.db.file_text(file_id),
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(
202 &self.resolution_scope,
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);
216 nester::nest_and_remove_collisions(matches, &self.sema)
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();
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(
235 FileRange { file_id, range: TextRange::new(start.into(), end.into()) },
239 remaining_text = &remaining_text[offset + snippet.len()..];
245 fn output_debug_for_nodes_at_range(
249 restrict_range: &Option<FileRange>,
250 out: &mut Vec<MatchDebugInfo>,
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)
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
265 if rule.pattern.node.kind() != node.kind()
266 && !(ast::Expr::can_cast(rule.pattern.node.kind())
267 && ast::Expr::can_cast(node.kind()))
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()
278 pattern: rule.pattern.node.clone(),
282 } else if let Some(macro_call) = ast::MacroCall::cast(node.clone()) {
283 if let Some(expanded) = self.sema.expand(¯o_call) {
284 if let Some(tt) = macro_call.token_tree() {
285 self.output_debug_for_nodes_at_range(
288 &Some(self.sema.original_range(tt.syntax())),
294 self.output_debug_for_nodes_at_range(&node, range, restrict_range, out);
299 pub struct MatchDebugInfo {
301 /// Our search pattern parsed as an expression or item, etc
303 matched: Result<Match, MatchFailureReason>,
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)?,
314 "============ AST ===========\n\
318 writeln!(f, "========= PATTERN ==========")?;
319 writeln!(f, "{:#?}", self.pattern)?;
320 writeln!(f, "============================")?;
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);
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);
344 pub fn matched_text(&self) -> String {
345 self.matched_node.text().to_string()
349 impl std::error::Error for SsrError {}
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())