G'day Luc,

Welcome to the Monastery.

The documentation you're probably looking for is "perlop: Quote and Quote-like Operators". Note the "Interpolates" column in the table at the start of that section.

In the next main section, perlop: Regexp Quote-Like Operators", you'll see s/PATTERN/REPLACEMENT/... (you'll need to scroll to the end of that section). That simply refers to "replacement text". I can't see any further mention of interpolating here; although, as indicated via my first link, it does occur.

$ alias perle
alias perle='perl -Mstrict -Mwarnings -Mautodie=:all -MCarp::Always -E
+'
[download]

Just as you can interpolate hash elements in an interpolated string:

$ perle 'my %x = qw{0 a 1 b 2 c}; say "$x{0}$x{1}$x{2}"'
abc
[download]

You can do the same in s/// interpolated replacement text:

$ perle 'my %x = qw{0 a 1 b 2 c}; say "012" =~ s/([012])/$x{$1}/gr'
abc
[download]

The same applies to array elements in an interpolated string:

$ perle 'my @x = qw{a b c}; say "$x[0]$x[1]$x[2]"'
abc
[download]

And, equivalently, in s/// interpolated replacement text:

$ perle 'my @x = qw{a b c}; say "012" =~ s/([012])/$x[$1]/gr'
abc
[download]

This has actually been around for a long time. I use it often and, as it's so ingrained, it took a while to locate the doco.

Here's a very quick-and-dirty example of usage to prepare raw text for HTML:

$ perle 'my %ent = qw{& &amp; < &lt; > &gt;}; say "... < & > ..." =~ s
+/([&><])/$ent{$1}/gr'
... &lt; &amp; &gt; ...
[download]