Author: ruoso
Date: 2009-02-16 17:57:10 +0100 (Mon, 16 Feb 2009)
New Revision: 25359
Modified:
docs/Perl6/Spec/S16-io.pod
Log:
[spec/S16] reorganizing the roles a bit, to make it less confusing. Now we
should discuss IO::Socket, IO::Pipe and other very OS-specific matters
Modified: docs/Perl6/Spec/S16-io.pod
===================================================================
--- docs/Perl6/Spec/S16-io.pod 2009-02-16 15:16:11 UTC (rev 25358)
+++ docs/Perl6/Spec/S16-io.pod 2009-02-16 16:57:10 UTC (rev 25359)
@@ -65,7 +65,7 @@
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,
-you're going to need to encode it later, or use a "getc" or other
+you're going to need to encode it later, or use "getc" or other
IO::Readable::Encoded methods.
=back
@@ -89,38 +89,24 @@
=back
-=head2 IO::FileDescriptor
+=head2 IO::Seekable
-This role indicates that this object actually represents an open file
-descriptor in the os level.
-
=over
-=item has int $.fileno
+=item method Bool eoi()
-File descriptors are always native integers, conforming to C89.
+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.
-=back
+=item method Bool seek(Int $position)
-=head2 IO::Closeable
+Position this stream into $position. The meaning of this position is
+always in "octets".
-This role indicates that this object can be closed.
+=item method Int tell()
-=over
+Returns the current raw position in the stream in number of "octets".
-=item method Bool close()
-
-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
@@ -128,46 +114,31 @@
Indicates that this object performs buffering. The management of the
buffer is completely implementation specific.
+=over
+
=item method Bool flush()
Flushes the buffers associated with this object.
-=item has Bool $.autoflush is rw
+=item method Bool autoflush() is rw
Forces this object to keep its buffers empty
-=head2 IO::POSIX
-
-Indicates that this object can perform standard posix IO
-operations. It implies IO::Readable and IO::Writeable.
-
-=over
-
-=item method IO dup()
-
-=item has Bool $.blocking is rw
-
-=item method Bool flock(:$r,:$w)
-
-=item method Bool funlock()
-
-=item ...
-
=back
-=head2 IO::Seekable
+=head2 IO::Streamable
+This role represents objects that depend on some external resource,
+which means that data might not be available at request.
+
=over
-=item method Bool eoi()
+=item method Bool blocking() is rw
-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.
+This allows the user to control wether this object should do a
+blocking wait or immediatly return in the case of not having data
+available.
-=item IO.seek
-
-=item IO.tell
-
=back
=head2 IO::Encoded
@@ -176,9 +147,10 @@
=over
-=item has $.encoding is rw
-=item has $.locale is rw
+=item method Str encoding() is rw
+=item method Str locale() is rw
+
Encoding and locale are required for sane conversions.
=back
@@ -190,31 +162,31 @@
=over
-=item has $.input_record_separator is rw
+=item method Str input_record_separator() is rw
This regulates how "readline" behaves.
-=item has $.input_field_separator is rw
+=item method Str input_field_separator() is rw
This regulates how "readfield" behaves.
-=item has $.input_escape is rw
+=item method Str input_escape() is rw
This allows the definition of a escape character, which should be used
by readline and readfield.
-=item method Str readline
+=item method Str readline()
Reads the stream before it finds a $.input_record_separator and
returns it (including the separator). If $.input_escape is set, it
should pay attention to that.
-=item method Str readfield
+=item method Str readfield()
Reads the stream before it finds a $.input_field_separator and returns
it (including the separator). If a readfield finds a
-$.input_record_separator it skips it and reads the next field. If
-$.input_escape is set, it should pay attention to that.
+$.input_record_separator it consumes the record separator, but returns
+undef. If $.input_escape is set, it should pay attention to that.
=item method Str getc(Int $length? = 1)
@@ -222,18 +194,16 @@
the $.locale, or the undefined value at end of file, or if there was
an error (in the latter case C<$!> is set).
-=item IO.lines
+=item our List multi method lines (IO $handle:) is export;
- our List multi method lines (IO $handle:) is export;
- our List multi lines (Str $filename);
+=item our List multi lines (Str $filename);
Returns all the lines of a file as a (lazy) List regardless of context.
See also C<slurp>.
-=item IO.slurp
+=item our Item multi method slurp (IO $handle: *%opts) is export;
- our Item multi method slurp (IO $handle: *%opts) is export;
- our Item multi slurp (Str $filename, *%opts);
+=item our Item multi slurp (Str $filename, *%opts);
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
@@ -252,21 +222,22 @@
=over
-=item has $.output_record_separator is rw
+=item method Str output_record_separator() is rw
This regulates how say and print(%hash) behaves.
-=item has $.output_field_separator is rw
+=item method Str output_field_separator() is rw
This regulates how print(@arr), say(@arr), print(%hash) and
say(%hash) behave.
-=item has $.output_escape is rw
+=item method Str output_escape() is rw
This allows the definition of a escape character, which should be used
by say and print to preserve the record/field semantics.
=item method Bool print(Str $str)
+
=item method Bool say(Str $str)
Sends $str to the data stream doing proper encoding conversions. Say
@@ -274,6 +245,7 @@
convert "\n" to the desired $.output_record_separator.
=item method Bool print(Array @arr)
+
=item method Bool say(Array @arr)
Sends each element of @arr separated by $.output_field_separator. Say
@@ -283,6 +255,7 @@
do the escaping.
=item method Bool print(Hash %hash)
+
=item method Bool say(Hash %hash)
Sends each pair of the hash separated by $.output_record_separator,
@@ -291,12 +264,12 @@
$.output_field_seaparator and $.output_escape is set, it should do the
escaping.
-=item print
+=item our Bool method print (IO $self: *...@list)
- our Bool method print (IO $self: *...@list)
- our Bool multi print (*...@list)
- our Bool method print (Str $self: IO $io)
+=item our Bool multi print (*...@list)
+=item 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
@@ -307,15 +280,11 @@
(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)
-=item say
+=item our Bool multi say (*...@list)
- our Bool method say (IO $self: *...@list)
- our Bool multi say (*...@list)
- our Bool method say (Str $self: IO $io)
+=item our Bool method say (Str $self: IO $io)
This is identical to print() except that it auto-appends a newline after
the final argument.
@@ -326,36 +295,46 @@
As with C<print>, it is a compiler error to use a bare C<say> without
arguments.
-=item printf
+=item our Bool method printf (IO $self: Str $fmt, *...@list)
- our Bool method printf (IO $self: Str $fmt, *...@list)
- our Bool multi printf (Str $fmt, *...@list)
+=item 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.
-=item warn LIST
+=back
-=item Str.warn
+=head2 IO::FileDescriptor
-Prints a warning just like Perl 5, except that it is always sent to
-the object in $*DEFERR, which is just standard error ($*ERR).
+This role indicates that this object actually represents an open file
+descriptor in the os level.
+=over
+
+=item method int fileno()
+
+File descriptors are always native integers, conforming to C89.
+
=back
+=head2 IO::Closeable
-=head2 IO::Openable
+This role indicates that this object can be closed.
-This role implies that the object can be connected to, or listened on.
+=over
-=over 4
+=item method Bool close()
-=item open
+Closes the file or pipe associated with the object.
- method Bool open();
+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.
-Attempts to open the handle. Depending on the implementation, this could be
an open()
-call, a connect(), a listen(), or something similar.
+Unlike in Perl 5, an 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
=back
@@ -375,16 +354,6 @@
(should IO::Socket.close() call shutdown, instead of having a different name?)
-=back
-
-=head2 IO::Streamable
-
-role IO::Streamable does IO::POSIX does IO::Openable does IO::Closeable {
-...
-}
-
-=over
-
=item IO.accept
=item IO.bind
@@ -722,6 +691,25 @@
=back
+=head2 IO::POSIX
+
+Indicates that this object can perform standard posix IO
+operations. It implies IO::Readable and IO::Writeable.
+
+=over
+
+=item method IO dup()
+
+=item has Bool $.blocking is rw
+
+=item method Bool flock(:$r,:$w)
+
+=item method Bool funlock()
+
+=item ...
+
+=back
+
=head2 IO::Pipe
class IO::Pipe does IO::Streamable {
@@ -805,6 +793,8 @@
=head1 Removed functions
+=over
+
=item IO.eof
Gone, see IO::Endable
@@ -821,6 +811,8 @@
Gone, see Socket.pair
+=back
+
=head1 Additions
Please post errors and feedback to perl6-language. If you are making
