Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

document IO::Path; move more stuff around

  • Loading branch information...
commit 8082097aa44af485d7b0652d29927b9c5c1407c6 1 parent c2eea90
Moritz Lenz moritz authored
Showing with 211 additions and 309 deletions.
  1. +211 −309 S32-setting-library/IO.pod
520 S32-setting-library/IO.pod
View
@@ -58,7 +58,7 @@ subclasses of C<IO::Path>.
File tests are performed through C<IO::Path> objects.
-=head2 Functions
+=head1 Functions
=over 4
@@ -160,8 +160,20 @@ other error in opening, writing, or closing.
=back
+=head1 IO Types
+
+=head2 IO
+
+ role IO { };
+
+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::Handle
+ class IO::Handle does IO { ... }
+
A handle of a file, pipe or anything else that supports reading or
writing like a file.
@@ -180,7 +192,18 @@ X<print>
method print (IO::Handle:D: *@LIST --> Bool)
multi print (*@LIST --> Bool)
-See below for details.
+Stringifies each element, concatenates those strings, and sends the
+result to the output.
+Returns C<Bool::True> if successful, C<Failure> otherwise.
+
+The compiler will warn you if 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.)
+
+ print; # warns
+ if $_ { print } # warns
+ if $_ { print() } # ok, but does nothing
+ if $_ { print () } # ok, but does nothing
=item say
X<say>
@@ -188,7 +211,15 @@ X<say>
method say (IO::Handle:D: *@LIST --> Bool)
multi say (*@LIST --> Bool)
-See below for details.
+This is identical to print() except that it stringifies its arguments by calling
+C<.gist> on them and auto-appends the C<output-line-separator> after the final
+argument.
+
+ Was: print "Hello, world!\n";
+ Now: say "Hello, world!";
+
+As with C<print>, the compiler will warn you if you use a bare C<say> without
+arguments.
=item printf
X<printf>
@@ -196,7 +227,7 @@ X<printf>
method printf (Str $fmt, *@LIST --> Bool)
multi printf (IO::Handle:D: Str $fmt, *@LIST --> Bool)
-See below for details.
+Output through C<Str.sprintf>. See L<S32::Str> for details.
=item write
@@ -229,223 +260,38 @@ Returns C<True> if the handle is opened to a tty.
Returns C<True> if the handle is opened to a pipe.
-=back
-
-=head1 IO::FileTests
-
- role IO::FileTests { ... }
-
-Provides ways to inspect a file or path without opening it.
-
-If you apply that role to a class, that class must provide a C<path>
-method which C<IO::FileTests>' method will call to obtain the path to
-test. This C<path> method must return a C<Str:D>.
-
-The methods are typically only one letter long (for now; perl 5 tradition
-strikes) and are summarized in the following table:
-
- M Test performed
- = ==============
- r $.path is readable by effective uid/gid.
- w $.path is writable by effective uid/gid.
- x $.path is executable by effective uid/gid.
- o $.path is owned by effective uid.
+=item eof
- R $.path is readable by real uid/gid.
- W $.path is writable by real uid/gid.
- X $.path is executable by real uid/gid.
- O $.path is owned by real uid.
+ method eof() returns Bool:D
- e $.path exists.
- s $.path has a size > 0 bytes
+Returns C<True> if the handle is exhausted.
- f $.path is a plain file.
- d $.path is a directory.
- l $.path is a symbolic link.
- p $.path is a named pipe (FIFO)
- S $.path is a socket.
- b $.path is a block special file.
- c $.path is a character special file.
-
- u $.path has setuid bit set.
- g $.path has setgid bit set.
- k $.path has sticky bit set.
-
-
-=head1 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 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;
- method read(Int $bytes --> Buf)
- }
-
-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.
-
-=over
-
-=item method read(Int $bytes --> Buf)
-
-Tries to read C<$bytes> bytes and return it as a C<Buf>. The C<Buf> may be
-shorter than the actual specified number of C<$bytes>.
-
-This is "raw" read. You're going to
-have plain octets stored in C<$buf>. If what you want is a C<Str>,
-you're going to need to C<.decode> it after C<read>ing, or use "getc" or other
-C<IO::Readable::Encoded> methods.
-
-=back
+=item seek
-=head2 IO::Writeable
-
-This role provides unbuffered write access to the data stream.
-
- role IO::Writeable {
- has $.isWriteable;
- method write(Buf $buf --> Int)
- }
-
-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
-
-
-=head2 IO::Seekable
-
-=over
-
-=item method eoi( --> Bool)
-
-EOI = End Of Input -- equivalent to End Of File, but applies to other kinds of sockets as
-well.
-
-Returns true if it's the end of the input (i.e. end of file or whatever), returns false if
-not, fails if we can't say for certain.
-
-=item method seek(Int $position --> Bool)
+method seek(Int $position, Int $whence --> Bool)
Position this stream into C<$position>. The meaning of this position is
always in "octets".
-=item method tell( --> Int)
-
-Returns the current raw position in the stream in number of "octets".
-
-=back
-
-=head2 IO::Buffered
-
-Indicates that this object performs buffering. The management of the
-buffer is completely implementation specific.
-
-=over
-
-=item method flush( --> Bool)
-
-Flushes the buffers associated with this object.
-
-=item method autoflush( --> Bool) is rw
-
-Forces this object to keep its buffers empty
-
-If set to nonzero, forces a flush right away and after every write
-or print on the currently selected output channel.
-Default is 0 (regardless of whether the channel is really buffered
-by the system or not;
-C<$OUT_FH.autoflush> tells you only whether you've asked Perl
-explicitly to flush after each write).
-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,
-such as when you are running a Perl program under rsh
-and want to see the output as it's happening.
-This has no effect on input buffering.
-
-
-=back
-
-=head2 IO::Streamable
-
-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 {...}
-
-=over
-
-=item new()
-
- method new(
- Bool :$NoOpen,
- Bool :$Blocking,
- --> IO::Streamable
- ) {...}
-
-Unless the NoOpen option is passed, an open will be done on the C<IO> object when it is
-created.
-
-If blocking is passed in, .blocking() is called (see below).
-
-=item method blocking( --> Bool) is rw
-
-This allows the user to control whether this object should do a
-blocking wait or immediately return in the case of not having data
-available.
-
-=item 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 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
-
-=head2 IO::Encoded
-
-This is a generic role for encoded data streams.
-
-=over
-
-=item method encoding( --> Str) is rw
+Fails if the handle is not seekable.
-=item method locale( --> Str) is rw
+TODO: make $whence an Enum
-Encoding and locale are required for sane conversions.
+=item tell
-=back
+ method tell() returns Int:D:
-=head2 IO::Readable::Encoded
+Returns the current raw position in the stream in number of "octets".
-This role provides encoded access to a readable data stream, implies
-C<IO::Encoded>. Might imply C<IO::Buffered>, but that's not a requirement.
+=item ins
-=over
+ method ins( --> Int)
-=item method ins( --> Int)
+Returns the number of lines that have been read with C<get>.
-Returns the number of lines or records that have been input.
-Now with cleaned-up localization usage.
+=item input-line-separator
-=item method input-line-separator( --> Str) is rw
+ method input-line-separator( --> Str) is rw
This regulates how "get" and "lines" behave.
@@ -467,152 +313,116 @@ 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 input-field-separator( --> Str) is rw
-
-[Deprecated.]
-
-=item method input-escape( --> Str) is rw
-
-[Deprecated.]
-
-=item method get( --> Str)
-
-Reads the stream before it finds a C<$.input-line-separator> and
-returns it (autochomped by default).
-
-=item method readfield( --> Str)
-
-[Deprecated. Use split or comb or an ILS regex.]
-
-=item method getc( --> Char)
-
-Reads the next 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.]
-
-=item multi method comb ( Regex $matcher, Int $limit = * )
+=item close
-Reads everything into a string, and calls C<.comb> on it with the same
-parameters. See C<Str::comb>.
+Closes the handle. Fails on error.
=back
-=head2 IO::Writeable::Encoded
-
-This role provides encoded access to a writeable data stream, implies
-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
-the appropriate handle unless C<$_> happens to be a filehandle.
-
-=over
-
-=item Int method outs()
-
-Returns the number of lines or records that have been output so far.
-
-=item method output-line-separator( --> Str) is rw
+=head1 IO::FileTests
-This regulates how say behaves.
+ role IO::FileTests does IO { ... }
-=item method output-field-separator( --> Str) is rw
+Provides ways to inspect a file or path without opening it.
-[Deprecated.]
+If you apply that role to a class, that class must provide a C<path>
+method which C<IO::FileTests>' method will call to obtain the path to
+test. This C<path> method must return a C<Str:D>.
-=item method output-escape( --> Str) is rw
+The methods are typically only one letter long (for now; perl 5 tradition
+strikes) and are summarized in the following table:
-[Deprecated.]
+ M Test performed
+ = ==============
+ r $.path is readable by effective uid/gid.
+ w $.path is writable by effective uid/gid.
+ x $.path is executable by effective uid/gid.
+ o $.path is owned by effective uid.
-=item method Str::print (IO $io = $*OUT --> Bool)
+ R $.path is readable by real uid/gid.
+ W $.path is writable by real uid/gid.
+ X $.path is executable by real uid/gid.
+ O $.path is owned by real uid.
-=item method Str::say (IO $io = $*OUT --> Bool)
+ e $.path exists.
+ s $.path has a size > 0 bytes
-=item method Array::print(IO $io = $*OUT --> Bool)
+ f $.path is a plain file.
+ d $.path is a directory.
+ l $.path is a symbolic link.
+ p $.path is a named pipe (FIFO)
+ S $.path is a socket.
+ b $.path is a block special file.
+ c $.path is a character special file.
-=item method Array::say(IO $io = $*OUT --> Bool)
+ u $.path has setuid bit set.
+ g $.path has setgid bit set.
+ k $.path has sticky bit set.
-=item method Hash::print(IO $io = $*OUT --> Bool)
+TODO: methods created, accessed, modified
-=item method Hash::say(IO $io = $*OUT --> Bool)
+=head2 IO::Path
-Stringifies the invocant (if necessary) and then sends it to the output.
-C<say> should add an additional C<$.output-line-separator>.
+ class IO::Path is Cool does IO::FileTest { }
+Holds a path of a file or directory. The path is generally divided
+into three parts, the I<file system>, I<directory> and I<base name>.
-=item method print (*@LIST --> Bool)
+On Windows, the file system is a drive letter like C<C:>. Relative paths
+never have a file system part. On UNIX-based systems, the file system part
+is empty.
-=item multi print (*@LIST --> Bool)
+The base name is name of the file or directory that the IO::Path object
+represents, and the directory is the part of the path leading up to the base
+name.
+ path file system directory base name
+ /usr/bin/gvim /usr/bin gvim
+ /usr/bin/ /usr bin
+ C:\temp\f.txt C: temp f.txt
-Stringifies each element, concatenates those strings, and sends the
-result to the output.
-Returns C<Bool::True> if successful, C<Failure> otherwise.
+=over 4
-The compiler will warn you if 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 path
- print; # warns
- if $_ { print } # warns
- if $_ { print() } # ok, but does nothing
- if $_ { print () } # ok, but does nothing
+Returns the path (file system, directory and base name joined together) as
+a string.
-=item method say (*@LIST --> Bool)
+=item filesystem
-=item multi say (*@LIST --> Bool)
+Returns the file system part of the path
-This is identical to print() except that it stringifies its arguments by calling
-C<.gist> on them and auto-appends the C<output-line-separator> after the final
-argument.
+=item directory
- Was: print "Hello, world!\n";
- Now: say "Hello, world!";
+Returns the directory part of the path
-As with C<print>, the compiler will warn you if you use a bare C<say> without
-arguments.
+=item basename
-=item method printf ($self: Str $fmt, *@LIST --> Bool)
+Returns the base name part of the path
-=item multi printf (Str $fmt, *@LIST --> Bool)
+=item Str
-The function form works as in Perl 5 and always prints to C<$*OUT>.
+Stringifies to the base name.
=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::File
-=head2 IO::Closeable
+ class IO::File is IO::Path { ... }
-This role indicates that this object can be closed.
+Represents a path that is known to be a plain file (not a directory), at
+least at the time when the object was created.
-=over
+=head2 IO::Dir
-=item method close( --> Bool)
+ class IO::Dir is IO::Path { ... }
-Closes the file or pipe associated with the object.
+Represents a path that is known to be a directory, at
+least at the time when the object was created.
-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.
+=head1 Here Be Dragons
-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, C<IO::Closeable> objects always close
-themselves during destruction.
-
-=back
+Everything below this point hasn't been reviewed properly
=head2 IO::Socket
@@ -1406,6 +1216,98 @@ a general laundry list, please separate messages by topic.
Old methods are moved here if it's not clear how they fit into the current
picture. If nobody comes up with a good solution, they are removed.
+=head2 IO::Buffered
+
+Indicates that this object performs buffering. The management of the
+buffer is completely implementation specific.
+
+=over
+
+=item method flush( --> Bool)
+
+Flushes the buffers associated with this object.
+
+=item method autoflush( --> Bool) is rw
+
+Forces this object to keep its buffers empty
+
+If set to nonzero, forces a flush right away and after every write
+or print on the currently selected output channel.
+Default is 0 (regardless of whether the channel is really buffered
+by the system or not;
+C<$OUT_FH.autoflush> tells you only whether you've asked Perl
+explicitly to flush after each write).
+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,
+such as when you are running a Perl program under rsh
+and want to see the output as it's happening.
+This has no effect on input buffering.
+
+
+=back
+
+=head2 IO::Streamable
+
+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 {...}
+
+=over
+
+=item new()
+
+ method new(
+ Bool :$NoOpen,
+ Bool :$Blocking,
+ --> IO::Streamable
+ ) {...}
+
+Unless the NoOpen option is passed, an open will be done on the C<IO> object when it is
+created.
+
+If blocking is passed in, .blocking() is called (see below).
+
+=item method blocking( --> Bool) is rw
+
+This allows the user to control whether this object should do a
+blocking wait or immediately return in the case of not having data
+available.
+
+=item 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 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
+
+=head2 IO::Encoded
+
+This is a generic role for encoded data streams.
+
+=over
+
+=item method encoding( --> Str) is rw
+
+=item method locale( --> Str) is rw
+
+Encoding and locale are required for sane conversions.
+
+=back
+
+=head2 IO::Readable::Encoded
+
+This role provides encoded access to a readable data stream, implies
+C<IO::Encoded>. Might imply C<IO::Buffered>, but that's not a requirement.
+
+=over
+
=over 4
=item uri
Please sign in to comment.
Something went wrong with that request. Please try again.