How to use ReplaceTargetRe

[jacobslusser]

How to use ReplaceTargetRe

[jacobslusser]

In ReplaceTargetRe your search string can include a backreference to one of the regular expression capture groups (called "tags" in Scintilla) from the previous search. This is helpful if you want your replacement string to include a portion of the matched text. For example, I use ReplaceTargetRe when I want to convert a bunch of C++ defines from the Scintilla.h header file into C# constants. Take the following text for example:

SCI_SETCARETWIDTH 2188
SCI_GETCARETWIDTH 2189
SCI_SETTARGETSTART 2190
SCI_GETTARGETSTART 2191
SCI_SETTARGETEND 2192
SCI_GETTARGETEND 2193
SCI_SETTARGETRANGE 2686
SCI_GETTARGETTEXT 2687

If I wanted to convert these to C# constants I would need to prefix each line with public const int, insert an = (equals) character between the variable and value, and finish off the line with a ; (semicolon). Said another way, what we want to do is search for "<variable> <value>" and replace it with "public const int <variable> = <value>;". That would be impossible to do with simple string replacement because the variable names and values are different for each match. But with a clever regular expression and the ReplaceTargetRe method it's quite easy. Here's how:

scintilla.TargetWholeDocument();
scintilla.SearchFlags = (SearchFlags.Regex | SearchFlags.Posix);

while (scintilla.SearchInTarget(@"([_A-Z]+)[ ]+([0-9]+)") >= 0)
{
    scintilla.ReplaceTargetRe(@"public const int \1 = \2;");
    scintilla.SetTargetRange(scintilla.TargetEnd, scintilla.TextLength);
}

My regular expression looks for any '_' (underscore) and 'A-Z' characters to find the variable name, then one or more ' ' (space) characters, followed by one or more '0-9' characters. Surrounding the sequences that match the variable name and value I've placed parentheses. These are called capture groups and/or backreferences in most Regex flavors and tags in Scintilla. I use all the terms interchangeably. Counting in regular expressions start with 1. So the first group, the variable name is backreference 1. The second group, the value, is backreference 2. etc...

By using the macro values \1 and \2 in my replace pattern I'm telling Scintilla to substitute what it finds for ([_A-Z]+) and ([0-9]+), respectively, into the replacement string. The result is that for each search/replace, the pattern "public const int \1 = \2;" will be expanded to:

public const int SCI_SETCARETWIDTH = 2188;
public const int SCI_GETCARETWIDTH = 2189;
public const int SCI_SETTARGETSTART = 2190;
public const int SCI_GETTARGETSTART = 2191;
public const int SCI_SETTARGETEND = 2192;
public const int SCI_GETTARGETEND = 2193;
public const int SCI_SETTARGETRANGE = 2686;
public const int SCI_GETTARGETTEXT = 2687;

The GetTag method is a companion to ReplaceTargetRe and allows you to get the text of each matched capture group if you wanted to manually construct the replacement string. For example, the same code above could be written like this using ReplaceTarget and GetTag:

scintilla.TargetWholeDocument();
scintilla.SearchFlags = (SearchFlags.Regex | SearchFlags.Posix);

while (scintilla.SearchInTarget(@"([_A-Z]+)[ ]+([0-9]+)") >= 0)
{
    scintilla.ReplaceTarget(@"public const int " + scintilla.GetTag(1) + " = " + scintilla.GetTag(2) + ";");
    scintilla.SetTargetRange(scintilla.TargetEnd, scintilla.TextLength);
}

Doing this obviously allows you greater control over the replacement string. I could, for example, change it to scintilla.GetTag(1).ToLower() if I wanted to change all the variable names to lowercase. That isn't possible in the automatic process used by ReplaceTargetRe but is if you wanted to construct your own replacement string with GetTag.

P.S. I bet you'll never look at the Replace dialog in Notepad++ the same way again. ;)

[theryan722]

Not only have you answered my question, you also explained it extremely well and in depth. My oh my is this repository the jackpot. Thank you for everything.