builtin SUBST eat chars in replacement :lady_beetle:

[paolopas]

SUBST documentation is completely missing, so I wrote it myself (doing the usual reverse-engineering of the code.) Before integrating it, it's best to wait for #560 to merge (God willing.)

rule SUBST ( string regexp replacements + )

Replaces the string matching the regexp with all replacements.
The regexp argument accepts a regular expression of the same type as those used by the MATCH rule.
In replacements, the placeholders \0 and $0 are replaced with the full matched string, while \N and $N are replaced with the substring matched by group (() regexp subexpression) N-th. Currently only 9 groups are supported, so $10 in a replacement is interpreted as $1 followed by a '0' character.
Note that unlike MATCH, regexp does not have to contain a group for a result to be returned.

The Issue

The \ and $ characters in replacements disappear when they are not in placeholders.
As the following Jamfile demonstrates:

input = hello ;
pattern = l ;
ECHO [ SUBST $(input) $(pattern) X$X\\X _$0_\\0_ ] ;
UPDATE ;

gives:

XXX _l_l_

instead of the expected:

X$X\X _l_l_

Note

If you see a 🐞 in the issue heading it's because my browser doesn't support label management. René please put the label you think is appropriate.

Note

I've already written the code that fixes the problem and a new dedicated test, as well as the missing documentation. Normally, for a matter like this, I would have written a PR directly, but I already have too many submitted, some of which have been waiting months.