[doc] Please document the $var =~ s{RE}{code}; syntax

[cb-acustaf]

Where
All of them?
But specific to regex.

Description

$var =~ s{ put-your-re-here-and-whitespace-is-not-counted }{ put-perl-code-here-which-prints-the-substitution }

The above syntax is not documented anywhere.
I've looked in the manpage, and followed search links to https://perldoc.perl.org/perlre and https://perldoc.perl.org/perlreref and there is no explanation for the syntax.
There are a couple brief examples being used to help explain other features, but this syntax itself is not ever explained.
The engineer part of my brain needs to see the syntax explained.

Thank you.

[mauke]

The =~ operator is documented in perldoc perlop: https://perldoc.perl.org/perlop#Binding-Operators

The s operator is documented in perldoc perlop: https://perldoc.perl.org/perlop#s/PATTERN/REPLACEMENT/msixpodualngcer

The free choice of delimiter for quoting operators (including balanced {} pairs) is also in perldoc perlop: https://perldoc.perl.org/perlop#Quote-and-Quote-like-Operators

The regex x modifier, which allows whitespace and comments in the pattern, is documented under qr, which s incorporates by reference (indirectly, via m): https://perldoc.perl.org/perlop#qr/STRING/msixpodualn

The e modifier, which tells s that the replacement part is a code block, not a quoted string (and which isn't really regex-related), is documented under s: https://perldoc.perl.org/perlop#s/PATTERN/REPLACEMENT/msixpodualngcer

Which of these were you looking for?

[cb-acustaf]

Lukas, Thank you for your complete answer. This part of the documentation could use updating, https://perldoc.perl.org/perlop#Regexp-Quote-Like-Operators, as it does not mention the alternative quote operators. especially since that link is where https://perldoc.perl.org/perlre sends the reader for "Regexp Quote-Like Operators". I guess I would expect the "perlre" page to be the definitive page for regex. The {} as regex delimiters is new to me and was driving me insane as I couldn't find where they were defined as legal syntax. I've never seen code be used on the right side of regex syntax before. The Camel Book's 7 pages on regex don't provide any detail on what "expression" meant, and it never clicked in my brain. Once again, thank you for the links.

…

On Thu, Aug 28, 2025 at 3:02 PM Lukas Mai ***@***.***> wrote: *mauke* left a comment (Perl/perl5#23655) <#23655 (comment)> The =~ operator is documented in perldoc perlop: https://perldoc.perl.org/perlop#Binding-Operators The s operator is documented in perldoc perlop: https://perldoc.perl.org/perlop#s/PATTERN/REPLACEMENT/msixpodualngcer The free choice of delimiter for quoting operators (including balanced {} pairs) is also in perldoc perlop: https://perldoc.perl.org/perlop#Quote-and-Quote-like-Operators The regex x modifier, which allows whitespace and comments in the pattern, is documented under qr, which s incorporates by reference (indirectly, via m): https://perldoc.perl.org/perlop#qr/STRING/msixpodualn The e modifier, which tells s that the replacement part is a code block, not a quoted string (and which isn't really regex-related), is documented under s: https://perldoc.perl.org/perlop#s/PATTERN/REPLACEMENT/msixpodualngcer Which of these were you looking for? — Reply to this email directly, view it on GitHub <#23655 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AZGU4LRYCFHQ2EAFXLF72PL3P5N5XAVCNFSM6AAAAACFCPIHY6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTEMZUG43TONJXGM> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[mauke]

I just realized perldoc perlretut also mentions e and delimiters: https://perldoc.perl.org/perlretut#Search-and-replace

A modifier available specifically to search and replace is the s///e evaluation modifier. s///e treats the replacement text as Perl code, rather than a double-quoted string. The value that the code returns is substituted for the matched substring. s///e is useful if you need to do a bit of computation in the process of replacing text. [...]

As with the match m// operator, s/// can use other delimiters, such as s!!! and s{}{}, and even s{}//. If single quotes are used s''', then the regexp and replacement are treated as single-quoted strings and there are no variable substitutions.

That aside, there is an issue of terminology:

The {} as regex delimiters is new to me and was driving me insane as I
couldn't find where they were defined as legal syntax.

I've never seen code be used on the right side of regex syntax before.

Strictly speaking, "regex syntax" is what goes in the REGEX part of s/REGEX/REPLACEMENT/FLAGS (and that is what perlre is mainly concerned with). The {} aren't regex delimiters per se and there is no "right side" of a regex. What we're dealing with is really the s substitution operator and its syntax.

I do realize that perl's documentation is sometimes arranged in odd ways. And if you had known that s is the crucial bit, perldoc -f s would have given you a page with examples of s{}[] and s///e (among other things).

PS: https://perldoc.perl.org/perlre#The-Basics does briefly mention alternative (and paired) delimiters, giving examples of m<...> and m'...'.)