Below there is a thoroughly commented example script to illustrate the XML syntax used by the scripting engine.

XML header and DTD specification on the first lines.

Start of refactoring script content. The script name is displayed in visual controls.

You can specify exceptions, i.e. paths that will not be affected by the refactoring. Paths are absolute or relative to the project root. You can specify both files and folders. For a folder, all files in it and in all its subfolders will be skipped.

It is advised to exclude sensitive project configuration files, for example:

Actual refactoring directives are called items. There are several kinds of items, differentiated by the action they perform.

When writing a script, one must be careful not to have item collisions: situations when the same piece of text is modified by more than one item. Here are examples that illustrate all the actions currently available in DVT.

replace-in-text: perform plain textual search & replace for all the text files in the project like source files, scripts etc. Note that the search string is case sensitive.

replace-in-file-name and replace-in-dir-name: perform plain textual search & replace in the names of all files/folders within the project.

rename all occurrences of the specified element (declaration and usages).

The element-full-name uniquely identifies a SystemVerilog language element, and should be specified as follows:

Note that the newname is just the name of the element. Here are some more examples:

In the last example, outer_class is not inside any package (it's in the global scope).

Also, you can optionally specify a comment that will be inserted on the line above the occurence. If the comment contains a Task Tag (like TODO, FIXME, XXX or a custom defined one), after refactoring is completed you can use the Tasks View to inspect action items or notes automatically added by the refactoring.

add-comment: to each occurrence of the specified element. The comment will be inserted on the line above the occurrence.

You can also specify whether you want to add comments only to the element declaration or only to its usages:

For add-comment items you can specify a set of elements that shall be affected by the refactoring (instead of specifying a single element via element-full-name) using a declaration comment pattern matcher and optionally a path matcher:

You can also use the element-comment-matches-not to invert the logic of the matcher.

Both element-comment-matches and element-path-matches perform simple pattern matching, that is * for any character sequence and ? for any character.

You can use ${element-signature} in the comment, as shown in the example above: it shall be replaced with the element signature, as seen for example in tooltips.

Finally, the script closing tag.

To see a larger example, you can simply start the OVM to UVM Migration wizard and inspect the script behind it (there is an Inspect button on the right side of the first wizard page).

Tip: Right-click in the XML editor > Validate to early detect syntax problems (requires the DTD specification line in the xml header).

Tip: Use Ctrl+Space to invoke autocomplete in the XML editor for tag and attribute names (requires the DTD specification line in the xml header).