From 15bd29898a60fb32c625ef95005385215b352b9b Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Wed, 7 May 2025 21:29:58 -0600 Subject: [PATCH 1/3] perlop: Fix heading levels for quote-like operators There is a "=head2 Quote and Quote-like Operators" that applies to several subsequent sections. Those sections should be =head3, as they are really subsections to that more general one. But until this commit they were =head2. --- pod/perlop.pod | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pod/perlop.pod b/pod/perlop.pod index f5ebf30e56c4..c482cb02dea1 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -1914,7 +1914,7 @@ expectations of shell programmers, back-quotes do I interpolate within double quotes, nor do single quotes impede evaluation of variables when used within double quotes. -=head2 Regexp Quote-Like Operators +=head3 Regexp Quote-Like Operators X Here are the quote-like operators that apply to pattern @@ -2458,7 +2458,7 @@ producing a warning if warnings are enabled. =back -=head2 Quote-Like Operators +=head3 Quote-Like Operators X =over 4 @@ -3071,7 +3071,7 @@ should be safe. =back -=head2 Gory details of parsing quoted constructs +=head3 Gory details of parsing quoted constructs X When presented with something that might have several different From c51a6723f5a131b933bf133baf0c68676c346b3c Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Thu, 8 May 2025 08:31:46 -0600 Subject: [PATCH 2/3] perlop: Create a heading for tr///; adjust other headings For symmetry and being able to find it, the tr/// command should have a heading. This means that what we now call Quote-Like Operators no longer includes it, so rename it. --- pod/perlop.pod | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/pod/perlop.pod b/pod/perlop.pod index c482cb02dea1..15d0ea743cd2 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -2458,7 +2458,7 @@ producing a warning if warnings are enabled. =back -=head3 Quote-Like Operators +=head3 Simpler Quote-Like Operators X =over 4 @@ -2637,16 +2637,22 @@ put comments into a multi-line C-string. For this reason, the S> pragma and the B<-w> switch (that is, the C<$^W> variable) produces warnings if the I contains the C<","> or the C<"#"> character. +=back + +=head3 Transliteration Quote-Like Operators + +=over + =item C/I/cdsr> X X X X X X =item C/I/cdsr> -Transliterates all occurrences of the characters found (or not found +These transliterate all occurrences of the characters found (or not found if the C modifier is specified) in the search list with the positionally corresponding character in the replacement list, possibly deleting some, depending on the modifiers specified. Unless the C -flag is specified, it returns the number of characters replaced or +flag is specified, they return the number of characters replaced or deleted. If no string is specified via the C<=~> or C operator, the C<$_> string is transliterated. @@ -3882,6 +3888,10 @@ This section has been superceded by L. The heading is retained only to prevent breaking any pre-existing links to it from outside. +=head2 Quote-Like Operators + +This section has been replaced by L + =head1 APPENDIX =head2 List of Extra Paired Delimiters From 59a950501ef43b9f50c2103b555e8d271242ed5a Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Thu, 8 May 2025 08:43:11 -0600 Subject: [PATCH 3/3] Move simpler to first The single and double quote operators are simplest to understand; they should be the first ones describedl --- pod/perlop.pod | 362 ++++++++++++++++++++++++------------------------- 1 file changed, 181 insertions(+), 181 deletions(-) diff --git a/pod/perlop.pod b/pod/perlop.pod index 15d0ea743cd2..a6f0a00bae5f 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -1914,6 +1914,187 @@ expectations of shell programmers, back-quotes do I interpolate within double quotes, nor do single quotes impede evaluation of variables when used within double quotes. +=head3 Simpler Quote-Like Operators +X + +=over 4 + +=item C/> +X X X<'> X<''> + +=item C<'I'> + +A single-quoted, literal string. A backslash represents a backslash +unless followed by the delimiter or another backslash, in which case +the delimiter or backslash is interpolated. + + $foo = q!I said, "You said, 'She said it.'"!; + $bar = q('This is it.'); + $baz = '\n'; # a two-character string + +=item C/> +X X X<"> X<""> + +=item C<"I"> + +A double-quoted, interpolated string. + + $_ .= qq + (*** The previous line contains the naughty word "$1".\n) + if /\b(tcl|java|python)\b/i; # :-) + $baz = "\n"; # a one-character string + +=item C/> +X X<`> X<``> X + +=item C<`I`> + +A string which is (possibly) interpolated and then executed as a +system command, via F or its equivalent if required. Shell +wildcards, pipes, and redirections will be honored. Similarly to +C, if the string contains no shell metacharacters then it will +be executed directly. The collected standard output of the command is +returned; standard error is unaffected. In scalar context, it comes +back as a single (potentially multi-line) string, or C if the +shell (or command) could not be started. In list context, returns a +list of lines (however you've defined lines with C<$/> or +C<$INPUT_RECORD_SEPARATOR>), or an empty list if the shell (or command) +could not be started. + + print qx/date/; # prints "Sun Jan 28 06:16:19 CST 2024" + +Because backticks do not affect standard error, use shell file descriptor +syntax (assuming the shell supports this) if you care to address this. +To capture a command's STDERR and STDOUT together: + + $output = `cmd 2>&1`; + +To capture a command's STDOUT but discard its STDERR: + + $output = `cmd 2>/dev/null`; + +To capture a command's STDERR but discard its STDOUT (ordering is +important here): + + $output = `cmd 2>&1 1>/dev/null`; + +To exchange a command's STDOUT and STDERR in order to capture the STDERR +but leave its STDOUT to come out the old STDERR: + + $output = `cmd 3>&1 1>&2 2>&3 3>&-`; + +To read both a command's STDOUT and its STDERR separately, it's easiest +to redirect them separately to files, and then read from those files +when the program is done: + + system("program args 1>program.stdout 2>program.stderr"); + +The STDIN filehandle used by the command is inherited from Perl's STDIN. +For example: + + open(SPLAT, "stuff") || die "can't open stuff: $!"; + open(STDIN, "<&SPLAT") || die "can't dupe SPLAT: $!"; + print STDOUT `sort`; + +will print the sorted contents of the file named F<"stuff">. + +Using single-quote as a delimiter protects the command from Perl's +double-quote interpolation, passing it on to the shell instead: + + $perl_info = qx(ps $$); # that's Perl's $$ + $shell_info = qx'ps $$'; # that's the new shell's $$ + +How that string gets evaluated is entirely subject to the command +interpreter on your system. On most platforms, you will have to protect +shell metacharacters if you want them treated literally. This is in +practice difficult to do, as it's unclear how to escape which characters. +See L for a clean and safe example of a manual C and C +to emulate backticks safely. + +On some platforms (notably DOS-like ones), the shell may not be +capable of dealing with multiline commands, so putting newlines in +the string may not get you what you want. You may be able to evaluate +multiple commands in a single line by separating them with the command +separator character, if your shell supports that (for example, C<;> on +many Unix shells and C<&> on the Windows NT C shell). + +Perl will attempt to flush all files opened for +output before starting the child process, but this may not be supported +on some platforms (see L). To be safe, you may need to set +C<$|> (C<$AUTOFLUSH> in C>) or call the C method of +C> on any open handles. + +Beware that some command shells may place restrictions on the length +of the command line. You must ensure your strings don't exceed this +limit after any necessary interpolations. See the platform-specific +release notes for more details about your particular environment. + +Using this operator can lead to programs that are difficult to port, +because the shell commands called vary between systems, and may in +fact not be present at all. As one example, the C command under +the POSIX shell is very different from the C command under DOS. +That doesn't mean you should go out of your way to avoid backticks +when they're the right way to get something done. Perl was made to be +a glue language, and one of the things it glues together is commands. +Just understand what you're getting yourself into. + +Like C, backticks put the child process exit code in C<$?>. +If you'd like to manually inspect failure, you can check all possible +failure modes by inspecting C<$?> like this: + + if ($? == -1) { + print "failed to execute: $!\n"; + } + elsif ($? & 127) { + printf "child died with signal %d, %s coredump\n", + ($? & 127), ($? & 128) ? 'with' : 'without'; + } + else { + printf "child exited with value %d\n", $? >> 8; + } + +Use the L pragma to control the I/O layers used when reading the +output of the command, for example: + + use open IN => ":encoding(UTF-8)"; + my $x = `cmd-producing-utf-8`; + +C can also be called like a function with L. + +See L for more discussion. + +=item C/> +X X X + +Evaluates to a list of the words extracted out of I, using embedded +whitespace as the word delimiters. It can be understood as being roughly +equivalent to: + + split(" ", q/STRING/); + +the differences being that it only splits on ASCII whitespace, +generates a real list at compile time, and +in scalar context it returns the last element in the list. So +this expression: + + qw(foo bar baz) + +is semantically equivalent to the list: + + "foo", "bar", "baz" + +Some frequently seen examples: + + use POSIX qw( setlocale localeconv ) + @EXPORT = qw( foo bar baz ); + +A common mistake is to try to separate the words with commas or to +put comments into a multi-line C-string. For this reason, the +S> pragma and the B<-w> switch (that is, the C<$^W> variable) +produces warnings if the I contains the C<","> or the C<"#"> character. + +=back + =head3 Regexp Quote-Like Operators X @@ -2458,187 +2639,6 @@ producing a warning if warnings are enabled. =back -=head3 Simpler Quote-Like Operators -X - -=over 4 - -=item C/> -X X X<'> X<''> - -=item C<'I'> - -A single-quoted, literal string. A backslash represents a backslash -unless followed by the delimiter or another backslash, in which case -the delimiter or backslash is interpolated. - - $foo = q!I said, "You said, 'She said it.'"!; - $bar = q('This is it.'); - $baz = '\n'; # a two-character string - -=item C/> -X X X<"> X<""> - -=item C<"I"> - -A double-quoted, interpolated string. - - $_ .= qq - (*** The previous line contains the naughty word "$1".\n) - if /\b(tcl|java|python)\b/i; # :-) - $baz = "\n"; # a one-character string - -=item C/> -X X<`> X<``> X - -=item C<`I`> - -A string which is (possibly) interpolated and then executed as a -system command, via F or its equivalent if required. Shell -wildcards, pipes, and redirections will be honored. Similarly to -C, if the string contains no shell metacharacters then it will -be executed directly. The collected standard output of the command is -returned; standard error is unaffected. In scalar context, it comes -back as a single (potentially multi-line) string, or C if the -shell (or command) could not be started. In list context, returns a -list of lines (however you've defined lines with C<$/> or -C<$INPUT_RECORD_SEPARATOR>), or an empty list if the shell (or command) -could not be started. - - print qx/date/; # prints "Sun Jan 28 06:16:19 CST 2024" - -Because backticks do not affect standard error, use shell file descriptor -syntax (assuming the shell supports this) if you care to address this. -To capture a command's STDERR and STDOUT together: - - $output = `cmd 2>&1`; - -To capture a command's STDOUT but discard its STDERR: - - $output = `cmd 2>/dev/null`; - -To capture a command's STDERR but discard its STDOUT (ordering is -important here): - - $output = `cmd 2>&1 1>/dev/null`; - -To exchange a command's STDOUT and STDERR in order to capture the STDERR -but leave its STDOUT to come out the old STDERR: - - $output = `cmd 3>&1 1>&2 2>&3 3>&-`; - -To read both a command's STDOUT and its STDERR separately, it's easiest -to redirect them separately to files, and then read from those files -when the program is done: - - system("program args 1>program.stdout 2>program.stderr"); - -The STDIN filehandle used by the command is inherited from Perl's STDIN. -For example: - - open(SPLAT, "stuff") || die "can't open stuff: $!"; - open(STDIN, "<&SPLAT") || die "can't dupe SPLAT: $!"; - print STDOUT `sort`; - -will print the sorted contents of the file named F<"stuff">. - -Using single-quote as a delimiter protects the command from Perl's -double-quote interpolation, passing it on to the shell instead: - - $perl_info = qx(ps $$); # that's Perl's $$ - $shell_info = qx'ps $$'; # that's the new shell's $$ - -How that string gets evaluated is entirely subject to the command -interpreter on your system. On most platforms, you will have to protect -shell metacharacters if you want them treated literally. This is in -practice difficult to do, as it's unclear how to escape which characters. -See L for a clean and safe example of a manual C and C -to emulate backticks safely. - -On some platforms (notably DOS-like ones), the shell may not be -capable of dealing with multiline commands, so putting newlines in -the string may not get you what you want. You may be able to evaluate -multiple commands in a single line by separating them with the command -separator character, if your shell supports that (for example, C<;> on -many Unix shells and C<&> on the Windows NT C shell). - -Perl will attempt to flush all files opened for -output before starting the child process, but this may not be supported -on some platforms (see L). To be safe, you may need to set -C<$|> (C<$AUTOFLUSH> in C>) or call the C method of -C> on any open handles. - -Beware that some command shells may place restrictions on the length -of the command line. You must ensure your strings don't exceed this -limit after any necessary interpolations. See the platform-specific -release notes for more details about your particular environment. - -Using this operator can lead to programs that are difficult to port, -because the shell commands called vary between systems, and may in -fact not be present at all. As one example, the C command under -the POSIX shell is very different from the C command under DOS. -That doesn't mean you should go out of your way to avoid backticks -when they're the right way to get something done. Perl was made to be -a glue language, and one of the things it glues together is commands. -Just understand what you're getting yourself into. - -Like C, backticks put the child process exit code in C<$?>. -If you'd like to manually inspect failure, you can check all possible -failure modes by inspecting C<$?> like this: - - if ($? == -1) { - print "failed to execute: $!\n"; - } - elsif ($? & 127) { - printf "child died with signal %d, %s coredump\n", - ($? & 127), ($? & 128) ? 'with' : 'without'; - } - else { - printf "child exited with value %d\n", $? >> 8; - } - -Use the L pragma to control the I/O layers used when reading the -output of the command, for example: - - use open IN => ":encoding(UTF-8)"; - my $x = `cmd-producing-utf-8`; - -C can also be called like a function with L. - -See L for more discussion. - -=item C/> -X X X - -Evaluates to a list of the words extracted out of I, using embedded -whitespace as the word delimiters. It can be understood as being roughly -equivalent to: - - split(" ", q/STRING/); - -the differences being that it only splits on ASCII whitespace, -generates a real list at compile time, and -in scalar context it returns the last element in the list. So -this expression: - - qw(foo bar baz) - -is semantically equivalent to the list: - - "foo", "bar", "baz" - -Some frequently seen examples: - - use POSIX qw( setlocale localeconv ) - @EXPORT = qw( foo bar baz ); - -A common mistake is to try to separate the words with commas or to -put comments into a multi-line C-string. For this reason, the -S> pragma and the B<-w> switch (that is, the C<$^W> variable) -produces warnings if the I contains the C<","> or the C<"#"> character. - -=back - =head3 Transliteration Quote-Like Operators =over