From 3b0db4f96671dacfd3421850abb588b84e2ce6da Mon Sep 17 00:00:00 2001
From: Jarkko Hietaniemi <jhi@iki.fi>
Date: Wed, 16 Apr 2003 17:24:24 +0000
Subject: [PATCH] Handle PERLIO= and document a bit.

p4raw-id: //depot/perl@19241
---
 lib/PerlIO.pm   | 17 +++++++----------
 pod/perlrun.pod |  2 ++
 t/io/layers.t   | 13 +++++++++++++
 3 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm
index 678a79d..24bc2b2 100644
--- a/lib/PerlIO.pm
+++ b/lib/PerlIO.pm
@@ -224,6 +224,8 @@ This can be used to see the effect of/bugs in the various layers e.g.
   PERLIO=stdio  ./perl harness
   PERLIO=perlio ./perl harness
 
+For the various value of PERLIO see L<perlrun/PERLIO>.
+
 =head2 Querying the layers of filehandle
 
 The following returns the B<names> of the PerlIO layers on a filehandle.
@@ -236,20 +238,15 @@ C<perlio>.  Under C<stdio> the platform specific low-level I/O (like
 C<unix>) is not part of the stack, but under C<perlio> (and the
 experimental C<mmap>) it is.
 
-In platforms of DOS progeny (Win32 being the most prominent) the
-lowest level layers are C<unix crlf>, meaning that Perl first uses the
-UNIX-style low-level fd layer, and then on top of that a layer that
-handles the CRLF translation.
-
 The following table summarizes the default layers on UNIX-like and
 DOS-like platforms and depending on the setting of the C<$ENV{PERLIO}>:
 
- PERLIO   UNIX-like       DOS-like
+ PERLIO     UNIX-like       DOS-like
  
- none     stdio           unix crlf
- stdio    stdio           stdio
- perlio   unix perlio     unix perlio
- mmap     unix mmap       unix mmap
+ none or "" stdio           unix crlf
+ stdio      stdio           stdio
+ perlio     unix perlio     unix perlio
+ mmap       unix mmap       unix mmap
 
 By default the layers from the input side of the filehandle is
 returned, to get the output side use the optional C<output> argument:
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index e6c8f73..2b63c6b 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -918,6 +918,8 @@ emphasise their similarity to variable "attributes". But the code that parses
 layer specification strings (which is also used to decode the PERLIO
 environment variable) treats the colon as a separator.
 
+An unset or empty PERLIO is equivalent to C<:stdio>.
+
 The list becomes the default for I<all> perl's IO. Consequently only built-in
 layers can appear in this list, as external layers (such as :encoding()) need
 IO in  order to load them!. See L<"open pragma"|open> for how to add external
diff --git a/t/io/layers.t b/t/io/layers.t
index 0da804c..7ba517a 100644
--- a/t/io/layers.t
+++ b/t/io/layers.t
@@ -8,7 +8,10 @@ BEGIN {
 	print "1..0 # Skip: not perlio\n";
 	exit 0;
     }
+    # Makes testing easier.
+    $ENV{PERLIO} = 'stdio' if exists $ENV{PERLIO} && $ENV{PERLIO} eq '';
     if (exists $ENV{PERLIO} && $ENV{PERLIO} !~ /^(stdio|perlio|mmap)$/) {
+	# We are not prepared for anything else.
 	print "1..0 # PERLIO='$ENV{PERLIO}' unknown\n";
 	exit 0;
     }
@@ -27,6 +30,16 @@ SKIP: {
 
     sub check {
 	my ($result, $expected, $id) = @_;
+	# An interesting dance follows where we try to make the following
+	# IO layer stack setups to compare equal:
+	#
+	# PERLIO     UNIX-like       DOS-like
+	#
+	# none or "" stdio           unix crlf
+	# stdio      stdio           stdio
+	# perlio     unix perlio     unix perlio
+	# mmap       unix mmap       unix mmap
+	#
 	if ($NONSTDIO) {
 	    # Get rid of "unix".
 	    shift @$result if $result->[0] eq "unix";
-- 
1.8.3.1