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:
Open the Search Structurally dialog
From the main menu, select
.
Use an existing template (property declaration)
In the Structural Search dialog, click and select Existing Templates.
In the Existing Templates dialog, under the node, select All vars/vals of a class. Click OK.
Specify Kotlin as File type. This makes the search only apply to Kotlin files.
Click Find to run the search. As the result, in the Find tool window, IntelliJ IDEA shows all the properties declared in Kotlin classes.
Rerun
While in the Structural Replace dialog, click 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
In the Structural Search dialog, let's update our template to only search for open properties by adding
open
before the$Field$
variable.Click Find and check the result in the Find tool window.
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
From the main menu, select
.In the Structural Search dialog, click and select Existing Templates.
In the Existing Templates dialog, under the node, select Method calls. Click OK.
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 ofprint.*
.Place the cursor on
$Parameter$
and in the right-hand pane, add a Type filter with the value ofString
.In the Replace Template, add the replacement code:
java.util.logging.Logger.getLogger(this.javaClass.getName()).fine($Parameter$)
Check the results in the Find tool window and use the replace options to select which of the results you want to replace
We can save this template for later use if we need.
Save template
In the Structural Replace dialog, click .
In the list that opens, select Save Template.
Specify the name for the template and click OK.
The template is saved under the User Defined node in the Existing Templates dialog.
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
In the Find tool window, where you get the results for the replace pattern, click Create Inspection from Template.
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.