Changeset 15167 for docs/Perl6/Spec

Show
Ignore:
Timestamp:
02/02/07 10:19:16 (22 months ago)
Author:
lwall
Message:

More .
More whitespace around .
Several eval'd tests of .:X syntax

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • docs/Perl6/Spec/IO.pod

    r13649 r15167  
    2626=over 4 
    2727 
    28 =item -X 
     28=item :X 
    2929 
    3030=over 8 
    3131 
    32 =item -X FILEHANDLE 
    33 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> 
    34 X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C> 
    35  
    36 =item -X EXPR 
    37  
    38 =item -X 
    39  
    40   -X $file   
    41   $file.'-X' 
     32=item FILEHANDLE ~~ :X 
     33X<: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> 
     34X<:S>X<:b>X<:c>X<:t>X<:u>X<:g>X<:k>X<:T>X<:B>X<:M>X<:A>X<:C> 
     35 
     36=item EXPR ~~ :X 
     37 
     38  $file.:X 
     39  $file ~~ :X 
     40  $file.TEST(:X) 
    4241 
    4342A file test, where X is one of the letters listed below.  This unary 
    4443operator takes one argument, either a filename or a filehandle, and 
    4544tests the associated file to see if something is true about it. 
    46 The argument may not be omitted unless it is C<$_>, in which case you must 
    47 use the C<.'-X'> form. 
    48  
    49 All file test operators return a stat buffer that also carries a "cumulative 
    50 success" boolean (or file size in the case of C<-s>) so that tests may be stacked: 
    51  
    52     -r -w $filename 
    53  
    54 or applied to existing stat buffers: 
    55  
    56     $b = stat($filename); 
    57     if -r $b {...} 
    58  
    59 Despite the funny 
    60 names, precedence is the same as any other named unary operator, and 
    61 the argument may be parenthesized like any other unary operator.  The 
    62 operator may be any of: 
    63  
    64     -r  File is readable by effective uid/gid. 
    65     -w  File is writable by effective uid/gid. 
    66     -x  File is executable by effective uid/gid. 
    67     -o  File is owned by effective uid. 
    68  
    69     -R  File is readable by real uid/gid. 
    70     -W  File is writable by real uid/gid. 
    71     -X  File is executable by real uid/gid. 
    72     -O  File is owned by real uid. 
    73  
    74     -e  File exists. 
    75     -z  File has zero size (is empty). 
    76     -s  File has nonzero size (returns size in bytes). 
    77  
    78     -f  File is a plain file. 
    79     -d  File is a directory. 
    80     -l  File is a symbolic link. 
    81     -p  File is a named pipe (FIFO), or Filehandle is a pipe. 
    82     -S  File is a socket. 
    83     -b  File is a block special file. 
    84     -c  File is a character special file. 
    85     -t  Filehandle is opened to a tty. 
    86  
    87     -u  File has setuid bit set. 
    88     -g  File has setgid bit set. 
    89     -k  File has sticky bit set. 
    90  
    91     -T  File is an ASCII text file (heuristic guess). 
    92     -B  File is a "binary" file (opposite of -T). 
    93  
    94     -M  Script start time minus file modification time, in days. 
    95     -A  Same for access time. 
    96     -C  Same for inode change time (Unix, may differ for other platforms) 
    97  
    98 The interpretation of the file permission operators C<-r>, C<-R>, 
    99 C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode 
     45 
     46A Pair used as a pattern is treated as a file test. 
     47 
     48    :r  File is readable by effective uid/gid. 
     49    :w  File is writable by effective uid/gid. 
     50    :x  File is executable by effective uid/gid. 
     51    :o  File is owned by effective uid. 
     52 
     53    :R  File is readable by real uid/gid. 
     54    :W  File is writable by real uid/gid. 
     55    :X  File is executable by real uid/gid. 
     56    :O  File is owned by real uid. 
     57 
     58    :e  File exists. 
     59    :z  File has zero size (is empty). 
     60    :s  File has nonzero size (returns size in bytes). 
     61 
     62    :f  File is a plain file. 
     63    :d  File is a directory. 
     64    :l  File is a symbolic link. 
     65    :p  File is a named pipe (FIFO), or Filehandle is a pipe. 
     66    :S  File is a socket. 
     67    :b  File is a block special file. 
     68    :c  File is a character special file. 
     69    :t  Filehandle is opened to a tty. 
     70 
     71    :u  File has setuid bit set. 
     72    :g  File has setgid bit set. 
     73    :k  File has sticky bit set. 
     74 
     75    :T  File is an ASCII text file (heuristic guess). 
     76    :B  File is a "binary" file (opposite of :T). 
     77 
     78    :M  Script start time minus file modification time, in days. 
     79    :A  Same for access time. 
     80    :C  Same for inode change time (Unix, may differ for other platforms) 
     81 
     82The interpretation of the file permission operators C<:r>, C<:R>, 
     83C<:w>, C<:W>, C<:x>, and C<:X> is by default based solely on the mode 
    10084of the file and the uids and gids of the user.  There may be other 
    10185reasons you can't actually read, write, or execute the file.  Such 
    … …  
    10488executable formats. 
    10589 
    106 Also note that, for the superuser on the local filesystems, the C<-r>, 
    107 C<-R>, C<-w>, and C<-W> tests always return 1, and C<-x> and C<-X> return 1 
     90Also note that, for the superuser on the local filesystems, the C<:r>, 
     91C<:R>, C<:w>, and C<:W> tests always return 1, and C<:x> and C<:X> return 1 
    10892if any execute bit is set in the mode.  Scripts run by the superuser 
    10993may thus need to do a stat() to determine the actual mode of the file, 
    … …  
    11498When under the C<use filetest 'access'> the above-mentioned filetests 
    11599will test whether the permission can (not) be granted using the 
    116 access() family of system calls.  Also note that the C<-x> and C<-X> may 
     100access() family of system calls.  Also note that the C<:x> and C<:X> may 
    117101under this pragma return true even if there are no execute permission 
    118102bits set (nor any extra execute permission ACLs).  This strangeness is 
    … …  
    120104documentation for the C<filetest> pragma for more information. 
    121105 
    122 Note that C<-s/a/b/> does not do a negated substitution.  Saying 
    123 C<-exp($foo)> still works as expected, however--only single letters 
    124 following a minus are interpreted as file tests. 
    125  
    126 The C<-T> and C<-B> switches work as follows.  The first block or so of the 
     106The C<:T> and C<:B> switches work as follows.  The first block or so of the 
    127107file is examined for odd characters such as strange control codes or 
    128108characters with the high bit set.  If too many strange characters (>30%) 
    129 are found, it's a C<-B> file; otherwise it's a C<-T> file.  Also, any file 
    130 containing null in the first block is considered a binary file.  If C<-T> 
    131 or C<-B> is used on a filehandle, the current IO buffer is examined 
    132 rather than the first block.  Both C<-T> and C<-B> return true on a null 
     109are found, it's a C<:B> file; otherwise it's a C<:T> file.  Also, any file 
     110containing null in the first block is considered a binary file.  If C<:T> 
     111or C<:B> is used on a filehandle, the current IO buffer is examined 
     112rather than the first block.  Both C<:T> and C<:B> return true on a null 
    133113file, or a file at EOF when testing a filehandle.  Because you have to 
    134 read a file to do the C<-T> test, on most occasions you want to use a C<-f> 
    135 against the file first, as in C<next unless -f $file && -T $file>. 
    136  
    137 The return value of a test is both a boolean and a stat buffer. So you can say: 
    138  
    139   if -r -w -x $filename {...} 
    140  
    141 Or chain tests together in OO style: 
     114read a file to do the C<:T> test, on most occasions you want to use a C<:f> 
     115against the file first, as in C<next unless $file ~~ :f  && $file ~~ :T >. 
     116 
     117You can test multiple features using junctions: 
     118 
     119  if -$filename ~~ :r & :w & :x {...} 
     120 
     121Or pass multiple tests together in OO style: 
    142122  
    143   if $filename.'-e'.'-x' {...} 
     123  if $filename.TEST(:e,:x) {...} 
    144124 
    145125=item chown