Author: lwall
Date: 2009-03-14 18:32:42 +0100 (Sat, 14 Mar 2009)
New Revision: 25830
Modified:
docs/Perl6/Spec/S32-setting-library/IO.pod
Log:
[IO] Massive overhaul, long overdue due to neglect of TimToady--
Modified: docs/Perl6/Spec/S32-setting-library/IO.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/IO.pod 2009-03-14 17:11:19 UTC (rev
25829)
+++ docs/Perl6/Spec/S32-setting-library/IO.pod 2009-03-14 17:32:42 UTC (rev
25830)
@@ -13,11 +13,11 @@
Mark Stosberg <m...@summersault.com>
Carl Mäsak <cma...@gmail.com>
Moritz Lenz <mor...@faui2k3.org>
- Tim Nelson <wayl...@wayland.id.au>
+ Tim Nelson <wayl...@wayland.id.au>
Daniel Ruoso <dan...@ruoso.com>
Date: 19 Feb 2009 extracted from S29-functions.pod; added stuff from
S16-IO later
Last Modified: 14 Mar 2009
- Version: 4
+ Version: 5
The document is a draft.
@@ -27,97 +27,125 @@
=head2 IO
+[Note: if a method declaration indicates a method name qualified by
+type, it should be taken as shorthand to say which role or class the
+method is actually declared in.]
+
=over 4
+=item open
+
+ multi open (Str $name,
+ Bool :$rw = False,
+ Bool :$bin = False,
+ Str :$enc = "Unicode",
+ Any :$nl = "\n",
+ Bool :$chomp = True,
+ ...
+ --> IO
+ ) is export
+
+A convenience method/function that hides most of the OO complexity.
+It will only open normal files. Text is the default. Note that
+the "Unicode" encoding implies figuring out which actual UTF is
+in use, either from a BOM or other heuristics. If heuristics are
+inconclusive, UTF-8 will be assumed. (No 8-bit encoding will ever
+be picked implicitly.) A file opened with C<:bin> may still be
+processed line-by-line, but IO will be in terms of C<Buf> rather
+than C<Str> types.
+
=item getc
- our Bool method getc (IO $self: *...@list)
+ method getc (Int $chars = 1 --> Char)
See below for details.
=item print
- our Bool method print (IO $self: *...@list)
- our Bool multi print (*...@list)
- our Bool method print (Str $self: IO $io)
+ method print (*...@list --> Bool)
+ multi print (*...@list --> Bool)
+ method Str::print (IO $io --> Bool)
+ method Array::print (IO $io --> Bool)
+ method Hash::print (IO $io --> Bool)
See below for details.
=item say
- our Bool method say (IO $self: *...@list)
- our Bool multi say (*...@list)
- our Bool method say (Str $self: IO $io)
+ method say (*...@list --> Bool)
+ multi say (*...@list --> Bool)
+ method Str::say (IO $io --> Bool)
+ method Array::say (IO $io --> Bool)
+ method Hash::say (IO $io --> Bool)
See below for details.
=item printf
- our Bool method printf (IO $self: Str $fmt, *...@list)
- our Bool multi printf (Str $fmt, *...@list)
+ method printf (Str $fmt, *...@list --> Bool)
+ multi printf (Str $fmt, *...@list --> Bool)
See below for details.
=item uri
- IO::Streamable method uri(Str $uri);
- IO::Streamable sub uri(Str $uri);
+ method uri(Str $uri --> IO::Streamable);
+ sub uri(Str $uri --> IO::Streamable);
-Returns an appropriate IO::Streamable descendant, with the type depending on
the uri
+Returns an appropriate C<IO::Streamable> descendant, with the type depending
on the uri
passed in. Here are some example mappings:
- URI type IO type
- ======== =======
- file: IO::File or IO::Directory
- ftp: IO::Socket::TCP (data channel)
- http: IO::Socket::TCP
+ URI type IO type
+ ======== =======
+ file: IO::File or IO::Directory
+ ftp: IO::Socket::TCP (data channel)
+ http: IO::Socket::TCP
These can naturally be overridden or added to by other modules.
-=item %*PROTOCOLS global variable
+=item %*PROTOCOLS context variable
-For each protocol, stores a type name that should be instantiated by calling
the .uri()
+For each protocol, stores a type name that should be instantiated by calling
the C<uri>
constructor on that type, and passing in the appropriate uri.
=back
=head1 Roles
-The functionality of IO objects is broken down into several roles,
+The functionality of C<IO> objects is broken down into several roles,
which should identify the features each object supports.
=head2 IO
-The base role only tags that this is an IO object for more generic
+The base role only tags that this is an C<IO> object for more generic
purposes. It doesn't specify any methods or attributes.
=head2 IO::Readable
This role provides unbuffered read access to the data stream.
-role IO::Readable {
- has $.isReadable;
+ role IO::Readable {
+ has $.isReadable;
+ method read($buf is rw, Int $bytes --> Int)
+ }
- method Int read($buf is rw, Int $bytes)
-}
+When the C<$.isReadable> is set, it tries to change the readability of the
filehandle. This
+is not always possible, but can be done in a number of cases. C<IO::Socket>
can remove
+readability by calling C<shutdown>, for example.
-When the $.isReadable is set, it tries to change the readability of the
filehandle. This
-is not always possible, but can be done in a number of cases. IO::Socket can
remove
-readability by calling shutdown(), for example.
-
=over
-=item method Int read($buf is rw, Int $bytes)
+=item method read($buf is rw, Int $bytes --> Int)
-Tries to read $bytes bytes and store in $buf. The contents of $buf
+Tries to read C<$bytes> bytes and store in C<$buf>. The contents of C<$buf>
are replaced and the actual number of bytes read is returned. A return
of 0 means end of file. It might return unthrown failures, to be
-specified by each IO implementation.
+specified by each C<IO> implementation.
It is important to realize that this is "raw" read. You're going to
-have plain octets stored in $buf, if this is actually encoded data,
+have plain octets stored in C<$buf>, if this is actually encoded data,
you're going to need to encode it later, or use "getc" or other
-IO::Readable::Encoded methods.
+C<IO::Readable::Encoded> methods.
=back
@@ -125,28 +153,27 @@
This role provides unbuffered write access to the data stream.
-role IO::Writeable {
- has $.isWriteable;
+ role IO::Writeable {
+ has $.isWriteable;
+ method write($buf, Int $bytes --> Int)
+ }
- method Int write($buf, Int $bytes)
-}
-
-When the $.isWriteable is set, it tries to change the writeability of the
filehandle.
-This is not always possible, but can be done in a number of cases. IO::Socket
can remove
+When the C<$.isWriteable> is set, it tries to change the writeability of the
filehandle.
+This is not always possible, but can be done in a number of cases.
C<IO::Socket> can remove
writeability by calling shutdown(), for example.
=over
-=item method Int write($buf, Int $bytes)
+=item method write($buf, Int $bytes --> Int)
-Tries to write $bytes bytes of $buf. The actual number of bytes
+Tries to write C<$bytes> bytes of C<$buf>. The actual number of bytes
written is returned. It might return unthrown failures, to be
-specified by each IO implementation.
+specified by each C<IO> implementation.
-It is important to realize that this is "raw" write. $buf should
-contain plain octets that are going to be sent. If $buf contains
+It is important to realize that this is "raw" write. C<$buf> should
+contain plain octets that are going to be sent. If C<$buf> contains
encoded data, you should decode it first, or use "print" or other
-IO::Writeable::Encoded methods.
+C<IO::Writeable::Encoded> methods.
=back
@@ -154,7 +181,7 @@
=over
-=item method Bool eoi()
+=item method eoi( --> Bool)
EOI = End Of Input -- equivalent to End Of File, but applies to other kinds of
sockets as
well.
@@ -162,12 +189,12 @@
Returns true if it's the end of the input (ie. end of file or whatever),
returns false if
not, returns undef if we can't say for certain.
-=item method Bool seek(Int $position)
+=item method seek(Int $position --> Bool)
-Position this stream into $position. The meaning of this position is
+Position this stream into C<$position>. The meaning of this position is
always in "octets".
-=item method Int tell()
+=item method tell( --> Int)
Returns the current raw position in the stream in number of "octets".
@@ -180,11 +207,11 @@
=over
-=item method Bool flush()
+=item method flush( --> Bool)
Flushes the buffers associated with this object.
-=item method Bool autoflush() is rw
+=item method autoflush( --> Bool) is rw
Forces this object to keep its buffers empty
@@ -192,9 +219,9 @@
or print on the currently selected output channel.
Default is 0 (regardless of whether the channel is really buffered
by the system or not;
-$OUT_FH.autoflush tells you only whether you've asked Perl
+C<$OUT_FH.autoflush> tells you only whether you've asked Perl
explicitly to flush after each write).
-$*OUT will typically be line buffered if output is to the
+C<$*OUT> 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,
@@ -210,32 +237,30 @@
This role represents objects that depend on some external resource,
which means that data might not be available at request.
-role IO::Streamable does IO {...}
+ role IO::Streamable does IO {...}
=over
=item new()
- method IO::Streamable new(
- Bool :$NoOpen,
- );
+ method new( Bool :$NoOpen --> IO::Streamable) {...}
-Unless the NoOpen option is passed, an open will be done on the IO object when
it is
+Unless the NoOpen option is passed, an open will be done on the C<IO> object
when it is
created.
-=item method Bool blocking() is rw
+=item method blocking( --> Bool) is rw
-This allows the user to control wether this object should do a
+This allows the user to control whether this object should do a
blocking wait or immediatly return in the case of not having data
available.
=item uri
- method IO::Streamable uri(Str $uri) {...}
+ method uri(Str $uri --> IO::Streamable) {...}
This should be callable on the class, and act like a kind of "new()" function.
When given
-a URI, it returns an IO::Streamable of the appropriate type, and throws an
error when an
-inappropriate type is passed in. For example, calling
IO::File.uri('http://....') will
+a URI, it returns an C<IO::Streamable> of the appropriate type, and throws an
error when an
+inappropriate type is passed in. For example, calling
C<IO::File.uri('http://....')> will
throw an error (but will suggest using just uri('http://...') instead).
=back
@@ -246,9 +271,9 @@
=over
-=item method Str encoding() is rw
+=item method encoding( --> Str) is rw
-=item method Str locale() is rw
+=item method locale( --> Str) is rw
Encoding and locale are required for sane conversions.
@@ -257,16 +282,16 @@
=head2 IO::Readable::Encoded
This role provides encoded access to a readable data stream, implies
-IO::Encoded. Might imply IO::Buffered, but that's not a requirement.
+C<IO::Encoded>. Might imply C<IO::Buffered>, but that's not a requirement.
=over
-=item method Int input-line()
+=item method ins( --> Int)
-Returns the number of lines (records) that have been input.
+Returns the number of lines or records that have been input.
Now with cleaned-up localization usage.
-=item method Str input-line-separator() is rw
+=item method input-line-separator( --> Str) is rw
This regulates how "readline" behaves.
@@ -284,43 +309,46 @@
that the next input character belongs to the next paragraph,
even if it's a newline.
-Remember: the value of input-line-separator is a string, not a regex.
-awk has to be better for something. :-)
+You may also set it to a regular expression. The value of C<$/>
+will be (temporarily) set to the matched separator upon input,
+if you care about the contents of the separator.
-=item method Str input-field-separator() is rw
+=item method input-field-separator( --> Str) is rw
-This regulates how "readfield" behaves.
+[Deprecated.]
-=item method Str input-escape() is rw
+=item method input-escape( --> Str) is rw
-This allows the definition of a escape character, which should be used
-by readline and readfield.
+[Deprecated.]
-=item method Str readline()
+=item method readline( --> Str)
-Reads the stream before it finds a $.input-line-separator and
-returns it (including the separator). If $.input-escape is set, it
-should pay attention to that.
+Reads the stream before it finds a C<$.input-line-separator> and
+returns it (autochomped by default).
-=item method Str readfield()
+=item method readfield( --> Str)
-Reads the stream before it finds a $.input-field-separator and returns
-it (including the separator). If a readfield finds a
-$.input-line-separator it consumes the line separator, but returns
-undef. If $.input-escape is set, it should pay attention to that.
+[Deprecated. Use split or comb or an ILS regex.]
-=item method Str getc(Int $char? = 1)
+=item method getc(Int $chars = 1 --> Char)
-Reads the next $char character in the set $.encoding according to
-the $.locale, or the undefined value at end of file, or if there was
-an error (in the latter case C<$!> is set).
+Reads the next C<$char> character in the set C<$.encoding>,
+or C<Failure> at end of file, or if there was
+an error (in either case C<$!> is set). Note that this
+function cannot be used interactively as a C<readkey()> function, since under
+Unicode you can't tell the end of a grapheme until you
+see the beginning of the next one.
+[TODO someone needs to define something like C<readkey()> for terminal IO.
+Though most event-based programs will just want to feed keystrokes into the
+event queue.]
+
=back
=head2 IO::Writeable::Encoded
This role provides encoded access to a writeable data stream, implies
-IO::Encoded. Might imply IO::Buffered, but that's not a requirement.
+C<IO::Encoded>. Might imply C<IO::Buffered>, but that's not a requirement.
If these are called in their non-object form, they operate on C<$*OUT>, except
in the
case of warn(), which operates on C<$*ERR>. The form with leading dot prints
C<$_> to
@@ -328,75 +356,56 @@
=over
-=item method Int output-line()
+=item Int method outs()
-Returns the number of lines (records) that have been output so far.
+Returns the number of lines or records that have been output so far.
-=item method Str output-line-separator() is rw
+=item method output-line-separator( --> Str) is rw
-This regulates how say and print(%hash) behaves.
+This regulates how say behaves.
-=item method Str output-field-separator() is rw
+=item method output-field-separator( --> Str) is rw
-This regulates how print(@arr), say(@arr), print(%hash) and
-say(%hash) behave.
+[Deprecated.]
-=item method Str output-escape() is rw
+=item method output-escape( --> Str) is rw
-This allows the definition of a escape character, which should be used
-by say and print to preserve the line/field semantics.
+[Deprecated.]
-=item method Bool print(Str $str)
+=item method Str::print (IO $io = $*OUT --> Bool)
-=item method Bool say(Str $str)
+=item method Str::say (IO $io = $*OUT --> Bool)
-Sends $str to the data stream doing proper encoding conversions. Say
-sends an additional $.output-line-separator. This should also
-convert "\n" to the desired $.output-line-separator.
+=item method Array::print(IO $io = $*OUT --> Bool)
-=item method Bool print(Array @arr)
+=item method Array::say(IO $io = $*OUT --> Bool)
-=item method Bool say(Array @arr)
+=item method Hash::print(IO $io = $*OUT --> Bool)
-Sends each element of @arr separated by $.output-field-separator. Say
-should add an additional $.output-line-separator. If an element
-contains the $.output-line-separator or the
-$.output-field-seaparator and a $.output-escape is defined, it should
-do the escaping.
+=item method Hash::say(IO $io = $*OUT --> Bool)
-=item method Bool print(Hash %hash)
+Stringifies the invocant (if necessary) and then sends it to the output.
+C<say> should add an additional C<$.output-line-separator>.
-=item method Bool say(Hash %hash)
-Sends each pair of the hash separated by $.output-line-separator,
-with key and value separated by $.output-field-separator. If one of
-those contains a $.output-line-separator or a
-$.output-field-seaparator and $.output-escape is set, it should do the
-escaping.
+=item method print (*...@list --> Bool)
-=item our Bool method print (IO $self: *...@list)
+=item multi print (*...@list --> Bool)
-=item our Bool multi print (*...@list)
-=item our Bool method print (Str $self: IO $io)
+Stringifies each element, concatenates those strings, and sends the
+result to the output.
+Returns C<Bool::True> if successful, C<Failure> otherwise.
-Prints a string or a list of strings. Returns Bool::True if
-successful, Failure otherwise. The IO handle, if supplied, must be
-an object that supports I/O. Indirect objects in Perl 6 must always
-be followed by a colon, and any indirect object more complicated than
-a variable should be put into parentheses.
-
It is a compiler error to use a bare C<print> without arguments.
(However, it's fine if you have an explicit argument list that evaluates to
the empty list at runtime.)
-=item say our Bool method say (IO $self: *...@list)
+=item method say (*...@list --> Bool)
-=item our Bool multi say (*...@list)
+=item multi say (*...@list --> Bool)
-=item our Bool method say (Str $self: IO $io)
-
-This is identical to print() except that it auto-appends a newline after
+This is identical to print() except that it auto-appends the
C<output-line-separator> after
the final argument.
Was: print "Hello, world!\n";
@@ -405,52 +414,57 @@
As with C<print>, it is a compiler error to use a bare C<say> without
arguments.
-=item our Bool method printf (IO $self: Str $fmt, *...@list)
+=item method printf ($self: Str $fmt, *...@list --> Bool)
-=item our Bool multi printf (Str $fmt, *...@list)
+=item multi printf (Str $fmt, *...@list --> Bool)
-The function form works as in Perl 5 and always prints to $*OUT.
-The method form uses IO handles, not formats, as objects.
+The function form works as in Perl 5 and always prints to C<$*OUT>.
=back
+For any handle marked as textual, all these output calls intercept any newline
+character and translate it to the current C<output-line-separator> if it
+is defined as something other than newline. No such translation is done on
+binary handles, though you may still specify a record separator. In any case,
+escaping separators is the responsibility of the programmer.
+
=head2 IO::Closeable
This role indicates that this object can be closed.
=over
-=item method Bool close()
+=item method close( --> Bool)
Closes the file or pipe associated with the object.
-Returns True on success, but might return an unthrown failure.
-Returns true only if IO buffers are successfully flushed and closes the system
+Returns C<True> on success, but might return an unthrown C<Failure>.
+Returns true only if C<IO> buffers are successfully flushed and closes the
system
file descriptor.
-Unlike in Perl 5, an IO object is not a special symbol table entry
+Unlike in Perl 5, an C<IO> object is not a special symbol table entry
neither this object is available magically anywhere else. But as in
-Perl 5, unless stated otherwise, IO::Closeable objects always close
-themselves during destruction
+Perl 5, unless stated otherwise, C<IO::Closeable> objects always close
+themselves during destruction.
=back
=head2 IO::Socket
-role IO::Socket {
- has %.options;
-...
-}
+ role IO::Socket {
+ has %.options;
+ ...
+ }
-Accessing the %.options would on Unix be done with getsockopt/setsockopt.
+Accessing the C<%.options> would on Unix be done with
I<getsockopt(2)>/I<setsockopt(2)>.
=over
=item pair
- our List of IO method pair(Int $domain, Int $type, Int $protocol)
+ method pair(Int $domain, Int $type, Int $protocol --> List of IO)
-A wrapper for socketpair(2), returns a pair of IO objects representing the
+A wrapper for I<socketpair(2)>, returns a pair of C<IO> objects representing
the
reader and writer ends of the socket.
use Socket;
@@ -463,13 +477,13 @@
=item open
- method open()
+ method open()
- Does a bind() and a listen().
+Does a I<bind(2)> and a I<listen(2)>.
=item accept
- method IO::Socket accept()
+ method accept( --> IO::Socket)
=head2 IO::FileDescriptor
@@ -486,52 +500,52 @@
=head1 Classes
-=head2 IO::File
+=head2 IO::File
This does file input and output.
-class IO::File does IO::Streamable {
-...
-}
+ class IO::File does IO::Streamable {
+ ...
+ }
=over
=item new
- method new(
- FSNode :$FSNode,
- Str :$Filename,
- :$fd
- Bool :$NoOpen,
- :$Writeable,
- :$Readable
- );
+ method new(
+ FSNode :$FSNode,
+ Str :$Filename,
+ :$fd
+ Bool :$NoOpen,
+ :$Writeable,
+ :$Readable
+ );
-The FSNode, Filename and fd options are mutually exclusive. If "use portable"
is in
-effect, the Filename option throws an error; use an FSNode instead.
+The C<FSNode>, C<Filename> and C<fd> options are mutually exclusive. If
"C<use portable>" is in
+effect, the C<Filename> option throws an error; use an C<FSNode> instead.
-NoOpen is passed to IO::Streamable.new()
+C<NoOpen> is passed to C<IO::Streamable.new()>
Examples:
- # Read -- throws errors with 'use portable'
- $fobj = new IO::File(Filename => $filename);
+ # Read -- throws errors with 'use portable'
+ $fobj = new IO::File(Filename => $filename);
- # Write -- works with 'use portable'
- $fobj = new IO::File(
- FSNode => IO::FSNode.new(type => 'Unix', Filename => $filename),
- Writeable => 1
- );
+ # Write -- works with 'use portable'
+ $fobj = new IO::File(
+ FSNode => IO::FSNode.new(type => 'Unix', Filename => $filename),
+ Writeable => 1
+ );
- # Read using file descriptor
- $fobj = new IO::File(fd => $fd);
+ # Read using file descriptor
+ $fobj = new IO::File(fd => $fd);
-This final example associates an IO object with an already-open file
descriptor,
+This final example associates an C<IO> object with an already-open file
descriptor,
presumably passed in from the parent process.
=item open()
-This function opens a file that had the "NoOpen" option passed to the new()
method.
+This function opens a file that had the C<NoOpen> option passed to the C<new>
method.
=item IO.truncate
@@ -541,43 +555,43 @@
=back
-=head2 IO::FileSystem
+=head2 IO::FileSystem
This represents the filesystem.
-class IO::FileSystem does IO::Streamable {
- has Str $.fstype; # ext3, ntfs, vfat, reiserfs, etc
- has Str $.illegal-chars; # ie. /\x0
- has Int $.max-path;
-...
-}
+ class IO::FileSystem does IO::Streamable {
+ has Str $.fstype; # ext3, ntfs, vfat, reiserfs, etc
+ has Str $.illegal-chars; # ie. /\x0
+ has Int $.max-path;
+ ...
+ }
=over 4
=item glob
-Returns FSNode objects
+Returns C<FSNode> objects.
=item find
-Returns FSNode objects
+Returns C<FSNode> objects.
=item rename
=back
-=head2 IO::FSNode
+=head2 IO::FSNode
-class IO::FSNode {
- has Array of IO::FSNodeACL @.ACLs;
- has Hash of %.times;
-...
-}
+ class IO::FSNode {
+ has Array of IO::FSNodeACL @.ACLs;
+ has Hash of %.times;
+ ...
+ }
-The %times has keys that can be eg. ctime, Modification, and Access (and maybe
others on
-other operating systems), and the values are all Temporal::Instant objects.
+The C<%times> has keys that can be eg. C<ctime>, C<Modification>, and
C<Access> (and maybe others on
+other operating systems), and the values are all C<Temporal::Instant> objects.
-When .path() is implemented, it should return the path that this was opened
with.
+When C<.path> is implemented, it should return the path that this was opened
with.
=over 4
@@ -594,41 +608,41 @@
operator takes one argument, either a filename or a filehandle, and
tests the associated file to see if something is true about it.
-A Pair used as a pattern is treated as a file test.
+A C<Pair> used as a pattern is treated as a file test.
- :r File is readable by effective uid/gid.
- :w File is writable by effective uid/gid.
- :x File is executable by effective uid/gid.
- :o File is owned by effective uid.
+ :r File is readable by effective uid/gid.
+ :w File is writable by effective uid/gid.
+ :x File is executable by effective uid/gid.
+ :o File is owned by effective uid.
- :R File is readable by real uid/gid.
- :W File is writable by real uid/gid.
- :X File is executable by real uid/gid.
- :O File is owned by real uid.
+ :R File is readable by real uid/gid.
+ :W File is writable by real uid/gid.
+ :X File is executable by real uid/gid.
+ :O File is owned by real uid.
- :e File exists.
- :z File has zero size (is empty).
- :s File has nonzero size (returns size in bytes).
+ :e File exists.
+ :z File has zero size (is empty).
+ :s File has nonzero size (returns size in bytes).
- :f File is a plain file.
- :d File is a directory.
- :l File is a symbolic link.
- :p File is a named pipe (FIFO), or Filehandle is a pipe.
- :S File is a socket.
- :b File is a block special file.
- :c File is a character special file.
- :t Filehandle is opened to a tty.
+ :f File is a plain file.
+ :d File is a directory.
+ :l File is a symbolic link.
+ :p File is a named pipe (FIFO), or Filehandle is a pipe.
+ :S File is a socket.
+ :b File is a block special file.
+ :c File is a character special file.
+ :t Filehandle is opened to a tty.
- :u File has setuid bit set.
- :g File has setgid bit set.
- :k File has sticky bit set.
+ :u File has setuid bit set.
+ :g File has setgid bit set.
+ :k File has sticky bit set.
- :T File is an ASCII text file (heuristic guess).
- :B File is a "binary" file (opposite of :T).
+ :T File is an ASCII text file (heuristic guess).
+ :B File is a "binary" file (opposite of :T).
- :M Script start time minus file modification time, in days.
- :A Same for access time.
- :C Same for inode change time (Unix, may differ for other platforms)
+ :M Script start time minus file modification time, in days.
+ :A Same for access time.
+ :C Same for inode change time (Unix, may differ for other platforms)
The interpretation of the file permission operators C<:r>, C<:R>,
C<:w>, C<:W>, C<:x>, and C<:X> is by default based on:
@@ -650,7 +664,7 @@
Also note that, for the superuser on the local filesystems, the C<:r>,
C<:R>, C<:w>, and C<:W> tests always return 1, and C<:x> and C<:X> return 1
if any execute bit is set in the mode. Scripts run by the superuser
-may thus need to do a stat() to determine the actual mode of the file,
+may thus need to do a C<stat> to determine the actual mode of the file,
or temporarily set their effective uid to something else.
The C<:T> and C<:B> switches work as follows. The first block or so of the
@@ -658,7 +672,7 @@
characters with the high bit set. If too many strange characters (>30%)
are found, it's a C<:B> file; otherwise it's a C<:T> file. Also, any file
containing null in the first block is considered a binary file. If C<:T>
-or C<:B> is used on a filehandle, the current IO buffer is examined
+or C<:B> is used on a filehandle, the current C<IO> buffer is examined
rather than the first block. Both C<:T> and C<:B> return true on a null
file, or a file at EOF when testing a filehandle. Because you have to
read a file to do the C<:T> test, on most occasions you want to use a C<:f>
@@ -675,13 +689,13 @@
=item realpath
- method Str realpath();
+ method realpath( --> Str);
Gets the real path to the object, resolving softlinks/shortcuts, etc
=item === operator
- method infix:<===>(Str $filename);
+ method infix:<===>(Str $filename);
Test whether the specified filename is the same file as this file. On a Unix
system,
this would presumably be done by comparing inode numbers or something.
@@ -690,45 +704,45 @@
This is called automatically on object creation.
-multi method new(Array of Str :@PathElements);
-multi method new(Str :$Type, Str :$Path, Str :$Create);
-multi method new(Str :$Path);
+ multi method new(Array of Str :@PathElements);
+ multi method new(Str :$Type, Str :$Path, Str :$Create);
+ multi method new(Str :$Path);
-This last throws an error if "use portable" pragma is used.
+This last throws an error if "C<use portable>" pragma is used.
-If the "Create" option is passed in, and the node doesn't exist in the
filesystem, it
-attempts to create the node; this can be used for "mkdir", "link", and similar
+If the C<Create> option is passed in, and the node doesn't exist in the
filesystem, it
+attempts to create the node; this can be used for I<mkdir>, I<link>, and
similar
functionality.
Examples:
- $fsnode = new IO::FSNode(PathElements => ['home', 'wayland']);
- $fsnode = new IO::FSNode(Type => 'Unix', Path => '/home/wayland');
- $fsnode = new IO::FSNode(Path => '/home/wayland'); # portability error
+ $fsnode = new IO::FSNode(PathElements => ['home', 'wayland']);
+ $fsnode = new IO::FSNode(Type => 'Unix', Path => '/home/wayland');
+ $fsnode = new IO::FSNode(Path => '/home/wayland'); # portability error
=item delete
-This deletes the FSNode from the filesystem. If the node has children, it
throws an error
-unless the "Recursive" option is specified. Returns the number of nodes
deleted.
+This deletes the C<FSNode> from the filesystem. If the node has children, it
throws an error
+unless the C<Recursive> option is specified. Returns the number of nodes
deleted.
=back
-=head2 IO::FSNodeACL
+=head2 IO::FSNodeACL
This is a basic abstraction; for better control, use the operating-system
specific
interfaces, over which this is a thin veneer.
-class IO::FSNodeACL {
- has Str $.type; # "User", "Group", "Everyone", ???
- has Str $.id; # username or groupname; unused for $type eq
"Everyone"
- has %.permissions;
- # Unsupported values may (or may not) throw
- # UnsupportedPermission when set or read
- has IO::FSNode $.owningObject;
-...
-}
+ class IO::FSNodeACL {
+ has Str $.type; # "User", "Group", "Everyone", ???
+ has Str $.id; # username or groupname; unused for $type eq "Everyone"
+ has %.permissions;
+ # Unsupported values may (or may not) throw
+ # UnsupportedPermission when set or read
+ has IO::FSNode $.owningObject;
+ ...
+ }
-The permissions used in %permissions are:
+The permissions used in C<%permissions> are:
=over
@@ -750,51 +764,76 @@
=item Default
An ACL of User,fred,Default sets the user "fred" to be the owner of the file.
This can be
-done with groups too. Work on Unix, at least.
+done with groups too. Works on Unix, at least.
=back
-The $.owningObject attribute of FSNodeACL shows what the ACL is set on. On a
+The C<$.owningObject> attribute of C<FSNodeACL> shows what the ACL is set on.
On a
Windows system, this can be a parent directory, as permissions are inherited.
-=head2 IO::FileNode
+=head2 IO::FileNode
- role IO::FileNode does IO::FSNode {
-...
- }
+ role IO::FileNode does IO::FSNode {
+ ...
+ }
=over
-=item our List multi method lines (IO $handle:) is export;
+=item lines
-=item our List multi lines (Str $filename);
+ method lines ($handle:
+ Bool :$bin = False,
+ Str :$enc = "Unicode",
+ Any :$nl = "\n",
+ Bool :$chomp = True,
+ --> List
+ ) is export
-Returns all the lines of a file as a (lazy) List regardless of context.
-See also C<slurp>.
+ multi lines (Str $filename,
+ Bool :$bin = False,
+ Str :$enc = "Unicode",
+ Any :$nl = "\n",
+ Bool :$chomp = True,
+ --> List
+ )
-=item our Item multi method slurp (IO $handle: *%opts) is export;
+Returns all the lines of a file as a C<List> regardless of context.
+See also C<slurp>. Note that lists are lazy by default, but you
+can always ask for C<eager lines>.
-=item our Item multi slurp (Str $filename, *%opts);
+=item slurp
-Slurps the entire file into a Str or Buf regardless of context.
-(See also C<lines>.) Whether a Str or Buf is returned depends on
-the options.
+ method slurp ($handle:
+ Bool :$bin = False,
+ Str :$enc = "Unicode",
+ --> Str|Buf
+ ) is export
+ multi slurp (Str $filename
+ Bool :$bin = False,
+ Str :$enc = "Unicode",
+ --> Str|Buf
+ )
+Slurps the entire file into a C<Str> (or C<Buf> if C<:bin>) regardless of
context.
+(See also C<lines>.)
+
=back
-=head2 IO::DirectoryNode
+=head2 IO::DirectoryNode
- role IO::DirectoryNode does IO::FSNode {
-...
- }
+ role IO::DirectoryNode does IO::FSNode {
+ ...
+ }
=item open
- $dir.open();
+ $dir.open(
+ Str :$enc = "Unicode",
+ );
-Opens a directory for processing, if the new() method was passed the NoOpen
option.
+Opens a directory for processing, if the C<new> method was passed the
C<NoOpen> option.
Makes the directory looks like
-a list of autochomped lines, so just use ordinary IO operators after the open.
+a list of autochomped lines, so just use ordinary C<IO> operators after the
open.
=item rmdir FILENAME
X<rmdir> X<rd> X<directory, remove>
@@ -802,39 +841,39 @@
=item rmdir
Deletes the directory specified by FILENAME if that directory is
-empty. If it succeeds it returns true, otherwise it returns false and
-sets C<$!> (errno). If FILENAME is omitted, uses C<$_>.
+empty. If it succeeds it returns true, otherwise it returns C<Failure> and
+sets C<$!> (errno).
=head2 IO::LinkNode
- role IO::LinkNode does IO::FSNode {
-...
- }
+ role IO::LinkNode does IO::FSNode {
+ ...
+ }
=item new
Creates a new link in the filesystem.
- IO::LinkNode.new(
- Name => '/home/wayland/symlink.txt'
- Target => '/home/wayland/realfile.txt',
- Type => 'Hard', # Default is Symbolic
- );
+ IO::LinkNode.new(
+ Name => '/home/wayland/symlink.txt'
+ Target => '/home/wayland/realfile.txt',
+ Type => 'Hard', # Default is Symbolic
+ );
Reads in the previously created symlink.
- $link = IO::LinkNode.new(
- Name => '/home/wayland/symlink.txt',
- );
- print $link.target; # prints /home/wayland/realfile.txt
+ $link = IO::LinkNode.new(
+ Name => '/home/wayland/symlink.txt',
+ );
+ print $link.target; # prints /home/wayland/realfile.txt
-Neither of these is "use portable" compatible.
+Neither of these is "C<use portable>" compatible.
-=head2 IO::Socket::TCP
+=head2 IO::Socket::TCP
-class IO::Socket::TCP does IO::Socket does IO::Streamable {
-...
-}
+ class IO::Socket::TCP does IO::Socket does IO::Streamable {
+ ...
+ }
=over
@@ -848,32 +887,33 @@
=item new
- method IO::Socket::TCP new(
- Str :$RemoteHost, Str :$RemotePort,
- Str :$LocalHost, Str :$LocalPort,
- Bool :$Blocking,
- Bool :$NoOpen
- );
+ method new(
+ Str :$RemoteHost, Str :$RemotePort,
+ Str :$LocalHost, Str :$LocalPort,
+ Bool :$Blocking,
+ Bool :$NoOpen
+ --> IO::Socket::TCP
+ ) {...}
-The NoOpen option is passed to IO::Streamable.new()
+The C<NoOpen> option is passed to C<IO::Streamable.new()>.
IPv6 is supported.
=item open
- method open()
+ method open()
-If it's not an IO::Listening, it does a connect().
+If it's not an C<IO::Listening>, it does a C<connect()>.
It's intended for the case where the creation of the object didn't do one.
-=item method Int read($buf is rw, Int $bytes)
+=item method read($buf is rw, Int $bytes --> Int)
-Does a recv().
+Does a I<recv(2)>.
-=item method Int write($buf, Int $bytes)
+=item method write($buf, Int $bytes --> Int)
-Does a send().
+Does a I<send(2)>.
=item IO.getpeername
@@ -883,63 +923,53 @@
=head2 IO::Pipe
-class IO::Pipe does IO::Streamable {
-...
-}
+ class IO::Pipe does IO::Streamable {
+ ...
+ }
-May also do IO::Readable and IO::Writable, depending on opening method.
+May also do C<IO::Readable> and C<IO::Writable>, depending on opening method.
=over
=item close()
If the file handle came from a piped open, C<close> will additionally
-return false if one of the other system calls involved fails, or if the
-program exits with non-zero status. (If the only problem was that the
-program exited non-zero, C<$!> will be set to C<0>.) Closing a pipe
+return C<Failure> (aliased to C<$!>) if one of the other system calls involved
fails, or if the
+program exits with non-zero status. The exception object will contain any
+pertinent informatoin. Closing a pipe
also waits for the process executing on the pipe to complete, in case you
want to look at the output of the pipe afterwards, and
-implicitly puts the exit status value of that command into C<$!>.
+implicitly puts the exit status value into the C<Failure> object if necessary.
-=item Pipe.to
+=item IO::Pipe.to
- our IO method to(Str $command, *%opts)
+ method to(Str $command, *%opts --> Bool)
+ method to(Str *...@command, *%opts --> Bool)
-Opens a one-way pipe writing to $command. IO redirection for
-stderr is specified with :err(IO) or :err<Str>. Other IO redirection
+Opens a one-way pipe writing to C<$command>. C<IO> redirection for
+stderr is specified with C<:err(IO)> or C<< :err<Str> >>. Other C<IO>
redirection
is done with feed operators. XXX how to specify "2>&1"?
-=item Pipe.from
+=item IO::Pipe.from
- our IO method from(Str $command, *%opts)
+ method from(Str $command, *%opts --> Bool)
+ method from(Str *...@command, *%opts --> Bool)
-Opens a one-way pipe reading from $command. IO redirection for
-stderr is specified with :err(IO) or :err<Str>. Other IO redirection
+Opens a one-way pipe reading from $command. C<IO> redirection for
+stderr is specified with C<:err(IO)> or C<< :err<Str> >>. Other C<IO>
redirection
is done with feed operators. XXX how to specify "2>&1"?
-=item Pipe.pair
+=item IO::Pipe.pair
- our List of IO method pair()
+ method pair(--> List of IO::Pipe)
-A wrapper for pipe(2), returns a pair of IO objects representing the
+A wrapper for I<pipe(2)>, returns a pair of C<IO> objects representing the
reader and writer ends of the pipe.
- ($r, $w) = Pipe.pair;
+ ($r, $w) = IO::Pipe.pair;
=back
-=head1 Calls that operate on the default IO handle
-
-=over
-
-=item close()
-
-=item open()
-
-...
-
-=back
-
=head1 OS-specific classes
=head2 Unix
@@ -948,7 +978,7 @@
=item chown
- our Int multi chown ($uid = -1, $gid = -1, *...@files)
+ multi chown ($uid = -1, $gid = -1, *...@files --> Int)
Changes the owner (and group) of a list of files. The first
two elements of the list must be the numeric uid and gid, in
@@ -1004,7 +1034,7 @@
=item IO.stat
- $node.stat(Type => 'Link'); # Type => Link does an lstat instead
+ $node.stat(Bool :$link); # :link does an lstat instead
Returns a stat buffer. If the lstat succeeds, the stat buffer evaluates
to true, and additional file tests may be performed on the value. If
@@ -1013,18 +1043,18 @@
=head2 IO::POSIX
-Indicates that this object can perform standard posix IO
-operations. It implies IO::Readable and IO::Writeable.
+Indicates that this object can perform standard posix C<IO>
+operations. It implies C<IO::Readable> and C<IO::Writeable>.
=over
-=item method IO dup()
+=item method dup( --> IO)
=item has Bool $.blocking is rw
-=item method Bool flock(:$r,:$w)
+=item method flock(:$r,:$w --> Bool)
-=item method Bool funlock()
+=item method funlock( --> Bool)
=item ...
@@ -1032,14 +1062,16 @@
=head2 IO::File::Windows
-role IO::File::Windows does IO::File {
- method open(Bool :$BinaryMode) {...}
-}
+ role IO::File::Windows does IO::File {
+ method open(Bool :$BinaryMode) {...}
+ }
=item open()
-Takes the BinaryMode option to open the file in binary mode.
+Takes the C<BinaryMode> option to open the file in binary mode.
+[XXX bogus, now under Unicode *all* systems must distinguish text from binary.]
+
=head1 Unfiled
=over 4
@@ -1052,9 +1084,9 @@
=item prompt
- our Str prompt (Str $prompt)
+ multi prompt (Str $prompt --> Str)
- Should there be an IO::Interactive role?
+Should there be an IO::Interactive role?
=item Str.readpipe
@@ -1072,19 +1104,19 @@
=item IO.eof
-Gone, see IO::Endable
+Gone, see C<IO::Endable>.
=item IO.fileno
-See IO::FileDescriptor
+See C<IO::FileDescriptor>.
=item lstat
-Use stat() with the Type => 'Link' option.
+Use C<stat> with the C<:link> option.
=item IO.name
-Changed to .path(), but we haven't gotten around to specifying this on all of
them.
+Changed to C<.path>, but we haven't gotten around to specifying this on all of
them.
The C<.name> method returns the name of the file/socket/uri the handle
was opened with, if known. Returns undef otherwise. There is no
@@ -1100,7 +1132,7 @@
=item IO.shutdown()
-Gone, see IO::Socket.close(), $IO::Readable.isReadable, and
$IO::Writeable.isWriteable
+Gone, see C<IO::Socket.close()>, C<$IO::Readable.isReadable>, and
C<$IO::Writeable.isWriteable>
=item socketpair
@@ -1108,15 +1140,15 @@
=item IO.sysread
-Gone, see IO::Readable.read()
+Gone, see C<IO::Readable.read()>.
=item IO.syswrite
-Gone, see IO::Writeable.read()
+Gone, see C<IO::Writeable.read()>.
=item utime
-Gone, see %IO::FSNode.times.
+Gone, see C<IO::FSNode.times>.
=back
@@ -1125,4 +1157,4 @@
Please post errors and feedback to perl6-language. If you are making
a general laundry list, please separate messages by topic.
-=cut
+=for vim:set expandtab sw=4:
