Author: lwall
Date: 2010-03-06 02:41:57 +0100 (Sat, 06 Mar 2010)
New Revision: 29951
Modified:
docs/Perl6/Spec/S32-setting-library/IO.pod
Log:
[S32/IO.pod] put back :s, remove :z, :T, :B, :M, :A, :C
note that these all end up calling methods on IO, not strings
Modified: docs/Perl6/Spec/S32-setting-library/IO.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/IO.pod 2010-03-06 01:18:04 UTC (rev
29950)
+++ docs/Perl6/Spec/S32-setting-library/IO.pod 2010-03-06 01:41:57 UTC (rev
29951)
@@ -22,8 +22,8 @@
Created: 19 Feb 2009 extracted from S29-functions.pod; added stuff from
S16-IO later
- Last Modified: 11 Dec 2009
- Version: 10
+ Last Modified: 5 Mar 2010
+ Version: 11
The document is a draft.
@@ -693,10 +693,6 @@
$Encoding parameter is passed in (see Path for further discussion of
encoding).
-=item filebytes
-
-Looks up the passed file name and returns its length in bytes.
-
=item glob
Returns C<Path> objects. Path.Encoding is set to $?ENC unless the
@@ -987,7 +983,7 @@
:O File is owned by real uid.
:e File exists.
- :z File has zero size (is empty).
+ :s File has a size > 0 bytes
:f File is a plain file.
:d File is a directory.
@@ -1002,13 +998,25 @@
: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).
+Each of these is redirected (by C<Pair.ACCEPTS>) to the
+corresponding method name on an IO object. (These methods are not
+defined on bare strings). Each test returns a boolean, and may be
+negated with a C<!> after the colon. They maybe ANDed and ORed using
+junctional logic. In fact, this is the primary reason for writing
+them as a pattern match; if you only want one test, you could just call
+the individual IO method directly and more efficiently. In any case,
+you must call the C<.s> method to return the file's size in bytes.
- :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)
+There is no <.z> method, so just write C<:!s> to test a file for zero size.
+Likewise, just call C<.s> directly if you actually want to know the file's
+size, since C<~~ :s> only returns a boolean.
+The C<.T> and C<.B> methods will be replaced by some filetype guessing
+methods more appropriate to the age of Unicode. There are likely methods
+to return the various ages of the file corresponding to Perl 5's C<-M>,
+C<-A>, and C<-C> times, but they make no sense as booleans, so also call
+those methods directly (whatever they end up being named).
+
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:
@@ -1032,25 +1040,10 @@
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
-file is examined for odd characters such as strange control codes or
-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 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>
-against the file first, as in C<next unless $file ~~ :f && $file ~~ :T >.
-
You can test multiple features using junctions:
- if -$filename ~~ :r & :w & :x {...}
+ if $filename.IO ~~ :r & :w & :x {...}
-Or pass multiple tests together in OO style:
-
- if $filename.TEST(:e,:x) {...}
-
=back
=head2 IO::ACL
