IntelliJ IDEA 2021.1 Help

Tutorial: Structural search and replace in Kotlin

Structural search and replace is a powerful tool that can search for a specific pattern in code and replace it in an automated way.

In this tutorial we will get acquainted with templates and filters, modify a predefined template, and then create a code inspection based on it.

The functionality covered in this tutorial is by no means the exhaustive list of what Structural search and replace can do. Our goal is to get you started. After that, you can explore various templates, filters, and options and combine them to create your own specific searches.

For the tutorial, we will use the following code:

class Point constructor(locationX: Int, locationY: Int) { val x: Int = locationX val y: Int = locationY } open class OpenClass { open val openProperty = 0 open fun display() { println("Some text") print("More text") print(0) } }

Open the Search Structurally dialog

  • From the main menu, select Edit | Find | Search Structurally.

Use an existing template (property declaration)

  1. In the Structural Search dialog, click the Tools icon and select Existing Templates.

  2. In the Existing Templates dialog, under the Kotlin | Class-based node, select All vars/vals of a class. Click OK.

    Kotlin ssr all fields
  3. Specify Kotlin as File type. This makes the search only apply to Kotlin files.

    Kotlin ssr vals vars
  4. Click Find to run the search. As the result, in the Find tool window, IntelliJ IDEA shows all the properties declared in Kotlin classes.

    Kotlin ssr vals vars result

Rerun

  • While in the Structural Replace dialog, click Icons actions search with history to browse the history of your recent searches and quickly rerun any of them.

Now, let's return to our structural search dialog to alter the predefined template a bit.

Alter a predefined template

  1. In the Structural Search dialog, let's update our template to only search for open properties by adding open before the $Field$ variable.

    Kotlin ssr all open fields
  2. Click Find and check the result in the Find tool window.

    Kotlin ssr all open fields result

As you can see, the search used the filter this time and only shows the open properties now.

With Structural Search, we can run some interesting searches. Let's choose another existing template (Method calls) as our example. Assume we're doing this search to replace all print statements with logging calls and exclude all calls that do not have a String as the argument.

Replace function calls

  1. From the main menu, select Edit | Find | Replace Structurally.

  2. In the Structural Search dialog, click the Tools icon and select Existing Templates.

  3. In the Existing Templates dialog, under the Kotlin | Expressions node, select Method calls. Click OK.

    Kotlin ssr function calls
  4. If we run the search now, we'll end up with results that include all the function calls in the code. So, we should alter our template a bit and use filters to be more specific about what we are looking for. Place the cursor on $MethodCall$ and in the right-hand pane, add a Text filter with the value of print.*.

    Kotlin ssr replace 1
  5. Place the cursor on $Parameter$ and in the right-hand pane, add a Type filter with the value of String.

    Kotlin ssr replace 2
  6. In the Replace Template, add the replacement code: java.util.logging.Logger.getLogger(this.javaClass.getName()).fine($Parameter$)

    Kotlin ssr replace 3

  7. Check the results in the Find tool window and use the replace options to select which of the results you want to replace

    Kotlin ssr replace 4

We can save this template for later use if we need.

Save template

  1. In the Structural Replace dialog, click Artwork studio icons layout editor properties tools attribute.

  2. In the list that opens, select Save Template.

  3. Specify the name for the template and click OK.

    Kotlin ssr save template 2

The template is saved under the User Defined node in the Existing Templates dialog.

Kotlin ssr save template 3

We can also use our template as an inspection, so when we come across the same code, we'll see a warning and can quickly replace the code.

Create a custom inspection

  1. In the Find tool window, where you get the results for the replace pattern, click Create Inspection from Template.

    Kotlin ssr create inspection 1
  2. In the dialog that opens, add the name for the inspection. Optionally, add a tooltip (provides a more detailed description of the problem on hovering the highlighted code) . Click OK.

The newly created inspection appears under the Structural search node on the Inspections page.

Last modified: 21 June 2021