Revision 29951

Date:
2010/03/06 01:41:57
Author:
lwall
Revision 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
Files:

Legend:

 
Added
 
Removed
 
Modified

  • docs/Perl6/Spec/S32-setting-library/IO.pod

     
    22 22
    23 23 Created: 19 Feb 2009 extracted from S29-functions.pod; added stuff from S16-IO later
    24 24
    25 Last Modified: 11 Dec 2009
    26 Version: 10
    25 Last Modified: 5 Mar 2010
    26 Version: 11
    27 27
    28 28 The document is a draft.
    29 29
    … …  
    693 693 $Encoding parameter is passed in (see Path for further discussion of
    694 694 encoding).
    695 695
    696 =item filebytes
    697
    698 Looks up the passed file name and returns its length in bytes.
    699
    700 696 =item glob
    701 697
    702 698 Returns C<Path> objects. Path.Encoding is set to $?ENC unless the
    … …  
    987 983 :O File is owned by real uid.
    988 984
    989 985 :e File exists.
    990 :z File has zero size (is empty).
    986 :s File has a size > 0 bytes
    991 987
    992 988 :f File is a plain file.
    993 989 :d File is a directory.
    … …  
    1002 998 :g File has setgid bit set.
    1003 999 :k File has sticky bit set.
    1004 1000
    1005 :T File is an ASCII text file (heuristic guess).
    1006 :B File is a "binary" file (opposite of :T).
    1001 Each of these is redirected (by C<Pair.ACCEPTS>) to the
    1002 corresponding method name on an IO object. (These methods are not
    1003 defined on bare strings). Each test returns a boolean, and may be
    1004 negated with a C<!> after the colon. They maybe ANDed and ORed using
    1005 junctional logic. In fact, this is the primary reason for writing
    1006 them as a pattern match; if you only want one test, you could just call
    1007 the individual IO method directly and more efficiently. In any case,
    1008 you must call the C<.s> method to return the file's size in bytes.
    1007 1009
    1008 :M Script start time minus file modification time, in days.
    1009 :A Same for access time.
    1010 :C Same for inode change time (Unix, may differ for other platforms)
    1010 There is no <.z> method, so just write C<:!s> to test a file for zero size.
    1011 Likewise, just call C<.s> directly if you actually want to know the file's
    1012 size, since C<~~ :s> only returns a boolean.
    1011 1013
    1014 The C<.T> and C<.B> methods will be replaced by some filetype guessing
    1015 methods more appropriate to the age of Unicode. There are likely methods
    1016 to return the various ages of the file corresponding to Perl 5's C<-M>,
    1017 C<-A>, and C<-C> times, but they make no sense as booleans, so also call
    1018 those methods directly (whatever they end up being named).
    1019
    1012 1020 The interpretation of the file permission operators C<:r>, C<:R>,
    1013 1021 C<:w>, C<:W>, C<:x>, and C<:X> is by default based on:
    1014 1022
    … …  
    1032 1040 may thus need to do a C<stat> to determine the actual mode of the file,
    1033 1041 or temporarily set their effective uid to something else.
    1034 1042
    1035 The C<:T> and C<:B> switches work as follows. The first block or so of the
    1036 file is examined for odd characters such as strange control codes or
    1037 characters with the high bit set. If too many strange characters (>30%)
    1038 are found, it's a C<:B> file; otherwise it's a C<:T> file. Also, any file
    1039 containing null in the first block is considered a binary file. If C<:T>
    1040 or C<:B> is used on a filehandle, the current C<IO> buffer is examined
    1041 rather than the first block. Both C<:T> and C<:B> return true on a null
    1042 file, or a file at EOF when testing a filehandle. Because you have to
    1043 read a file to do the C<:T> test, on most occasions you want to use a C<:f>
    1044 against the file first, as in C<next unless $file ~~ :f && $file ~~ :T >.
    1045
    1046 1043 You can test multiple features using junctions:
    1047 1044
    1048 if -$filename ~~ :r & :w & :x {...}
    1045 if $filename.IO ~~ :r & :w & :x {...}
    1049 1046
    1050 Or pass multiple tests together in OO style:
    1051
    1052 if $filename.TEST(:e,:x) {...}
    1053
    1054 1047 =back
    1055 1048
    1056 1049 =head2 IO::ACL