ipt rename

ipt rename allows you to rename any identifier in your source code. To use it, specify the identifier’s context and the position of the identifier, as well as the new name.

The following identifiers are supported to be renamed:

  1. Local variables inside functions, including function arguments and return parameters.

  2. Function names

  3. Constants, string constants and complex constants

  4. Structure names

  5. Fields names inside structures

Warning

ipt rename cannot rename identifier provided by Igor Pro itself or XOPs.

Currently, there is no support for renaming the following identifier:

  1. Module names

  2. Independent module names

  3. Macro names

  4. Local variables inside macros.

  5. Menu names

  6. Updating includes after renaming a file

  7. Conditional compilation symbols specified using #define and #undef

  8. Pictures

  9. Datafolder names or paths

  10. Content of datafolders

  11. Output of operations like V_flag

  12. Auto indexing variables like p inside an auto indexing context

Renaming a identifier

ipt needs to know the location of all files that might contain the requested identifier. You can specify more files, and only those containing the identifier will be updated.

One file must be specified with the --file or -f flag. This file must contain the identifier that should be renamed. The remaining files can just be listed without a flag.

The position of the identifier in --file is further described using the --line (or -l) and --column (or -c) flags. Both start their counting at 1, as in most code editors. However, Igor Pro uses a different line counting system and starts at 0. If you want to provide a position from Igor Pro, you must also specify the --igor-line-counting flag.

Note

Some code editors count special characters like tab \t as multiple characters. Igor Pro and ipt count them as a single character.

Use the --new-name or -n flag to specify the new name for the identifier. The new name should be valid for the identifier, but ipt does not verify its validity.

When executing ipt rename with the above configuration, ipt will only list all positions where the identifier was found and would be renamed. To apply all changes, you have to additionally specify the --apply-changes (or -y) flag. ipt will only update files wherein the identifier was found. Updated files are always formatted like in ipt format.

Important

It is good practice to have a backup or undo option of your code before renaming an identifier. For example git, which allows to checkout the previous version of the code.

The order of the log output of ipt rename can change between multiple runs. ipt rename is parallelized and runs in multiple threads if applicable. The order of the output is result of this.

Auto indexing variables

In Igor Pro the variables p, q, r, s, x, y, z and t have a special meaning inside auto indexing contexts.

example 1
Make/FREE=1/N=5 wv = p
print wv
// prints:
// wv[0]= {0,1,2,3,4}

The user can also create variables with the same name, which creates an interesting scenario in auto indexing context: Igor Pro ignores the auto indexing variables and uses only the value which was specified before.

example 2
variable p = 100
Make/FREE=1/N=5 wv = p
print wv
// prints:
// wv[0]= {100,100,100,100,100}

The reader has to be careful if a variable with the same name was created and has to keep the special behavior in mind. This behavior is not documented in Igor Pro and might change in the future - it’s best to not rely on it.

Contrary to Igor Pros behavior ipt always treats the mentioned variable names in wave assignments as auto-indexing variables. If the user has code like in example 2 only the first p can and will be renamed and the program behavior is changed.

Examples

ìpt rename is very powerful in scenarios where an identifier is used in multiple files or multiple different identifier with the same name is contained in the same file.

Nested Structures

nested structure example
Structure Str1
    variable field
EndStructure

Structure Str2
    STRUCT Str1 field
EndStructure

Function test()
    STRUCT Str2 field
    print field.field.field
End

There are three identifiers with the name field. A simple search-and-replace algorithm will replace them all, so users must be careful and replace them one by one to avoid errors, especially in nested structures. Finding all of its uses can be quite tricky in a large code base, but ipt rename can do this easily.

ipt rename -l 11 -c 8 ...

ipt rename -l 11 -c 14 ...

ipt rename -l 11 -c 20 ...

 
Structure Str1
    variable field
EndStructure

Structure Str2
    STRUCT Str1 field
EndStructure

Function test()
    STRUCT Str2 foo
    print foo.field.field
End

Structure Str1
    variable field
EndStructure

Structure Str2
    STRUCT Str1 foo
EndStructure

Function test()
    STRUCT Str2 field
    print field.foo.field
End

Structure Str1
    variable foo
EndStructure

Structure Str2
    STRUCT Str1 field
EndStructure

Function test()
    STRUCT Str2 field
    print field.field.foo
End

As you can see only corresponding field identifier are renamed and unrelated ones are unchanged.

Limitations

  1. ipt will not rename identifier of variables, constants, structures or functions provided by Igor Pro or XOPs.

  2. Dynamically resolved names using the dollar operator cannot be renamed

  3. String content of the Execute operation will not be checked

  4. All identifier that are listed as not supported in the list above.

  5. ipt can only rename function names, constant names and structures, if their declaration is contained within the provided context.