Update some pods.
Make t/op/utf8decode.t a text file.
p4raw-id: //depot/perlio@9417
lib/open3.pl Open a three-ended pipe (uses IPC::Open3)
lib/overload.pm Module for overloading perl operators
lib/perl5db.pl Perl debugging routines
-lib/perlio.pm Perl IO interface pragma
lib/pwd.pl Routines to keep track of PWD environment variable
lib/shellwords.pl Perl library to split into words with shell quoting
lib/sigtrap.pm For trapping an abort and giving traceback
=head1 NAME
-PerlIO - On demand loader for PerlIO::* name space
+PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space
=head1 SYNOPSIS
- open($fh,">:foo",...)
+ open($fh,">:crlf","my.txt")
+ open($fh,">:raw","his.jpg")
+
+ Shell:
+ PERLIO=perlio perl ....
=head1 DESCRIPTION
Otherwise the C<PerlIO> package is a place holder for additional PerLIO related
functions.
+The following layers are currently defined:
-=cut
+=over 4
+
+=item unix
+
+Low level layer which calls C<read>, C<write> and C<lseek> etc.
+
+=item stdio
+
+Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc.
+Note that as this is "real" stdio it will ignore any layers beneath it and
+got straight to the operating system via the C library as usual.
+
+=item perlio
+
+This is a re-implementation of "stdio-like" buffering written as a PerlIO "layer".
+As such it will call whatever layer is below it for its operations.
+
+=item crlf
+
+A layer which does CRLF to "\n" translation distinguishing "text" and "binary"
+files in the manner of MS-DOS and similar operating systems.
+
+=item utf8
+
+Declares that the stream accepts perl's internal encoding of characters.
+(Which really is UTF-8 on ASCII machines, but is UTF-EBCDIC on EBCDIC machines.)
+This allows any character perl can represent to be read from or written to the
+stream. The UTF-X encoding is chosen to render simple text parts (i.e.
+non-accented letters, digits and common punctuation) human readable in the
+encoded file.
+
+=item raw
+
+A pseudo-layer which performs two functions (which is messy, but necessary to
+maintain compatibility with non-PerLIO builds of perl and they way things
+have been documented elsewhere).
+
+Firstly it forces the file handle to be considered binary at that point
+in the layer stack,
+
+Secondly in prevents the IO system seaching back before it in the layer specification.
+Thus:
+
+ open($fh,":raw:perlio"),...)
+
+Forces the use of C<perlio> layer even if the platform default, or C<use open> default
+is something else (such as ":encoding(iso-8859-7)" ) which would interfere with
+binary nature of the stream.
+=back
+
+=head2 Defaults and how to override them
+
+If the platform is MS-DOS like and normally does CRLF to "\n" translation
+for text files then the default layers are :
+
+ unix crlf
+
+(The low level "unix" layer may be replaced by a platform specific low level layer.)
+
+Otherwise if C<Configure> found out how to do "fast" IO using system's stdio, then
+the default layers are :
+
+ unix stdio
+
+Otherwise the default layers are
+
+ unix perlio
+
+These defaults may change once perlio has been better tested and tuned.
+
+The default can be overridden by setting the environment variable PERLIO
+to a space separated list of layers (unix or platform low level layer is
+always pushed first).
+This can be used to see the effect of/bugs in the various layers e.g.
+
+ cd .../perl/t
+ PERLIO=stdio ./perl harness
+ PERLIO=perlio ./perl harness
+
+=head1 AUTHOR
+
+Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
+
+=head1 SEE ALSO
+
+L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<open>
+
+=cut
use Carp;
$open::hint_bits = 0x20000;
+# layers array and hash mainly manipulated by C code in perlio.c
use vars qw(%layers @layers);
# Populate hash in non-PerlIO case
=head1 DESCRIPTION
-The open pragma is used to declare one or more default disciplines for
-I/O operations. Any open() and readpipe() (aka qx//) operators found
-within the lexical scope of this pragma will use the declared defaults.
-Neither open() with an explicit set of disciplines, nor sysopen() are
-influenced by this pragma.
+Full-fledged support for I/O disciplines is now implemented provided perl is
+configured to use PerlIO as its IO system (which is now the default).
-Only the two pseudo-disciplines ":raw" and ":crlf" are currently
-available.
+The C<open> pragma serves as one of the interfaces to declare default
+"layers" (aka disciplines) for all I/O.
+
+The C<open> pragma is used to declare one or more default layers for
+I/O operations. Any open(), readpipe() (aka qx//) and similar operators
+found within the lexical scope of this pragma will use the declared defaults.
+
+When open() is given an explicit list of layers they are appended to the
+list declared using this pragma.
+
+Directory handles may also support disciplines in future.
+
+=head1 NONPERLIO FUNCTIONALITY
+
+If perl is not built to use PerlIO as its IO system then only the two pseudo-disciplines
+":raw" and ":crlf" are available.
The ":raw" discipline corresponds to "binary mode" and the ":crlf"
discipline corresponds to "text mode" on platforms that distinguish
between the two modes when opening files (which is many DOS-like
-platforms, including Windows). These two disciplines are currently
-no-ops on platforms where binmode() is a no-op, but will be
-supported everywhere in future.
+platforms, including Windows). These two disciplines are
+no-ops on platforms where binmode() is a no-op, but perform their
+functions everywhere if PerlIO is enabled.
+
+=head1 IMPLEMENTATION DETAILS
-=head1 UNIMPLEMENTED FUNCTIONALITY
+There are two package variables C<%layers> and C<@layers> which
+are mainly manipulated by C code in F<perlio.c>, but are visible
+to the nosy:
-Full-fledged support for I/O disciplines is currently unimplemented.
-When they are eventually supported, this pragma will serve as one of
-the interfaces to declare default disciplines for all I/O.
+ print "Have ",join(',',keys %open::layers),"\n";
+ print "Using ",join(',',@open::layers),"\n";
-In future, any default disciplines declared by this pragma will be
-available by the special discipline name ":DEFAULT", and could be used
-within handle constructors that allow disciplines to be specified.
-This would make it possible to stack new disciplines over the default
-ones.
+The C<%open::layers> hash is a record of the available "layers" that may be pushed
+onto a C<PerlIO> stream. The values of the hash are perl objects, of class C<PerlIO::Layer>
+which are created by the C code in F<perlio.c>. As yet there is nothing useful you
+can do with the objects at the perl level.
- open FH, "<:para :DEFAULT", $file or die "can't open $file: $!";
+The C<@open::layers> array is the current set of layers and their arguments.
+The array consists of layer => argument pairs and I<must> always have even number of
+entries and the even entries I<must> be C<PerlIO::Layer> objects or perl will "die"
+when it attempts to open a filehandle. In most cases the odd entry will be C<undef>,
+but in the case of (say) ":encoding(iso-8859-1)" it will be 'iso-8859-1'. These
+argument entries are currently restricted to being strings.
-Socket and directory handles will also support disciplines in
-future.
+When a new C<PerlIO> stream is opened, the C code looks at the
+array to determine the default layers to be pushed. So with care it is possible
+to manipulate the default layer "stack":
-Full support for I/O disciplines will enable all of the supported
-disciplines to work on all platforms.
+ splice(@PerlIO::layers,-2,2);
+ push(@PerlIO::layers,$PerlIO::layers{'stdio'} => undef);
=head1 SEE ALSO
-L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>
+L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<PerlIO>
=cut
+++ /dev/null
-package perlio;
-1;
-__END__
-
-=head1 NAME
-
-perlio - perl pragma to configure C level IO
-
-=head1 SYNOPSIS
-
- Shell:
- PERLIO=perlio perl ....
-
- print "Have ",join(',',keys %perlio::layers),"\n";
- print "Using ",join(',',@perlio::layers),"\n";
-
-
-=head1 DESCRIPTION
-
-Mainly a Place holder for now.
-
-The C<%perlio::layers> hash is a record of the available "layers" that may be pushed
-onto a C<PerlIO> stream.
-
-The C<@perlio::layers> array is the current set of layers that are used when
-a new C<PerlIO> stream is opened. The C code looks are the array each time
-a stream is opened so the "stack" can be manipulated by messing with the array :
-
- pop(@perlio::layers);
- push(@perlio::layers,$perlio::layers{'stdio'});
-
-The values if both the hash and the array are perl objects, of class C<perlio::Layer>
-which are created by the C code in C<perlio.c>. As yet there is nothing useful you
-can do with the objects at the perl level.
-
-There are three layers currently defined:
-
-=over 4
-
-=item unix
-
-Low level layer which calls C<read>, C<write> and C<lseek> etc.
-
-=item stdio
-
-Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc.
-Note that as this is "real" stdio it will ignore any layers beneath it and
-got straight to the operating system via the C library as usual.
-
-=item perlio
-
-This is a re-implementation of "stdio-like" buffering written as a PerlIO "layer".
-As such it will call whatever layer is below it for its operations.
-
-=back
-
-=head2 Defaults and how to override them
-
-If C<Configure> found out how to do "fast" IO using system's stdio, then
-the default layers are :
-
- unix stdio
-
-Otherwise the default layers are
-
- unix perlio
-
-(STDERR will have just unix in this case as that is optimal way to make it
-"unbuffered" - do not add a buffering layer!)
-
-The default may change once perlio has been better tested and tuned.
-
-The default can be overridden by setting the environment variable PERLIO
-to a space separated list of layers (unix is always pushed first).
-This can be used to see the effect of/bugs in the various layers e.g.
-
- cd .../perl/t
- PERLIO=stdio ./perl harness
- PERLIO=perlio ./perl harness
-
-=head1 AUTHOR
-
-Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
-
-=cut
-
-
/*--------------------------------------------------------------------------------------*/
/* XS Interface for perl code */
-XS(XS_perlio_import)
-{
- dXSARGS;
- GV *gv = CvGV(cv);
- char *s = GvNAME(gv);
- STRLEN l = GvNAMELEN(gv);
- PerlIO_debug("%.*s\n",(int) l,s);
- XSRETURN_EMPTY;
-}
-
-XS(XS_perlio_unimport)
-{
- dXSARGS;
- GV *gv = CvGV(cv);
- char *s = GvNAME(gv);
- STRLEN l = GvNAMELEN(gv);
- PerlIO_debug("%.*s\n",(int) l,s);
- XSRETURN_EMPTY;
-}
-
SV *
PerlIO_find_layer(pTHX_ const char *name, STRLEN len)
{
SV *
PerlIO_tab_sv(pTHX_ PerlIO_funcs *tab)
{
- HV *stash = gv_stashpv("perlio::Layer", TRUE);
+ HV *stash = gv_stashpv("PerlIO::Layer", TRUE);
SV *sv = sv_bless(newRV_noinc(newSViv(PTR2IV(tab))),stash);
return sv;
}
{
const char *s = (PL_tainting) ? Nullch : PerlEnv_getenv("PERLIO");
PerlIO_layer_av = get_av("open::layers",GV_ADD|GV_ADDMULTI);
- newXS("perlio::import",XS_perlio_import,__FILE__);
- newXS("perlio::unimport",XS_perlio_unimport,__FILE__);
#if 0
newXS("io::MODIFY_SCALAR_ATTRIBUTES",XS_io_MODIFY_SCALAR_ATTRIBUTES,__FILE__);
#endif
chomp($a = `$^X $path "-MB::Stash" "-Mwarnings" -e1`);
$a = join ',', sort split /,/, $a;
-$a =~ s/-u(perlio|open)(?:::\w+)?,//g if defined $Config{'useperlio'} and $Config{'useperlio'} eq 'define';
+$a =~ s/-u(PerlIO|open)(?:::\w+)?,//g if defined $Config{'useperlio'} and $Config{'useperlio'} eq 'define';
$a =~ s/-uWin32,// if $^O eq 'MSWin32';
$a =~ s/-u(Cwd|File|File::Copy|OS2),//g if $^O eq 'os2';
$a =~ s/-uCwd,// if $^O eq 'cygwin';
{
my $wide = v256;
use bytes;
- print STDERR ord($wide),"\n";
if (ord($wide) == 140) {
print "1..0 # Skip: UTF-EBCDIC (not UTF-8) used here\n";
exit 0;
projects / p5sagit/p5-mst-13.2.git / commitdiff