Skip to content
This repository
Browse code

move &slurp and &spurt to functions; move file tests to IO::FileTests

  • Loading branch information...
commit c2eea90e22987f4f05f5960d47ef01ae16221495 1 parent 1aa555e
Moritz Lenz authored

Showing 1 changed file with 111 additions and 127 deletions. Show diff stats Hide diff stats

  1. 238  S32-setting-library/IO.pod
238  S32-setting-library/IO.pod
Source Rendered
@@ -110,6 +110,54 @@ scope by declaring:
110 110
 
111 111
     only note(*@) {}
112 112
 
  113
+=item slurp
  114
+
  115
+    multi slurp (IO $fh = $*ARGFILES,
  116
+        Bool :$bin = False,
  117
+        Str  :$enc = "Unicode",
  118
+        --> Str|Buf
  119
+    )
  120
+    multi slurp (Str $filename,
  121
+        Bool :$bin = False,
  122
+        Str  :$enc = "Unicode",
  123
+        --> Str|Buf
  124
+    )
  125
+
  126
+Slurps the entire file into a C<Str> (or C<Buf> if C<:bin>) regardless of context.
  127
+(See also C<lines>.)
  128
+
  129
+The routine will C<fail> if the file does not exist, or is a directory.
  130
+
  131
+=item spurt
  132
+
  133
+    multi spurt (IO $fh,
  134
+        Str   $contents,
  135
+        Str  :$enc = $?ENC,
  136
+        Bool :append = False,
  137
+    )
  138
+    multi spurt (IO $fh,
  139
+        Buf   $contents,
  140
+        Bool :append = False,
  141
+    )
  142
+    multi spurt (Str $filename,
  143
+        Str   $contents,
  144
+        Str  :$enc = $?ENC,
  145
+        Bool :append = False,
  146
+    )
  147
+    multi spurt (Str $filename,
  148
+        Buf   $contents,
  149
+        Bool :append = False,
  150
+    )
  151
+
  152
+Opens the file for writing, dumps the contents, and closes the file.
  153
+
  154
+This routine will C<fail> if the file exists, unless the C<:append> flag is
  155
+set, in which case it will instead add the given contents at the end of the
  156
+file.
  157
+
  158
+The routine will also C<fail> with the corresponding exception if there was any
  159
+other error in opening, writing, or closing.
  160
+
113 161
 =back
114 162
 
115 163
 =head2 IO::Handle
@@ -150,7 +198,9 @@ X<printf>
150 198
 
151 199
 See below for details.
152 200
 
153  
-=item method write(IO::Handle:D: Buf $buf --> Int)
  201
+=item  write
  202
+
  203
+    method write(IO::Handle:D: Buf $buf --> Int)
154 204
 
155 205
 Tries to write C<$buf>. The actual number of bytes
156 206
 written is returned. It might return unthrown failures, to be
@@ -160,8 +210,68 @@ This is "raw" write. C<$buf> contains plain octets. If you want to C<write>
160 210
 a C<Str>, you should C<.encode> it first, or use "print" or other
161 211
 C<IO::Writeable::Encoded> methods.
162 212
 
  213
+=item slurp
  214
+
  215
+    method slurp()
  216
+
  217
+Reads all the remaining contents of the handle into a C<Str> (or a C<Buf>
  218
+if  the handle was opened with C<:bin>).
  219
+
  220
+=item t
  221
+
  222
+    method t() returns Bool:D
  223
+
  224
+Returns C<True> if the handle is opened to a tty.
  225
+
  226
+=item p
  227
+
  228
+    method p() returns Bool:D
  229
+
  230
+Returns C<True> if the handle is opened to a pipe.
  231
+
163 232
 =back
164 233
 
  234
+=head1 IO::FileTests
  235
+
  236
+    role IO::FileTests { ... }
  237
+
  238
+Provides ways to inspect a file or path without opening it.
  239
+
  240
+If you apply that role to a class, that class must provide a C<path>
  241
+method which C<IO::FileTests>' method will call to obtain the path to
  242
+test. This C<path> method must return a C<Str:D>.
  243
+
  244
+The methods are typically only one letter long (for now; perl 5 tradition
  245
+strikes) and are summarized in the following table:
  246
+
  247
+    M  Test performed
  248
+    =  ==============
  249
+    r  $.path is readable by effective uid/gid.
  250
+    w  $.path is writable by effective uid/gid.
  251
+    x  $.path is executable by effective uid/gid.
  252
+    o  $.path is owned by effective uid.
  253
+
  254
+    R  $.path is readable by real uid/gid.
  255
+    W  $.path is writable by real uid/gid.
  256
+    X  $.path is executable by real uid/gid.
  257
+    O  $.path is owned by real uid.
  258
+
  259
+    e  $.path exists.
  260
+    s  $.path has a size > 0 bytes
  261
+
  262
+    f  $.path is a plain file.
  263
+    d  $.path is a directory.
  264
+    l  $.path is a symbolic link.
  265
+    p  $.path is a named pipe (FIFO)
  266
+    S  $.path is a socket.
  267
+    b  $.path is a block special file.
  268
+    c  $.path is a character special file.
  269
+
  270
+    u  $.path has setuid bit set.
  271
+    g  $.path has setgid bit set.
  272
+    k  $.path has sticky bit set.
  273
+
  274
+
165 275
 =head1 Roles
166 276
 
167 277
 The functionality of C<IO> objects is broken down into several roles,
@@ -924,67 +1034,6 @@ is equivalent to
924 1034
 If fewer lines are available than the limit, it is not an error;
925 1035
 you just get the number of lines available.
926 1036
 
927  
-=item slurp
928  
-
929  
-    method slurp ($handle:
930  
-        Bool :$bin = False,
931  
-        Str  :$enc = "Unicode",
932  
-        --> Str|Buf
933  
-    )
934  
-    multi slurp (IO $fh = $*ARGFILES,
935  
-        Bool :$bin = False,
936  
-        Str  :$enc = "Unicode",
937  
-        --> Str|Buf
938  
-    )
939  
-    multi slurp (Str $filename,
940  
-        Bool :$bin = False,
941  
-        Str  :$enc = "Unicode",
942  
-        --> Str|Buf
943  
-    )
944  
-
945  
-Slurps the entire file into a C<Str> (or C<Buf> if C<:bin>) regardless of context.
946  
-(See also C<lines>.)
947  
-
948  
-The routine will C<fail> if the file does not exist, or is a directory.
949  
-
950  
-=item spurt
951  
-
952  
-    multi method spurt ($handle:
953  
-        Str   $contents,
954  
-        Str  :$enc = $?ENC,
955  
-        Bool :append = False,
956  
-    )
957  
-    multi method spurt ($handle:
958  
-        Buf   $contents,
959  
-        Bool :append = False,
960  
-    )
961  
-    multi spurt (IO $fh,
962  
-        Str   $contents,
963  
-        Str  :$enc = $?ENC,
964  
-        Bool :append = False,
965  
-    )
966  
-    multi spurt (IO $fh,
967  
-        Buf   $contents,
968  
-        Bool :append = False,
969  
-    )
970  
-    multi spurt (Str $filename,
971  
-        Str   $contents,
972  
-        Str  :$enc = $?ENC,
973  
-        Bool :append = False,
974  
-    )
975  
-    multi spurt (Str $filename,
976  
-        Buf   $contents,
977  
-        Bool :append = False,
978  
-    )
979  
-
980  
-Opens the file for writing, dumps the contents, and closes the file.
981  
-
982  
-This routine will C<fail> if the file exists, unless the C<:append> flag is
983  
-set, in which case it will instead add the given contents at the end of the
984  
-file.
985  
-
986  
-The routine will also C<fail> with the corresponding exception if there was any
987  
-other error in opening, writing, or closing.
988 1037
 
989 1038
 =back
990 1039
 
@@ -992,71 +1041,6 @@ other error in opening, writing, or closing.
992 1041
 
993 1042
 =over 4
994 1043
 
995  
-=item IO ~~ :X
996  
-X<:r>X<:w>X<:x>X<:o>X<:R>X<:W>X<:X>X<:O>X<:e>X<:z>X<:f>X<:d>X<:l>X<:p>
997  
-X<:S>X<:b>X<:c>X<:t>X<:u>X<:g>X<:k>X<:T>X<:B>X<:M>X<:A>X<:C>
998  
-
999  
-=item EXPR ~~ :X
1000  
-
1001  
-  $file.:X
1002  
-  $file ~~ :X
1003  
-
1004  
-A file test, where X is one of the letters listed below.  This unary
1005  
-operator takes one argument, either a filename or a filehandle, and
1006  
-tests the associated file to see if something is true about it.
1007  
-
1008  
-A C<Pair> used as a pattern is treated as a file test.
1009  
-
1010  
-    :r  File is readable by effective uid/gid.
1011  
-    :w  File is writable by effective uid/gid.
1012  
-    :x  File is executable by effective uid/gid.
1013  
-    :o  File is owned by effective uid.
1014  
-
1015  
-    :R  File is readable by real uid/gid.
1016  
-    :W  File is writable by real uid/gid.
1017  
-    :X  File is executable by real uid/gid.
1018  
-    :O  File is owned by real uid.
1019  
-
1020  
-    :e  File exists.
1021  
-    :s  File has a size > 0 bytes
1022  
-
1023  
-    :f  File is a plain file.
1024  
-    :d  File is a directory.
1025  
-    :l  File is a symbolic link.
1026  
-    :p  File is a named pipe (FIFO), or Filehandle is a pipe.
1027  
-    :S  File is a socket.
1028  
-    :b  File is a block special file.
1029  
-    :c  File is a character special file.
1030  
-    :t  Filehandle is opened to a tty.
1031  
-
1032  
-    :u  File has setuid bit set.
1033  
-    :g  File has setgid bit set.
1034  
-    :k  File has sticky bit set.
1035  
-
1036  
-Each of these is redirected (by C<Pair.ACCEPTS>) to the
1037  
-corresponding method name on an IO object.  (These methods are not
1038  
-defined on bare strings).  Each test returns a boolean, and may be
1039  
-negated with a C<!> after the colon.  They maybe ANDed and ORed using
1040  
-junctional logic.  In fact, this is the primary reason for writing
1041  
-them as a pattern match; if you only want one test, you could just call
1042  
-the individual IO method directly and more efficiently.  In any case,
1043  
-you must call the C<.s> method to return the file's size in bytes.
1044  
-
1045  
-There is no <.z> method, so just write C<:!s> to test a file for zero size.
1046  
-Likewise, just call C<.s> directly if you actually want to know the file's
1047  
-size, since C<~~ :s> only returns a boolean.
1048  
-
1049  
-The C<.T> and C<.B> methods will be replaced by some filetype guessing
1050  
-methods more appropriate to the age of Unicode.  There are likely methods
1051  
-to return the various ages of the file corresponding to Perl 5's C<-M>,
1052  
-C<-A>, and C<-C> times, but they make no sense as booleans, so also call
1053  
-those methods directly (whatever they end up being named).
1054  
-
1055  
-The interpretation of the file permission operators C<:r>, C<:R>,
1056  
-C<:w>, C<:W>, C<:x>, and C<:X> is by default based on:
1057  
-
1058  
-=over
1059  
-
1060 1044
 =item * The mode of the file and the uids and gids of the user
1061 1045
 
1062 1046
 =item * ACLs (access control lists)

0 notes on commit c2eea90

Please sign in to comment.
Something went wrong with that request. Please try again.