Skip to content
This repository
Browse code

document IO::Path; move more stuff around

  • Loading branch information...
commit 8082097aa44af485d7b0652d29927b9c5c1407c6 1 parent c2eea90
Moritz Lenz authored July 06, 2012

Showing 1 changed file with 211 additions and 309 deletions. Show diff stats Hide diff stats

  1. 520  S32-setting-library/IO.pod
520  S32-setting-library/IO.pod
Source Rendered
@@ -58,7 +58,7 @@ subclasses of C<IO::Path>.
58 58
 
59 59
 File tests are performed through C<IO::Path> objects.
60 60
 
61  
-=head2 Functions
  61
+=head1 Functions
62 62
 
63 63
 =over 4
64 64
 
@@ -160,8 +160,20 @@ other error in opening, writing, or closing.
160 160
 
161 161
 =back
162 162
 
  163
+=head1 IO Types
  164
+
  165
+=head2 IO
  166
+
  167
+    role IO { };
  168
+
  169
+The base role only tags that this is an C<IO> object for more generic
  170
+purposes. It doesn't specify any methods or attributes.
  171
+
  172
+
163 173
 =head2 IO::Handle
164 174
 
  175
+    class IO::Handle does IO { ... }
  176
+
165 177
 A handle of a file, pipe or anything else that supports reading or
166 178
 writing like a file.
167 179
 
@@ -180,7 +192,18 @@ X<print>
180 192
     method print (IO::Handle:D: *@LIST --> Bool)
181 193
     multi print (*@LIST --> Bool)
182 194
 
183  
-See below for details.
  195
+Stringifies each element, concatenates those strings, and sends the
  196
+result to the output.
  197
+Returns C<Bool::True> if successful, C<Failure> otherwise.
  198
+
  199
+The compiler will warn you if use a bare C<print> without arguments.
  200
+(However, it's fine if you have an explicit argument list that evaluates to
  201
+the empty list at runtime.)
  202
+
  203
+    print;             # warns
  204
+    if $_ { print }    # warns
  205
+    if $_ { print() }  # ok, but does nothing
  206
+    if $_ { print () } # ok, but does nothing
184 207
 
185 208
 =item say
186 209
 X<say>
@@ -188,7 +211,15 @@ X<say>
188 211
     method say (IO::Handle:D: *@LIST --> Bool)
189 212
     multi say (*@LIST --> Bool)
190 213
 
191  
-See below for details.
  214
+This is identical to print() except that it stringifies its arguments by calling
  215
+C<.gist> on them and auto-appends the C<output-line-separator> after the final
  216
+argument.
  217
+
  218
+    Was:    print "Hello, world!\n";
  219
+    Now:    say   "Hello, world!";
  220
+
  221
+As with C<print>, the compiler will warn you if you use a bare C<say> without
  222
+arguments.
192 223
 
193 224
 =item printf
194 225
 X<printf>
@@ -196,7 +227,7 @@ X<printf>
196 227
     method printf (Str $fmt, *@LIST --> Bool)
197 228
     multi printf (IO::Handle:D: Str $fmt, *@LIST --> Bool)
198 229
 
199  
-See below for details.
  230
+Output through C<Str.sprintf>. See L<S32::Str> for details.
200 231
 
201 232
 =item  write
202 233
 
@@ -229,223 +260,38 @@ Returns C<True> if the handle is opened to a tty.
229 260
 
230 261
 Returns C<True> if the handle is opened to a pipe.
231 262
 
232  
-=back
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.
  263
+=item eof
253 264
 
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.
  265
+    method eof() returns Bool:D
258 266
 
259  
-    e  $.path exists.
260  
-    s  $.path has a size > 0 bytes
  267
+Returns C<True> if the handle is exhausted.
261 268
 
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  
-
275  
-=head1 Roles
276  
-
277  
-The functionality of C<IO> objects is broken down into several roles,
278  
-which should identify the features each object supports.
279  
-
280  
-=head2 IO
281  
-
282  
-The base role only tags that this is an C<IO> object for more generic
283  
-purposes. It doesn't specify any methods or attributes.
284  
-
285  
-=head2 IO::Readable
286  
-
287  
-This role provides unbuffered read access to the data stream.
288  
-
289  
-    role IO::Readable {
290  
-        has $.isReadable;
291  
-        method read(Int $bytes --> Buf)
292  
-    }
293  
-
294  
-When the C<$.isReadable> is set, it tries to change the readability of the filehandle.  This
295  
-is not always possible, but can be done in a number of cases.  C<IO::Socket> can remove
296  
-readability by calling C<shutdown>, for example.
297  
-
298  
-=over
299  
-
300  
-=item method read(Int $bytes --> Buf)
301  
-
302  
-Tries to read C<$bytes> bytes and return it as a C<Buf>. The C<Buf> may be
303  
-shorter than the actual specified number of C<$bytes>.
304  
-
305  
-This is "raw" read. You're going to
306  
-have plain octets stored in C<$buf>. If what you want is a C<Str>,
307  
-you're going to need to C<.decode> it after C<read>ing, or use "getc" or other
308  
-C<IO::Readable::Encoded> methods.
309  
-
310  
-=back
  269
+=item seek
311 270
 
312  
-=head2 IO::Writeable
313  
-
314  
-This role provides unbuffered write access to the data stream.
315  
-
316  
-    role IO::Writeable {
317  
-        has $.isWriteable;
318  
-        method write(Buf $buf --> Int)
319  
-    }
320  
-
321  
-When the C<$.isWriteable> is set, it tries to change the writeability of the filehandle.
322  
-This is not always possible, but can be done in a number of cases.  C<IO::Socket> can remove
323  
-writeability by calling shutdown(), for example.
324  
-
325  
-=over
326  
-
327  
-
328  
-=head2 IO::Seekable
329  
-
330  
-=over
331  
-
332  
-=item method eoi( --> Bool)
333  
-
334  
-EOI = End Of Input -- equivalent to End Of File, but applies to other kinds of sockets as
335  
-well.
336  
-
337  
-Returns true if it's the end of the input (i.e. end of file or whatever), returns false if
338  
-not, fails if we can't say for certain.
339  
-
340  
-=item method seek(Int $position --> Bool)
  271
+method seek(Int $position, Int $whence --> Bool)
341 272
 
342 273
 Position this stream into C<$position>. The meaning of this position is
343 274
 always in "octets".
344 275
 
345  
-=item method tell( --> Int)
346  
-
347  
-Returns the current raw position in the stream in number of "octets".
348  
-
349  
-=back
350  
-
351  
-=head2 IO::Buffered
352  
-
353  
-Indicates that this object performs buffering. The management of the
354  
-buffer is completely implementation specific.
355  
-
356  
-=over
357  
-
358  
-=item method flush( --> Bool)
359  
-
360  
-Flushes the buffers associated with this object.
361  
-
362  
-=item method autoflush( --> Bool) is rw
363  
-
364  
-Forces this object to keep its buffers empty
365  
-
366  
-If set to nonzero, forces a flush right away and after every write
367  
-or print on the currently selected output channel.
368  
-Default is 0 (regardless of whether the channel is really buffered
369  
-by the system or not;
370  
-C<$OUT_FH.autoflush> tells you only whether you've asked Perl
371  
-explicitly to flush after each write).
372  
-C<$*OUT> will typically be line buffered if output is to the
373  
-terminal and block buffered otherwise.
374  
-Setting this variable is useful primarily when you are
375  
-outputting to a pipe or socket,
376  
-such as when you are running a Perl program under rsh
377  
-and want to see the output as it's happening.
378  
-This has no effect on input buffering.
379  
-
380  
-
381  
-=back
382  
-
383  
-=head2 IO::Streamable
384  
-
385  
-This role represents objects that depend on some external resource,
386  
-which means that data might not be available at request.
387  
-
388  
-    role IO::Streamable does IO {...}
389  
-
390  
-=over
391  
-
392  
-=item new()
393  
-
394  
-    method new(
395  
-        Bool :$NoOpen,
396  
-        Bool :$Blocking,
397  
-        --> IO::Streamable
398  
-    ) {...}
399  
-
400  
-Unless the NoOpen option is passed, an open will be done on the C<IO> object when it is
401  
-created.
402  
-
403  
-If blocking is passed in, .blocking() is called (see below).
404  
-
405  
-=item method blocking( --> Bool) is rw
406  
-
407  
-This allows the user to control whether this object should do a
408  
-blocking wait or immediately return in the case of not having data
409  
-available.
410  
-
411  
-=item uri
412  
-
413  
-    method uri(Str $uri --> IO::Streamable) {...}
414  
-
415  
-This should be callable on the class, and act like a kind of "new()" function.  When given
416  
-a URI, it returns an C<IO::Streamable> of the appropriate type, and throws an error when an
417  
-inappropriate type is passed in.  For example, calling C<IO::File.uri('http://....')> will
418  
-throw an error (but will suggest using just uri('http://...') instead).
419  
-
420  
-=back
421  
-
422  
-=head2 IO::Encoded
423  
-
424  
-This is a generic role for encoded data streams.
425  
-
426  
-=over
427  
-
428  
-=item method encoding( --> Str) is rw
  276
+Fails if the handle is not seekable.
429 277
 
430  
-=item method locale( --> Str) is rw
  278
+TODO: make $whence an Enum
431 279
 
432  
-Encoding and locale are required for sane conversions.
  280
+=item tell
433 281
 
434  
-=back
  282
+    method tell() returns Int:D:
435 283
 
436  
-=head2 IO::Readable::Encoded
  284
+Returns the current raw position in the stream in number of "octets".
437 285
 
438  
-This role provides encoded access to a readable data stream, implies
439  
-C<IO::Encoded>. Might imply C<IO::Buffered>, but that's not a requirement.
  286
+=item ins
440 287
 
441  
-=over
  288
+    method ins( --> Int)
442 289
 
443  
-=item method ins( --> Int)
  290
+Returns the number of lines that have been read with C<get>.
444 291
 
445  
-Returns the number of lines or records that have been input.
446  
-Now with cleaned-up localization usage.
  292
+=item input-line-separator
447 293
 
448  
-=item method input-line-separator( --> Str) is rw
  294
+    method input-line-separator( --> Str) is rw
449 295
 
450 296
 This regulates how "get" and "lines" behave.
451 297
 
@@ -467,152 +313,116 @@ You may also set it to a regular expression.  The value of C<$/>
467 313
 will be (temporarily) set to the matched separator upon input,
468 314
 if you care about the contents of the separator.
469 315
 
470  
-=item method input-field-separator( --> Str) is rw
471  
-
472  
-[Deprecated.]
473  
-
474  
-=item method input-escape( --> Str) is rw
475  
-
476  
-[Deprecated.]
477  
-
478  
-=item method get( --> Str)
479  
-
480  
-Reads the stream before it finds a C<$.input-line-separator> and
481  
-returns it (autochomped by default).
482  
-
483  
-=item method readfield( --> Str)
484  
-
485  
-[Deprecated. Use split or comb or an ILS regex.]
486  
-
487  
-=item method getc( --> Char)
488  
-
489  
-Reads the next character in the set C<$.encoding>,
490  
-or C<Failure> at end of file, or if there was
491  
-an error (in either case C<$!> is set).  Note that this
492  
-function cannot be used interactively as a C<readkey()> function, since under
493  
-Unicode you can't tell the end of a grapheme until you
494  
-see the beginning of the next one.
495  
-
496  
-[TODO someone needs to define something like C<readkey()> for terminal IO.
497  
-Though most event-based programs will just want to feed keystrokes into the
498  
-event queue.]
499  
-
500  
-=item multi method comb ( Regex $matcher, Int $limit = * )
  316
+=item close
501 317
 
502  
-Reads everything into a string, and calls C<.comb> on it with the same
503  
-parameters. See C<Str::comb>.
  318
+Closes the handle. Fails on error.
504 319
 
505 320
 =back
506 321
 
507  
-=head2 IO::Writeable::Encoded
508  
-
509  
-This role provides encoded access to a writeable data stream, implies
510  
-C<IO::Encoded>. Might imply C<IO::Buffered>, but that's not a requirement.
511  
-
512  
-If these are called in their non-object form, they operate on C<$*OUT>, except in the
513  
-case of warn(), which operates on C<$*ERR>.  The form with leading dot prints C<$_> to
514  
-the appropriate handle unless C<$_> happens to be a filehandle.
515  
-
516  
-=over
517  
-
518  
-=item Int method outs()
519  
-
520  
-Returns the number of lines or records that have been output so far.
521  
-
522  
-=item method output-line-separator( --> Str) is rw
  322
+=head1 IO::FileTests
523 323
 
524  
-This regulates how say behaves.
  324
+    role IO::FileTests does IO { ... }
525 325
 
526  
-=item method output-field-separator( --> Str) is rw
  326
+Provides ways to inspect a file or path without opening it.
527 327
 
528  
-[Deprecated.]
  328
+If you apply that role to a class, that class must provide a C<path>
  329
+method which C<IO::FileTests>' method will call to obtain the path to
  330
+test. This C<path> method must return a C<Str:D>.
529 331
 
530  
-=item method output-escape( --> Str) is rw
  332
+The methods are typically only one letter long (for now; perl 5 tradition
  333
+strikes) and are summarized in the following table:
531 334
 
532  
-[Deprecated.]
  335
+    M  Test performed
  336
+    =  ==============
  337
+    r  $.path is readable by effective uid/gid.
  338
+    w  $.path is writable by effective uid/gid.
  339
+        x  $.path is executable by effective uid/gid.
  340
+    o  $.path is owned by effective uid.
533 341
 
534  
-=item method Str::print (IO $io = $*OUT --> Bool)
  342
+    R  $.path is readable by real uid/gid.
  343
+    W  $.path is writable by real uid/gid.
  344
+    X  $.path is executable by real uid/gid.
  345
+    O  $.path is owned by real uid.
535 346
 
536  
-=item method Str::say (IO $io = $*OUT --> Bool)
  347
+    e  $.path exists.
  348
+    s  $.path has a size > 0 bytes
537 349
 
538  
-=item method Array::print(IO $io = $*OUT --> Bool)
  350
+    f  $.path is a plain file.
  351
+    d  $.path is a directory.
  352
+    l  $.path is a symbolic link.
  353
+    p  $.path is a named pipe (FIFO)
  354
+    S  $.path is a socket.
  355
+    b  $.path is a block special file.
  356
+    c  $.path is a character special file.
539 357
 
540  
-=item method Array::say(IO $io = $*OUT --> Bool)
  358
+    u  $.path has setuid bit set.
  359
+    g  $.path has setgid bit set.
  360
+    k  $.path has sticky bit set.
541 361
 
542  
-=item method Hash::print(IO $io = $*OUT --> Bool)
  362
+TODO: methods created, accessed, modified
543 363
 
544  
-=item method Hash::say(IO $io = $*OUT --> Bool)
  364
+=head2 IO::Path
545 365
 
546  
-Stringifies the invocant (if necessary) and then sends it to the output.
547  
-C<say> should add an additional C<$.output-line-separator>.
  366
+    class IO::Path is Cool does IO::FileTest { }
548 367
 
  368
+Holds a path of a file or directory. The path is generally divided
  369
+into three parts, the I<file system>, I<directory> and I<base name>.
549 370
 
550  
-=item method print (*@LIST --> Bool)
  371
+On Windows, the file system is a drive letter like C<C:>. Relative paths
  372
+never have a file system part. On UNIX-based systems, the file system part
  373
+is empty.
551 374
 
552  
-=item multi print (*@LIST --> Bool)
  375
+The base name is name of the file or directory that the IO::Path object
  376
+represents, and the directory is the part of the path leading up to the base
  377
+name.
553 378
 
  379
+    path            file system   directory  base name
  380
+    /usr/bin/gvim                 /usr/bin   gvim   
  381
+    /usr/bin/                     /usr       bin
  382
+    C:\temp\f.txt  C:             temp       f.txt
554 383
 
555  
-Stringifies each element, concatenates those strings, and sends the
556  
-result to the output.
557  
-Returns C<Bool::True> if successful, C<Failure> otherwise.
  384
+=over 4
558 385
 
559  
-The compiler will warn you if use a bare C<print> without arguments.
560  
-(However, it's fine if you have an explicit argument list that evaluates to
561  
-the empty list at runtime.)
  386
+=item path
562 387
 
563  
-    print;             # warns
564  
-    if $_ { print }    # warns
565  
-    if $_ { print() }  # ok, but does nothing
566  
-    if $_ { print () } # ok, but does nothing
  388
+Returns the path (file system, directory and base name joined together) as
  389
+a string.
567 390
 
568  
-=item method say (*@LIST --> Bool)
  391
+=item filesystem
569 392
 
570  
-=item multi say (*@LIST --> Bool)
  393
+Returns the file system part of the path
571 394
 
572  
-This is identical to print() except that it stringifies its arguments by calling
573  
-C<.gist> on them and auto-appends the C<output-line-separator> after the final
574  
-argument.
  395
+=item directory
575 396
 
576  
-    Was:    print "Hello, world!\n";
577  
-    Now:    say   "Hello, world!";
  397
+Returns the directory part of the path
578 398
 
579  
-As with C<print>, the compiler will warn you if you use a bare C<say> without
580  
-arguments.
  399
+=item basename
581 400
 
582  
-=item method printf ($self: Str $fmt, *@LIST --> Bool)
  401
+Returns the base name part of the path
583 402
 
584  
-=item multi printf (Str $fmt, *@LIST --> Bool)
  403
+=item Str
585 404
 
586  
-The function form works as in Perl 5 and always prints to C<$*OUT>.
  405
+Stringifies to the base name.
587 406
 
588 407
 =back
589 408
 
590  
-For any handle marked as textual, all these output calls intercept any newline
591  
-character and translate it to the current C<output-line-separator> if it
592  
-is defined as something other than newline.  No such translation is done on
593  
-binary handles, though you may still specify a record separator.  In any case,
594  
-escaping separators is the responsibility of the programmer.
  409
+=head2 IO::File
595 410
 
596  
-=head2 IO::Closeable
  411
+    class IO::File is IO::Path { ... }
597 412
 
598  
-This role indicates that this object can be closed.
  413
+Represents a path that is known to be a plain file (not a directory), at
  414
+least at the time when the object was created.
599 415
 
600  
-=over
  416
+=head2 IO::Dir
601 417
 
602  
-=item method close( --> Bool)
  418
+    class IO::Dir is IO::Path { ... }
603 419
 
604  
-Closes the file or pipe associated with the object.
  420
+Represents a path that is known to be a directory, at
  421
+least at the time when the object was created.
605 422
 
606  
-Returns C<True> on success, but might return an unthrown C<Failure>.
607  
-Returns true only if C<IO> buffers are successfully flushed and closes the system
608  
-file descriptor.
  423
+=head1 Here Be Dragons
609 424
 
610  
-Unlike in Perl 5, an C<IO> object is not a special symbol table entry
611  
-neither this object is available magically anywhere else. But as in
612  
-Perl 5, unless stated otherwise, C<IO::Closeable> objects always close
613  
-themselves during destruction.
614  
-
615  
-=back
  425
+Everything below this point hasn't been reviewed properly
616 426
 
617 427
 =head2 IO::Socket
618 428
 
@@ -1406,6 +1216,98 @@ a general laundry list, please separate messages by topic.
1406 1216
 Old methods are moved here if it's not clear how they fit into the current
1407 1217
 picture. If nobody comes up with a good solution, they are removed.
1408 1218
 
  1219
+=head2 IO::Buffered
  1220
+
  1221
+Indicates that this object performs buffering. The management of the
  1222
+buffer is completely implementation specific.
  1223
+
  1224
+=over
  1225
+
  1226
+=item method flush( --> Bool)
  1227
+
  1228
+Flushes the buffers associated with this object.
  1229
+
  1230
+=item method autoflush( --> Bool) is rw
  1231
+
  1232
+Forces this object to keep its buffers empty
  1233
+
  1234
+If set to nonzero, forces a flush right away and after every write
  1235
+or print on the currently selected output channel.
  1236
+Default is 0 (regardless of whether the channel is really buffered
  1237
+by the system or not;
  1238
+C<$OUT_FH.autoflush> tells you only whether you've asked Perl
  1239
+explicitly to flush after each write).
  1240
+C<$*OUT> will typically be line buffered if output is to the
  1241
+terminal and block buffered otherwise.
  1242
+Setting this variable is useful primarily when you are
  1243
+outputting to a pipe or socket,
  1244
+such as when you are running a Perl program under rsh
  1245
+and want to see the output as it's happening.
  1246
+This has no effect on input buffering.
  1247
+
  1248
+
  1249
+=back
  1250
+
  1251
+=head2 IO::Streamable
  1252
+
  1253
+This role represents objects that depend on some external resource,
  1254
+which means that data might not be available at request.
  1255
+
  1256
+    role IO::Streamable does IO {...}
  1257
+
  1258
+=over
  1259
+
  1260
+=item new()
  1261
+
  1262
+    method new(
  1263
+        Bool :$NoOpen,
  1264
+        Bool :$Blocking,
  1265
+        --> IO::Streamable
  1266
+    ) {...}
  1267
+
  1268
+Unless the NoOpen option is passed, an open will be done on the C<IO> object when it is
  1269
+created.
  1270
+
  1271
+If blocking is passed in, .blocking() is called (see below).
  1272
+
  1273
+=item method blocking( --> Bool) is rw
  1274
+
  1275
+This allows the user to control whether this object should do a
  1276
+blocking wait or immediately return in the case of not having data
  1277
+available.
  1278
+
  1279
+=item uri
  1280
+
  1281
+    method uri(Str $uri --> IO::Streamable) {...}
  1282
+
  1283
+This should be callable on the class, and act like a kind of "new()" function.  When given
  1284
+a URI, it returns an C<IO::Streamable> of the appropriate type, and throws an error when an
  1285
+inappropriate type is passed in.  For example, calling C<IO::File.uri('http://....')> will
  1286
+throw an error (but will suggest using just uri('http://...') instead).
  1287
+
  1288
+=back
  1289
+
  1290
+=head2 IO::Encoded
  1291
+
  1292
+This is a generic role for encoded data streams.
  1293
+
  1294
+=over
  1295
+
  1296
+=item method encoding( --> Str) is rw
  1297
+
  1298
+=item method locale( --> Str) is rw
  1299
+
  1300
+Encoding and locale are required for sane conversions.
  1301
+
  1302
+=back
  1303
+
  1304
+=head2 IO::Readable::Encoded
  1305
+
  1306
+This role provides encoded access to a readable data stream, implies
  1307
+C<IO::Encoded>. Might imply C<IO::Buffered>, but that's not a requirement.
  1308
+
  1309
+=over
  1310
+
1409 1311
 =over 4
1410 1312
 
1411 1313
 =item uri

0 notes on commit 8082097

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