From 5df28176d3648ade0e57d2aeedfffe04cb77865e Mon Sep 17 00:00:00 2001
From: Scott Baker <scott@perturb.org>
Date: Fri, 21 Mar 2025 14:52:16 -0700
Subject: [PATCH 1/3] Clean-up, modernize, and add examples for `$|` and
autoflush
---
pod/perlvar.pod | 41 +++++++++++++++++++++++++++++++----------
1 file changed, 31 insertions(+), 10 deletions(-)
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 559ca8ebe3e7..e1d1f558e0e0 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -1828,19 +1828,40 @@ Also, it's just like C<$/>, but it's what you get "back" from Perl.
X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
If set to nonzero, forces a flush right away and after every write or
-print on the currently selected output channel. Default is 0
-(regardless of whether the channel is really buffered by the system or
-not; C<$|> tells you only whether you've asked Perl explicitly to
-flush after each write). STDOUT will typically be line buffered if
-output is to the terminal and block buffered otherwise. Setting this
-variable is useful primarily when you are outputting to a pipe or
-socket, such as when you are running a Perl program under B<rsh> and
-want to see the output as it's happening. This has no effect on input
-buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
-how to select the output channel. See also L<IO::Handle>.
+print on the currently selected output channel. The default is 0.
+
+C<STDOUT> will typically be line buffered if output is to the terminal
+and block buffered otherwise. Setting this variable is useful
+primarily when you are outputting to a pipe or socket. This would
+come into play when you are writing to a pipe and want to see the
+output "live" with no buffering.
+
+B<Examples:>
+
+ $| = 1; # Set autoflush for current channel
+ $is_buf = $|; # Get the current autoflush status
+
+ STDOUT->autoflush(1); # Enable autoflush for STDOUT
+ STDERR->autoflush(0); # Disable autoflush for STDERR
+
+B<Warning:> C<$|> tells you only if you have asked Perl explicitly to
+flush after each write. It is still possible the channel may be buffered
+by the system.
Mnemonic: when you want your pipes to be piping hot.
+B<See also:>
+
+=over
+
+=item * L<perlfunc/select> to pick the output channel.
+
+=item * L<IO::Handle> for more fine grained IO control.
+
+=item * L<perlfunc/getc> for information on I<input> buffering.
+
+=back
+
=item ${^LAST_FH}
X<${^LAST_FH}>
From b911e248a47e14254510a788a58010a678549e2d Mon Sep 17 00:00:00 2001
From: Scott Baker <scott@perturb.org>
Date: Fri, 21 Mar 2025 15:21:13 -0700
Subject: [PATCH 2/3] Clarify that it targets `C<$|>`
---
pod/perlvar.pod | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index e1d1f558e0e0..8ec5d04ec6df 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -1854,7 +1854,7 @@ B<See also:>
=over
-=item * L<perlfunc/select> to pick the output channel.
+=item * L<perlfunc/select> to pick the output channel for C<$|>.
=item * L<IO::Handle> for more fine grained IO control.
From 3e2e3823f78e187d7d5388fa3c191e1c54d00a5f Mon Sep 17 00:00:00 2001
From: Scott Baker <scott@perturb.org>
Date: Fri, 21 Mar 2025 15:22:27 -0700
Subject: [PATCH 3/3] Remove example for setting autoflush to zero
---
pod/perlvar.pod | 1 -
1 file changed, 1 deletion(-)
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 8ec5d04ec6df..cd1ba6cd2984 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -1842,7 +1842,6 @@ B<Examples:>
$is_buf = $|; # Get the current autoflush status
STDOUT->autoflush(1); # Enable autoflush for STDOUT
- STDERR->autoflush(0); # Disable autoflush for STDERR
B<Warning:> C<$|> tells you only if you have asked Perl explicitly to
flush after each write. It is still possible the channel may be buffered