1. Change of name of deprecated functions: level easy

Firstly, we list the deprecated API found in Aqua btn.
Then, in the second line, we align the parameters of the modern function of replacement found in PDB.


Notepad++ menu "Search" > "Replace..."
Find what: copy and paste the name of the deprecated function without parameters
Replace with: copy and paste the name of the modern function without parameters

We call this basic replacement a rule of rewriting.

Be sure to process the longest functions before any short functions.
For example: replace "gimp-image-lower-layer-to-bottom" before "gimp-image-lower-layer" that begins with the same tokens.

2. Insert a new parameter: level average

This article is a short introduction of so called "regular expression" to capture symbolically tokens inside a string.
Consider the couple of deprecated/modern functions:

The parent parameter has been added in the modern function between layer and position.

Notepad++ menu "Search" > "Replace..."

[x] Regular expression check this option that changes the semantic of letter preceded with backslash.

The rule of rewriting becomes:
Find what:

Replace with:

In Find what:
"\s" captures one white-space
"\s+" captures one white-space or more

"\w+" captures one or more letter or number that is to say a word. Minus "-" will be processed soon.
In our case, the first "\w+" captures the first parameter for example "image" or often "img" in Aqua btn.
So the second "\w+" captures the second parameter corresponding to "layer".

We build our first group between parenthesis: "(\w+\s+\w+)" to capture both "image" + "layer"
because we wish to insert a new parameter called parent after this group.
Its meaning is the first parameter image + one or more white-space + the second parameter layer.

The idea is that we can symbolically reuse this group in the "Replace with" input area.
The name of the first group --that is to say the first expression between parenthesis-- is automatically named "\1".

Hence the 'Replace with' input string that includes:

• the modern function gimp-image-insert-layer;
• a single space before the first parameter;
• our first group code-named "\1" containing both the first parameter and the second parameter;
• "0" which is the compatible parent since we do not need to create any group of layers.

With PDB, consult the help of the modern function for more information about the new parameter parent.

Take in consideration that we do not process the last parameter "position"
because it does not change of position relatively to the new parameter "parent".

3. Minus-in-the-name-of-Scheme variable: level average++

In Scheme, minus "-" is both:

• the operator of subtraction
• an acceptable character in the name of a parameter.

The entire Gimp API uses minus as separator.

It is also true for the parameters. For example, the Aqua btn variable "acopy-mask" include minus inside its name.
The only problem is that the regular expression "\w+" captures only the first part "acopy" of the name before minus.

To be compatible with the Scheme syntax of variable, we need to add minus in the definition of a element of word.
To do that, we search the definition of "\w" as an interval of regular expressions: "[_\d\l\u]"
with:

• "_" underscore is valid character of variable
• "\d" standing for digit
• "\l" standing for lower letter
• "\u" standing for upper letter

In addition of underscore "_", we add in the interval the minus "-" character.
However minus "-" is also a specific operator to define an interval between characters. For example "[0-9]" captures a digit.
That is why, we need to use a backslash before minus.

So the rule of rewriting becomes more complex:
Find what:

Replace with:


Before running this rule of rewriting in Notepad++,
try to only find the deprecated function with the group of its two first --full-- parameters as an exercice to validate the improved regular expression.

4. Move parameter: level difficult

Let us progress in the Notepad++ regular expressions to replace more complex deprecated functions.

In the deprecated function gimp-ellipse-select, the 6th parameter operation is moved after image.

Not only operation is moved before its actual position
but the three last parameters antialias, feather and feather-radius disappear in the modern function.

In Aqua btn, a real example could be moving the operation "CHANNEL-OP-REPLACE" just after "img":

To capture all constants beginning with "CHANNEL", the regular expression starts with:

Since the multiple joker ".*" matches everything such as CHANNEL-OP-REPLACE but also CHANNEL-OP-SUBTRACT, etc.,
it is usual to indicate a separator after the constant to indicate the end of the constant.
We already know the separator "\s+" capturing at least one white-space or more.

The regular expression to capture the entire constant and its next separator becomes:


Hereafter enclosed is the "simplified" rule of rewriting using "\w+" without minus in the name of parameter:

Notepad++ menu "Search" > "Replace..."
[x] Regular expression

Find what:


Replace with:

We have three groups and the third group "\3" has been moved between the two first groups "\1" and "\2".

4.1 Scope of the capture of the multiple joker ".*"

The second group is delimited between two separators:

This regular expression (regex) could be interpreted as capturing " xscale40 " that is to say the first parameter.
However this regular expression is greedy or gluttonous.
It captures the maximum possible of input until the supplied constant "(CHANNEL.*)\s+".
That is why group2 captures " xscale40 yscale40 radius4 radius4 ".

Always before replacing, test your regex-based searching until you reach exactly the wished capture.

The third group code-named operation that is to say "(CHANNEL.*)" will be inserted between the two first groups.

Please, pay attention that the rewriting rule takes in consideration --for the very first time-- the three last parameters --a word and two numbers--
"TRUE 0 0)" until the closing parenthesis. Always focus on the separators of the language.

The idea is to remove those three last parameters in the modern function replacing them only with the closing parenthesis.

• "\w+" matches "TRUE"
• "\d+" matches "0"
• the last "\d+" matches also "0"
• "\)" matches ")". We need to backslash the closing parenthesis to avoid the known semantic of group.

Moreover let us indicate another similar example:
Again in the legacy function gimp-rect-select, the two last parameters "feather feather-radius" will be forgotten.

Existing deprecated function:


Goal of the replacement with the modern function:


The rewriting rule could be defined by the following:

Notepad++ menu "Search" > "Replace..."
[x] Regular expression

Find what:


Replace with:

Please note that in the "Replace with", the closing parenthesis does not need to be backslashed.

4.2 Newline inside the parameters

In Aqua btn, the previous regular expressions work if the deprecated function is on only one line.
What appends if the list of parameters is split on two lines.

After the Notepad++ option [x] Regular expression, checking [x] . matches newline
will capture to many functions until the last constant "CHANNEL" of the file. The regular expression is too greedy.

Of course, you can replace manually the deprecated functions without using regular expressions.
It depends of the number of the replacements.

However searching in the online help of Notepad++ regular expression,
you may wish to try the "/R" regular expression that captures EOL (End of line).
EOL depends on the operating system:

• Windows: "\r\n"
• Linux and macOS: "\n"
• classic Mac OS: "\r"

Notepad++ menu "Search" > "Replace..."
[x] Regular expression

Find what:

We accept only one newline "\R{1}" inside the list of parameters before the constant "CHANNEL".
The number of the previous character is indicated between brace parenthesis "{1}".

There is probably a better, shorter solution. It is up to you to improve this solution replying to this thread.

According to a previous chapter 3. Minus-in-the-name-of-Scheme variable, if the Scheme code uses minus inside the name of variable,
feel free to replace each word "\w+" by the interval "[_\-\d\l\u]+" including minus "-" in the name of a parameter.

5. New parameters in the modern function: level difficult

Finally the last family of deprecated functions introduces new parameters often unknown parameters.

As usual, the first function is the deprecated function:

The second function is the associated modern function having linear as new last parameter.

Since there is only one occurrence of gimp-invert in Aqua btn, you can manually replace it with the modern function.
However, the rewriting rule with regex could be:

Notepad++ menu "Search" > "Replace..."
[x] Regular expression

Find what:

The hypothesis is that the parameter drawable is a variable but not the result of the call of a function including parenthesis.

Replace with:

In line 167 of AquaBou2_10_28.scm, AlSchemist preferred TRUE for linear however this is an open discussion.
The final result of the generated aqua pill does not suffer to this new parameter with the modern function.

In the final example, PDB could not help anymore.
The difficulty increases with the number of options for the new parameter code-named operation:

The alignment indicates that layer = item.
According to the following rewriting rule, AlSchemist chose "CHANNEL-OP-REPLACE" for operation
however the relationship with the selection of layer alpha is not patent.

Notepad++ menu "Search" > "Replace..."
[x] Regular expression

Find what:


Replace with:

There are four occurrences: lines 39, 52, 58 and 168.
It is up to you to test the other alternatives if you prefer them.

This post concludes the series of articles about:
migrating Script-Fu deprecated functions in Gimp 2.10.28