Home ISESteroids Documentation Advanced Search & Replace
 

Advanced Search & Replace

Searching (and safely replacing) code in scripts can be challenging. Renaming variables, functions, and parameters might break your code if you don’t rename all instances and derived elements correctly. Discover ISESteroids search options, the new semantic search and the editor focus on affected elements – they all turn searching and replacing into an easy and extremely powerful experience.

Quickly Finding Functions and Regions

The navigation bar at the top of the editor pane always shows the name of the function your caret is in. Press ALT+N to toggle the navigation bar.

Navigation Bar

  1. Click the “New” icon to insert a new function body. Right-click the “New” icon to open a context menu with choices. You can insert different function snippets, or open new documents of various types, including VBScript.
  2. Shows the name of the function/configuration/workflow the caret is located in, or “(main)”. Click to drop down a list of all functions/configurations/workflows and collapsible regions.
  3. Icon is enabled when you select more than one line of code. Turns the code into a function.
  4. Icon is enabled when the caret is inside a function. Exports the function to a new or existing PowerShell module.
  5. Enter any text to highlight all instances in real-time
  6. Click to adjust search options

Navigator

When you click the function name (marked #2 in the picture above), a combobox drops down and provides you with a script inventory: it list all functions, configurations, workflows, and regions. Just click one to quickly navigate to it.

Navigator

  1. Click into Navigator. Drop-down list slides out.
  2. Currently selected entity is marked gray.
  3. Click anywhere on the list to navigate elsewhere

Note that the dropdown list uses different icons. In the screenshot, you see all collapsible regions on top, followed by functions. Workflows and configurations use differently colored icons. To change Navigator Settings, right-click into the navigator (make sure your caret is over text):

Navigator Settings

Finding Functions From References

When you right-click a command in your code that resolves to a function, right-click the command and choose “Go To Definition”. This switches focus to the function code. If the function was defined in another script or module, ISESteroids switches editor pane.

Finding References

On top of each function definition, ISESteroids shows how often this function is referenced from other parts of your code.

References to Function

If the function has just one reference, then clicking the reference overlay brings you immediately to the reference. If there are more than one reference, a reference list slides in at the bottom of the editor. Click any reference inside of it to move to the reference, or click into the editor pane to slide in the list again.

Reference List

  1. Click the reference adornment
  2. A reference list slides in. Click any reference to switch focus to that reference

Real-Time Search

If you’d quickly find a given spot in your script, enter your search phrase into the search field (marked #5 below):

Navigation Bar

While you type, ISESteroids starts to highlight all matches in your code. Press ENTER to navigate to the next instance, or SHIFT+ENTER to navigate backwards. press ESC to clear the search.

Real-Time Search

  1. Enter search phrase, or press CTRL+F to copy selection into this field. Field shows a green border when there are search results, else a red border.
  2. In real time, all instances are marked. Press ENTER / SHIFT+ENTER to navigate between them.

Press ESC to clear the search field, and remove all markings.

Semantic Variable and Function Rename

Assume you have code like this and would like to rename the variable $name inside the function Test-Something:

function Test-⁠Something
{
  param
  (
   [String]
   [Parameter(Mandatory)]
   $Name,

   [String]
   $ID = 0
  )

  Set-⁠Variable -⁠Name name -⁠Description 'Username'
  "Your name is $name and your ID is $id."
}

$Name = 'Tobias'
Test-⁠Something -⁠Name $Name

With a simple text search&replace, your code would break because this search would miss many spots where changing the variable name also affects other code.

With semantic replace, ISESteroids works different. Click the variable $name inside the function Test-Something (but do not select text). Then press F2. Here is the result:

Rename Variable

  1. Click a variable, then press F2. Semantic replace marks the variable and all affected portions of your code.
  2. All other variables with the same name in the same scope are also marked.
  3. All arguments of commands referencing the variable are also marked.
  4. All parameters affected by the rename are also marked.
  5. All variables with same name outside the scope are not marked. These are different variables that just happen to share the same name.

Simply type the replace text. As you type, all marked instances are renamed. You can also press ESC to restore the original name, or press ESC again to cancel the replace. Once the replace is applied, you can press CTRL+Z to undo the replace operation.

Safely reneming a variable or function name takes more than just a simple text seach&replace. Semantic replace is an easy yet powerful feature enabling you to refactor variable names. But it can do more.

When you click on any portion of your code and press F2 (without selecting text), you always get a semantic replace. So if you click on an operator, for example, and change casing, only operators of the same kind are marked and affected.

Advanced Search & Replace Dialog

This functionality was added in ISESteroids 2.6.3.7.

When you select text and then press F2, a Search&Replace dialog opens. Note: the dialog appears only when you have selected text. If nothing is selected when you press F2, ISESteroids uses the quick mode and performs a semantic replace.

It looks similar to this:

Advanced Search

  1. Search Term. Taken from your selection but can be adjusted (except in Semantic Mode)
  2. Search Target: select the parts of your code that are affected by this search
  3. Search Comments: when checked, searches in comments to (except in “Everywhere” mode where everything is searched anyway)
  4. Replace Term: Replace findings with this text
  5. Show only affected lines in editor view until you press ESC or start to edit code

Semantic Search

Finding (and replacing) the right things in your code is crucial, so a simple text search can wreck code easily. Instead, ISESteroids offers two types of language-based search:

  • “Only when it is…”: limits search on tokens only. Takes the token kind of the currently selected token. Not available if your selection spans more than one token type. Use this to “only replace operators” or “only replace in comments”
  • Semantic: available for a limited set of selected items, like variables, function names, parameters. Always auto-detects the replace text which is why the “Search for” group is disabled. Uses advanced logic to identify all relevant instances and necessary replacements to perform a safe replace.

Token-based- and Semantic Replace can both extent their reach into comments when you check “Search in comments, too”. For example, if you rename a function you might also want to update its comment based help, just like with parameters.

Let’s take this code for example:

function Test-⁠It
{
     <#
        .SYNOPSIS
        Describe purpose of "Test-⁠It" in 1-⁠2 sentences.

        .DESCRIPTION
        Add a more complete description of what the function does.

        .PARAMETER Name
        Describe parameter -⁠Name.

        .PARAMETER ID
        Describe parameter -⁠ID.

        .EXAMPLE
        Test-⁠It -⁠Name Value -⁠ID Value
        Describe what this call does

        .NOTES
        Place additional notes here.

        .LINK
        URLs to related sites
        The first link is opened by Get-⁠Help -⁠Online Test-⁠It

        .INPUTS
        List of input types that are accepted by this function.

        .OUTPUTS
        List of output types produced by this function.
    #>




  param
  (
   [String]
   [Parameter(Mandatory)]
   $Name,

   [int]
   $ID = 1
  )

  "You are $Name and your ID is $ID."

}

Test-⁠It -⁠Name Tobias

Now let’s assume you want to rename the function “Test-It” into “Add-User”.

Simply select “Test-It” and press F2. The dialog opens:

Semantic Search

  1. Option “Semantic Search” is preselected. Group “Search for” is disabled because Semantic Search knows already everything it needs.
  2. Check “Search in comments, too”
  3. Enter the replacement text: “Add-User”
  4. Check “Show only affected code in editor”
  5. Then click “Search”

Here is what ISESteroids selects for you:

Selected Instances

  • The search term is identified multiple times, including comments
  • The editor just shows the lines that are affected, and excludes any other line

You can now do a couple of things:

  • press ENTER to accept the replace
  • press ESC to undo the replace
  • Type text to change the replace term in real-time
  • Click one of the marked siblings to selectively undo the replace for this item.
  • Click anywhere outside a selected item to accept the replace

Note that the collapsed view (showing only affected lines) is turned off the moment you edit the code in any way. Once you start editing the code, you are brought back to normal view. You can then press POS1 (HOME) to quickly switch to the item being renamed, or press TAB to move to one of the siblings.

The settings for “Search in comments” and “Show only affected code” persist, and also apply to the search performed when you press F2 on a token without any selection (QuickSearch&Replace).

Search in Files

ISESteroids can quickly search for expressions in files and entire folder hierarchies, in case you are looking for scripts containing a certain command or phrase.

Choose “Edit/Advanced Search” (or press CTRL+SHIFT+F). The Advanced Search Addon opens:

File Search

  1. Search phrase to search for
  2. Root search location. Use command Set-Location to change current location
  3. Enable recurse search
  4. Specify semantic search and special search options like Regex support
  5. List of search results. Click to open in editor