IntelliJ IDEA 2024.1 Help

Structural search and replace

A conventional search process does not take into account the syntax and semantics of the source code. Even if you use regular expressions, IntelliJ IDEA still treats your code as a regular text. The structural search and replace (SSR) actions let you search for a particular code pattern or grammatical construct in your code considering your code structure.

IntelliJ IDEA finds and replaces fragments of source code, based on the search templates that you create and conditions you apply.

Search for a target structurally

  1. Go to Edit | Find | Search Structurally to open the Structural Search dialog.

  2. In the Structural Search dialog, do one of the following:

    • Create your own template from scratch.

      Select Draft Template from the list of templates.

      In the editor area, enter the code template ($variable$ that represents your code), in the dialog's toolbar click the Save Template button to save it for future use. You can opt to save the template as inspection as well.

      Structural Search dialog

      IntelliJ IDEA adds the created template to the existing template list (Recent node).

    • Use one of the existing templates to act as a prototype.

      In the list of available existing templates, select the needed template.

      For example, you have the following fields in your code:

      public class MainActivity { public static final String this_is_wrong = "Hello"; public static final String THIS_IS_CORRECT = "world"; }

      Let's find a certain field in the class.

      In the list of existing templates, click Java and open the Class-based node (since we need fields in the class), so the fields of the class template would be our target.

      the existing templates list

      Click Find.

      IntelliJ IDEA instantly highlights the found code occurrences in the editor.

  3. The Structural Search dialog displays the selected template and the values of the filters used in the template. You can edit the existing filters or add new conditions, for example, add some regular expressions, or a script constraint. Place the caret at the code variable and use the filter area to manage filters.

    the Edit filters
  4. As an example, let's add a condition for the $Field$ variable.

    In the filter area, click the Add button to add a new condition. If, for example, you need to add a regular expression, select Text. You can also add other conditions depending on your variable.

  5. In the field that opens, type your condition.

    For example, let's type the following regular expression:

    Add regular expression to the filter dialog

    In this case when you select the Match case checkbox in the Structural Search dialog, IntelliJ IDEA will only search for the fields with uppercase characters.

    Also note there are different additional options are available depending on the selected language.

    For example, check the following options:

    • Language: use the list to select, which file types should be a part of the search. In our case, it is Java.

    • Target: in the list of options, select what item to search for. In our case it is Field).

      Search target
    • Recursive: if this checkbox is selected, IntelliJ IDEA performs the recursive search and all nested items will be included in the results. For example, when you search for a method call, with the Recursive option enabled, IntelliJ IDEA will find nested method calls in foo(foo(foo())). With the Recursive option disabled, only the outer method call will be found.

    • Injected code: if this checkbox is selected, the injected code such as JavaScript that is injected in HTML code or SQL injected in Java will be a part of the search process.

    • Match case: if this checkbox is selected, the search result will match the case of a search target.

  6. Specify where to search: in a project, module, directory, or within a custom scope.

    Click Find.

    IntelliJ IDEA displays the results in the Find tool window.

    Find tool window results

    You can add the newly created search template to structural search inspections as a custom template by clicking Create Inspection from Template in the Find tool window and use it later to inspect your code.

Replace a target structurally

  1. In the main menu, go to Edit | Find | Replace Structurally.

  2. In the Replace Structurally dialog, add new or existing templates to the search and replace template areas. You can save the replace template the same way as the search one.

  3. If you need to add a filter for the variable in the replace template, place the caret at the variable of interest and use the filter area to manage filters.

  4. In the filter area, depending on what you chose as a filter, specify the condition.

    For example, let's take a variable $Field$ that we searched for and add a condition to replace the found template with the lowercase characters.

    Let's call our variable $Field2$ and add the following filter script which basically is a Groovy script:

    the Replace template
  5. To narrow down your replace results, select the following options:

    • Shorten fully-qualified names - replaces fully qualified class names with short names and imports.

    • Reformat - automatically formats the replaced code.

    • Use static import - uses static import in replacement when possible. For example, a method call to a static method Math.abs(i) becomes abs(i) if this option is selected.

    After specifying the necessary options, click Find. IntelliJ IDEA displays the results in the Find tool window.

  6. In the Find tool window, you can work with the results further, replacing found items one by one, or all of them at once, or previewing your potential changes.

    You can also add the replace template to the structural search inspections and use it as a quick-fix for your code.

    the Find tool window             with the Replace preview

    As a result of our replacement, the uppercase characters were switched to lowercase.

    the Replace result

Share search templates

You can share a search template with your peers by exporting or importing it.

  1. In the Structural Search dialog (Edit | Find | Search Structurally), create a new search template or use the existing one.

  2. To export a template, click the Export Template to Clipboard icon. IntelliJ IDEA adds the XML representation of the template to a clipboard (press Ctrl+Shift+V to see the clipboard's content). You can share this representation with other developers in chat, email, or a forum.

    To import a template, copy (Ctrl+C) the shared XML code from anywhere (email, chat, or a forum) and in the Structural Search dialog, click the Import Template from Clipboard icon. IntelliJ IDEA takes the XML code representation and converts it into a template including variables and a scope if it is present.

Last modified: 08 April 2024