Author: wayland
Date: 2009-02-14 06:38:34 +0100 (Sat, 14 Feb 2009)
New Revision: 25328
Modified:
docs/Perl6/Spec/S16-io.pod
Log:
S16-io: Reorganised everything, grouping things together a bit better. This is
only a
draft; otherwise I'd be a lot more careful :).
Specifically, I've:
- Taken some of the stuff that was spread throughout the document, and
put it in
with its associated role
- Created sections for a lot of the different classes we'll need
It still needs a lot of work.
Modified: docs/Perl6/Spec/S16-io.pod
===================================================================
--- docs/Perl6/Spec/S16-io.pod 2009-02-14 05:28:12 UTC (rev 25327)
+++ docs/Perl6/Spec/S16-io.pod 2009-02-14 05:38:34 UTC (rev 25328)
@@ -82,8 +82,17 @@
=item method Bool close()
-returns True on success, but might return an unthrown failure.
+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
+file descriptor.
+
+You don't have to close IO if you are immediately going to do
+another C<open> on it, because C<open> will close it for you. (See
+C<open>.) However, an explicit C<close> on an input file resets the line
+counter (C<$.>), while the implicit close done by C<open> does not.
+
=back
=head2 IO::Buffered
@@ -184,6 +193,15 @@
Reads the next character in the set $.encoding according to the
$.locale.
+=item getc
+
+ our Bool method getc (IO $self: Bool :async)
+
+Returns the next character from the input stream attached to IO,
+or the undefined value at end of file, or if there was an error (in
+the latter case C<$!> is set). The C<:async> flag lets the call
+return an undefined value if no character is immediately available.
+
=cut
=head2 IO::Writeable::Encoded
@@ -218,12 +236,165 @@
$.output_field_seaparator and $.output_escape is set, it should do the
escaping.
+=item print
+
+ our Bool method print (IO $self: *...@list)
+ our Bool multi print (*...@list)
+ our Bool method print (Str $self: IO $io)
+
+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.
+
+If IO is omitted, prints to C<$*DEFOUT>, which is aliased to C<$*OUT>
+when the program starts but may be temporarily or permanently rebound to
+some other file handle. The form with leading dot prints C<$_> to C<$*DEFOUT>
+unless an explicit filehandle is supplied.
+
+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.)
+
+There is are no variables corresponding to Perl 5's C<$,> and
+C<$\> variables. Use C<join> to interpose separators; use filehandle
+properties to change line endings.
+
+=item say
+
+ our Bool method say (IO $self: *...@list)
+ our Bool multi say (*...@list)
+ our Bool method say (Str $self: IO $io)
+
+This is identical to print() except that it auto-appends a newline after
+the final argument.
+
+ Was: print "Hello, world!\n";
+ Now: say "Hello, world!";
+
+As with C<print>, it is a compiler error to use a bare C<say> without
+arguments.
+
+=item printf
+
+ our Bool method printf (IO $self: Str $fmt, *...@list)
+ our Bool multi printf (Str $fmt, *...@list)
+
+The function form works as in Perl 5 and always prints to $*DEFOUT.
+The method form uses IO handles, not formats, as objects.
+
=back
+=head2 IO::Openable
+
+This role implies that the object can be connected to, or listened on.
+
+=over 4
+
+=item open
+
+ method Bool open();
+
+Attempts to open the handle. Depending on the implementation, this could be
an open()
+call, a connect(), a listen(), or something similar.
+
+=back
+
+=head2 IO::Socket
+
+role IO::Socket does IO::POSIX does IO::Openable does IO::Closeable {
+...
+}
+
+=over
+
+=item IO.accept
+
+=item IO.bind
+
+=item Socket.pair
+
+ our List of IO method pair(Int $domain, Int $type, Int $protocol)
+
+A wrapper for socketpair(2), returns a pair of IO objects representing the
+reader and writer ends of the socket.
+
+ use Socket;
+ ($r, $w) = Socket.pair(AF_UNIX, SOCK_STREAM, PF_UNSPEC);
+
+
+=back
+
=head1 Filehandles, files, and directories
=over 4
+=item IO.fcntl
+
+Available only as a handle method.
+
+=item IO.ioctl
+
+Available only as a handle method.
+
+=item IO.name
+
+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
+corresponding C<name()> function.
+
+=item syscall
+
+=item sysopen
+
+=item umask
+
+=item utime
+
+=back
+
+=head1 Classes
+
+=head2 IO::File
+
+This does file input and output.
+
+class IO::File does IO::POSIX does IO::Closeable does IO::Openable {
+...
+}
+
+=over
+
+=item init
+
+ method init(String $filename, $options?);
+ method init(Int $fd);
+
+ # Read
+ $fobj = new IO::File($filename);
+
+ # Write
+ $fobj = new IO::File($filename, :w);
+
+ # Read using file descriptor
+ $fobj = new IO::File($fd);
+
+Associate an IO object with an already-open file descriptor,
+presumably passed in from the parent process.
+
+=back
+
+=head2 IO::FileSystem
+
+This reads directories, worries about ownership and permissions, and the like.
+
+class IO::FileSystem does IO::POSIX does IO::Closeable does IO::Openable {
+...
+}
+
+=over 4
+
=item IO ~~ :X
X<:r>X<:w>X<:x>X<:o>X<:R>X<:W>X<:X>X<:O>X<:e>X<:z>X<:s>X<:f>X<:d>X<:l>X<:p>
X<:S>X<:b>X<:c>X<:t>X<:u>X<:g>X<:k>X<:T>X<:B>X<:M>X<:A>X<:C>
@@ -371,51 +542,10 @@
$mode = '0o644'; chmod $mode, 'foo'; # this is better
$mode = 0o644; chmod $mode, 'foo'; # this is best
-=item close IO
-
-=item IO.close
-
-Closes the file or pipe associated with the file handle, returning
-true only if IO buffers are successfully flushed and closes the system
-file descriptor. Closes the currently selected filehandle if the
-argument is omitted.
-
-You don't have to close IO if you are immediately going to do
-another C<open> on it, because C<open> will close it for you. (See
-C<open>.) However, an explicit C<close> on an input file resets the line
-counter (C<$.>), while the implicit close done by C<open> does not.
-
-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
-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<$!>.
-
-=item connect
-
- my $fh = connect($hostname, 80);
-
-Attempts to connect to a remote host and returns an IO handle if successful.
-The call fails with an exception if it cannot connect.
-
-=item IO.fcntl
-
-Available only as a handle method.
-
=item glob
-=item IO.ioctl
-
-Available only as a handle method.
-
=item link
-=item IO.listen
-
-Available only as a handle method.
-
=item lstat
Returns a stat buffer. If the lstat succeeds, the stat buffer evaluates
@@ -425,27 +555,6 @@
=item mkdir
-=item IO.name
-
-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
-corresponding C<name()> function.
-
-=item open
-
- # Read
- my $fh = open($filename);
-
- # Write
- my $fh = open($filename, :w);
-
-=item IO.fdopen
-
- our IO method fdopen(Int $fd)
-
-Associate an IO object with an already-open file descriptor,
-presumably passed in from the parent process.
-
=item IO::Dir::open EXPR
my $dir = IO::Dir::open('.');
@@ -477,12 +586,6 @@
=item symlink
-=item syscall
-
-=item sysopen
-
-=item umask
-
=item unlink LIST
X<unlink> X<delete> X<remove> X<rm>
@@ -499,71 +602,86 @@
It is an error to use bare C<unlink> without arguments.
-=item utime
+=back
+=head2 IO::Socket::INET
+
+class IO::Socket::INET does IO::Socket {
+...
+}
+
+=over
+
+=item init
+
+ method Bool init($RemoteHost, $RemotePort, $LocalHost?, $LocalPort?);
+
+=item open($Listen?);
+
+If $Listen is 0, it does a connect(). If $Listen is 1, it does a connect()
and a
+listen(). If $Listen is 2, it does a listen(), but no connect().
+
+=item IO.getpeername
+
+=item /[get|set][host|net|proto|serv|sock].*/
+
=back
-=head1 Input and Output
+=head2 IO::Pipe
-=over 4
+class IO::Pipe does IO::POSIX does IO::Closeable does IO::Openable {
+...
+}
-=item getc
+May also do IO::Readable and IO::Writable, depending on opening method.
- our Bool method getc (IO $self: Bool :async)
+=over
-Returns the next character from the input stream attached to IO,
-or the undefined value at end of file, or if there was an error (in
-the latter case C<$!> is set). The C<:async> flag lets the call
-return an undefined value if no character is immediately available.
+=item close()
-=item print
+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
+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<$!>.
- our Bool method print (IO $self: *...@list)
- our Bool multi print (*...@list)
- our Bool method print (Str $self: IO $io)
+=item Pipe.to
-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.
+ our IO method to(Str $command, *%opts)
-If IO is omitted, prints to C<$*DEFOUT>, which is aliased to C<$*OUT>
-when the program starts but may be temporarily or permanently rebound to
-some other file handle. The form with leading dot prints C<$_> to C<$*DEFOUT>
-unless an explicit filehandle is supplied.
+Opens a one-way pipe writing to $command. IO redirection for
+stderr is specified with :err(IO) or :err<Str>. Other IO redirection
+is done with feed operators. XXX how to specify "2>&1"?
-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 Pipe.from
-There is are no variables corresponding to Perl 5's C<$,> and
-C<$\> variables. Use C<join> to interpose separators; use filehandle
-properties to change line endings.
+ our IO method from(Str $command, *%opts)
-=item say
+Opens a one-way pipe reading from $command. IO redirection for
+stderr is specified with :err(IO) or :err<Str>. Other IO redirection
+is done with feed operators. XXX how to specify "2>&1"?
- our Bool method say (IO $self: *...@list)
- our Bool multi say (*...@list)
- our Bool method say (Str $self: IO $io)
+=item Pipe.pair
-This is identical to print() except that it auto-appends a newline after
-the final argument.
+ our List of IO method pair()
- Was: print "Hello, world!\n";
- Now: say "Hello, world!";
+A wrapper for pipe(2), returns a pair of IO objects representing the
+reader and writer ends of the pipe.
-As with C<print>, it is a compiler error to use a bare C<say> without
-arguments.
+ ($r, $w) = Pipe.pair;
-=item printf
+=back
- our Bool method printf (IO $self: Str $fmt, *...@list)
- our Bool multi printf (Str $fmt, *...@list)
+=head1 Calls that operate on the default IO handle
-The function form works as in Perl 5 and always prints to $*DEFOUT.
-The method form uses IO handles, not formats, as objects.
+=over
+=item close()
+
+=item open()
+
=back
=head1 Unfiled
@@ -574,18 +692,10 @@
=item IO.flock
-=item IO.getpeername
-
=item IO.eof
-=item IO.accept
-
-=item /[get|set][host|net|proto|serv|sock].*/
-
=item alarm
-=item IO.bind
-
=item IO.binmode
=item IO.lines
@@ -596,28 +706,16 @@
Returns all the lines of a file as a (lazy) List regardless of context.
See also C<slurp>.
-=item pipe
-
-Gone, see Pipe.pair
-
=item prompt
our Str prompt (Str $prompt)
-=item IO.read
-
-=item IO.readline
-
=item Str.readpipe
=item IO.recv
=item IO.seek
-=item select(both)
-
-Gone. (Note: for subsecond sleep, just use sleep with a fractional argument.)
-
=item IO.send
=item IO.setsockopt
@@ -635,10 +733,6 @@
=item socket
-=item socketpair
-
-Gone, see Socket.pair
-
=item IO.sysread
=item IO.sysseek
@@ -656,44 +750,22 @@
Prints a warning just like Perl 5, except that it is always sent to
the object in $*DEFERR, which is just standard error ($*ERR).
-=item Pipe.to
+=back
- our IO method to(Str $command, *%opts)
+=head1 Removed functions
-Opens a one-way pipe writing to $command. IO redirection for
-stderr is specified with :err(IO) or :err<Str>. Other IO redirection
-is done with feed operators. XXX how to specify "2>&1"?
+=item pipe
-=item Pipe.from
+Gone, see Pipe.pair
- our IO method from(Str $command, *%opts)
+=item select(both)
-Opens a one-way pipe reading from $command. IO redirection for
-stderr is specified with :err(IO) or :err<Str>. Other IO redirection
-is done with feed operators. XXX how to specify "2>&1"?
+Gone. (Note: for subsecond sleep, just use sleep with a fractional argument.)
-=item Pipe.pair
+=item socketpair
- our List of IO method pair()
+Gone, see Socket.pair
-A wrapper for pipe(2), returns a pair of IO objects representing the
-reader and writer ends of the pipe.
-
- ($r, $w) = Pipe.pair;
-
-=item Socket.pair
-
- our List of IO method pair(Int $domain, Int $type, Int $protocol)
-
-A wrapper for socketpair(2), returns a pair of IO objects representing the
-reader and writer ends of the socket.
-
- use Socket;
- ($r, $w) = Socket.pair(AF_UNIX, SOCK_STREAM, PF_UNSPEC);
-
-
-=back
-
=head1 Additions
Please post errors and feedback to perl6-language. If you are making
