1IO::All(3)            User Contributed Perl Documentation           IO::All(3)
2
3
4

NAME

6       IO::All - IO::All of it to Graham and Damian!
7

SYNOPSIS

9           use IO::All;                                # Let the madness begin...
10
11           # Some of the many ways to read a whole file into a scalar
12           io('file.txt') > $contents;                 # Overloaded "arrow"
13           $contents < io 'file.txt';                  # Flipped but same operation
14           $io = io 'file.txt';                        # Create a new IO::All object
15           $contents = $$io;                           # Overloaded scalar dereference
16           $contents = $io->all;                       # A method to read everything
17           $contents = $io->slurp;                     # Another method for that
18           $contents = join '', $io->getlines;         # Join the separate lines
19           $contents = join '', map "$_\n", @$io;      # Same. Overloaded array deref
20           $io->tie;                                   # Tie the object as a handle
21           $contents = join '', <$io>;                 # And use it in builtins
22           # and the list goes on ...
23
24           # Other file operations:
25           @lines = io('file.txt')->slurp;             # List context slurp
26           $content > io('file.txt');                  # Print to a file
27           io('file.txt')->print($content, $more);     # (ditto)
28           $content >> io('file.txt');                 # Append to a file
29           io('file.txt')->append($content);           # (ditto)
30           $content << $io;                            # Append to a string
31           io('copy.txt') < io('file.txt');            $ Copy a file
32           io('file.txt') > io('copy.txt');            # Invokes File::Copy
33           io('more.txt') >> io('all.txt');            # Add on to a file
34
35           # UTF-8 Support
36           $contents = io('file.txt')->utf8->all;      # Turn on utf8
37           use IO::All -utf8;                          # Turn on utf8 for all io
38           $contents = io('file.txt')->all;            #   by default in this package.
39
40           # General Encoding Support
41           $contents = io('file.txt')->encoding('big5')->all;
42           use IO::All -encoding => 'big5';            # Turn on big5 for all io
43           $contents = io('file.txt')->all;            #   by default in this package.
44
45           # Print the path name of a file:
46           print $io->name;                            # The direct method
47           print "$io";                                # Object stringifies to name
48           print $io;                                  # Quotes not needed here
49           print $io->filename;                        # The file portion only
50
51           # Read all the files/directories in a directory:
52           $io = io('my/directory/');                  # Create new directory object
53           @contents = $io->all;                       # Get all contents of dir
54           @contents = @$io;                           # Directory as an array
55           @contents = values %$io;                    # Directory as a hash
56           push @contents, $subdir                     # One at a time
57             while $subdir = $io->next;
58
59           # Print the name and file type for all the contents above:
60           print "$_ is a " . $_->type . "\n"          # Each element of @contents
61             for @contents;                            # is an IO::All object!!
62
63           # Print first line of each file:
64           print $_->getline                           # getline gets one line
65             for io('dir')->all_files;                 # Files only
66
67           # Print names of all files/dirs three directories deep:
68           print "$_\n" for $io->all(3);               # Pass in the depth. Default=1
69
70           # Print names of all files/dirs recursively:
71           print "$_\n" for $io->all(0);               # Zero means all the way down
72           print "$_\n" for $io->All;                  # Capitalized shortcut
73           print "$_\n" for $io->deep->all;            # Another way
74
75           # There are some special file names:
76           print io('-');                              # Print STDIN to STDOUT
77           io('-') > io('-');                          # Do it again
78           io('-') < io('-');                          # Same. Context sensitive.
79           "Bad puppy" > io('=');                      # Message to STDERR
80           $string_file = io('$');                     # Create IO::String Object
81           $temp_file = io('?');                       # Create a temporary file
82
83           # Socket operations:
84           $server = io('localhost:5555')->fork;       # Create a daemon socket
85           $connection = $server->accept;              # Get a connection socket
86           $input < $connection;                       # Get some data from it
87           "Thank you!" > $connection;                 # Thank the caller
88           $connection->close;                         # Hang up
89           io(':6666')->accept->slurp > io->devnull;   # Take a complaint and file it
90
91           # DBM database operations:
92           $dbm = io 'my/database';                    # Create a database object
93           print $dbm->{grocery_list};                 # Hash context makes it a DBM
94           $dbm->{todo} = $new_list;                   # Write to database
95           $dbm->dbm('GDBM_file');                     # Demand specific DBM
96           io('mydb')->mldbm->{env} = \%ENV;           # MLDBM support
97
98           # Tie::File support:
99           $io = io 'file.txt';
100           $io->[42] = 'Line Forty Three';             # Change a line
101           print $io->[@$io / 2];                      # Print middle line
102           @$io = reverse @$io;                        # Reverse lines in a file
103
104           # Stat functions:
105           printf "%s %s %s\n",                        # Print name, uid and size of
106             $_->name, $_->uid, $_->size               # contents of current directory
107               for io('.')->all;
108           print "$_\n" for sort                       # Use mtime method to sort all
109             {$b->mtime <=> $a->mtime}                 # files under current directory
110               io('.')->All_Files;                     # by recent modification time.
111
112           # File::Spec support:
113           $contents < io->catfile(qw(dir file.txt));  # Portable IO operation
114
115           # Miscellaneous:
116           @lines = io('file.txt')->chomp->slurp;      # Chomp as you slurp
117           @chunks =
118             io('file.txt')->separator('xxx')->slurp;  # Use alternnate record sep
119           $binary = io('file.bin')->binary->all;      # Read a binary file
120           io('a-symlink')->readlink->slurp;           # Readlink returns an object
121           print io('foo')->absolute->pathname;        # Print absolute path of foo
122
123           # IO::All External Plugin Methods
124           io("myfile") > io->("ftp://store.org");     # Upload a file using ftp
125           $html < io->http("www.google.com");         # Grab a web page
126           io('mailto:worst@enemy.net')->print($spam); # Email a "friend"
127
128           # This is just the beginning, read on...
129

DESCRIPTION

131       "Graham Barr for doing it all. Damian Conway for doing it all differ‐
132       ent."
133
134       IO::All combines all of the best Perl IO modules into a single nifty
135       object oriented interface to greatly simplify your everyday Perl IO
136       idioms. It exports a single function called "io", which returns a new
137       IO::All object. And that object can do it all!
138
139       The IO::All object is a proxy for IO::File, IO::Dir, IO::Socket,
140       IO::String, Tie::File, File::Spec, File::Path and File::ReadBackwards;
141       as well as all the DBM and MLDBM modules. You can use most of the meth‐
142       ods found in these classes and in IO::Handle (which they inherit from).
143       IO::All adds dozens of other helpful idiomatic methods including file
144       stat and manipulation functions.
145
146       IO::All is pluggable, and modules like IO::All::LWP and IO::All::Mailto
147       add even more functionality. Optionally, every IO::All object can be
148       tied to itself. This means that you can use most perl IO builtins on
149       it: readline, <>, getc, print, printf, syswrite, sysread, close.
150
151       The distinguishing magic of IO::All is that it will automatically open
152       (and close) files, directories, sockets and other IO things for you.
153       You never need to specify the mode ('<', '>>', etc), since it is deter‐
154       mined by the usage context. That means you can replace this:
155
156           open STUFF, '<', './mystuff'
157             or die "Can't open './mystuff' for input:\n$!";
158           local $/;
159           my $stuff = <STUFF>;
160           close STUFF;
161
162       with this:
163
164           my $stuff < io"./mystuff";
165
166       And that is a good thing!
167

USAGE

169       Normally just say:
170
171           use IO::All;
172
173       and IO::All will export a single function called "io", which contructs
174       all IO objects.
175
176       You can also pass global flags like this:
177
178           use IO::All -strict -encoding => 'big5', -foobar;
179
180       Which automatically makes those method calls on every new IO object. In
181       other words this:
182
183           my $io = io('lalala.txt');
184
185       becomes this:
186
187           my $io = io('lalala.txt')->strict->encoding('big5')->foobar;
188

METHOD ROLE CALL

190       Here is an alphabetical list of all the public methods that you can
191       call on an IO::All object.
192
193       "abs2rel", "absolute", "accept", "All", "all", "All_Dirs", "all_dirs",
194       "All_Files", "all_files", "All_Links", "all_links", "append",
195       "appendf", "appendln", "assert", "atime", "autoclose", "autoflush",
196       "backwards", "bcc", "binary", "binmode", "blksize", "blocks",
197       "block_size", "buffer", "canonpath", "case_tolerant", "catdir", "cat‐
198       file", "catpath", "cc", "chdir", "chomp", "clear", "close", "confess",
199       "content", "ctime", "curdir", "dbm", "deep", "device", "device_id",
200       "devnull", "dir", "domain", "empty", "encoding", "eof", "errors",
201       "file", "filename", "fileno", "filepath", "filter", "fork", "from",
202       "ftp", "get", "getc", "getline", "getlines", "gid", "handle", "head",
203       "http", "https", "inode", "io_handle", "is_absolute", "is_dir",
204       "is_dbm", "is_executable", "is_file", "is_link", "is_mldbm", "is_open",
205       "is_pipe", "is_readable", "is_socket", "is_stdio", "is_string",
206       "is_temp", "is_writable", "join", "length", "link", "lock", "mailer",
207       "mailto", "mkdir", "mkpath", "mldbm", "mode", "modes", "mtime", "name",
208       "new", "next", "nlink", "open", "password", "path", "pathname",
209       "perms", "pipe", "port", "print", "printf", "println", "put", "rdonly",
210       "rdwr", "read", "readdir", "readlink", "recv", "rel2abs", "relative",
211       "rename", "request", "response", "rmdir", "rmtree", "rootdir",
212       "scalar", "seek", "send", "separator", "shutdown", "size", "slurp",
213       "socket", "sort", "splitdir", "splitpath", "stat", "stdio", "stderr",
214       "stdin", "stdout", "strict", "string", "string_ref", "subject", "sys‐
215       read", "syswrite", "tail", "tell", "temp", "tie", "tmpdir", "to",
216       "touch", "truncate", "type", "user", "uid", "unlink", "unlock",
217       "updir", "uri", "utf8", "utime" and "write".
218
219       Each method is documented further below.
220

OPERATOR OVERLOADING

222       IO::All objects overload a small set of Perl operators to great effect.
223       The overloads are limited to <, <<, >, >>, dereferencing operations,
224       and stringification.
225
226       Even though relatively few operations are overloaded, there is actually
227       a huge matrix of possibilities for magic. That's because the overload‐
228       ing is sensitive to the types, position and context of the arguments,
229       and an IO::All object can be one of many types.
230
231       The most important overload to grok is stringification. IO::All objects
232       stringify to their file or directory name. Here we print the contents
233       of the current directory:
234
235           perl -MIO::All -le 'print for io(".")->all'
236
237       is the same as:
238
239           perl -MIO::All -le 'print $_->name for io(".")->all'
240
241       Stringification is important because it allows IO::All operations to
242       return objects when they might otherwise return file names. Then the
243       recipient can use the result either as an object or a string.
244
245       '>' and '<' move data between objects in the direction pointed to by
246       the operator.
247
248           $content1 < io('file1');
249           $content1 > io('file2');
250           io('file2') > $content3;
251           io('file3') < $content3;
252           io('file3') > io('file4');
253           io('file5') < io('file4');
254
255       '>>' and '<<' do the same thing except the recipent string or file is
256       appended to.
257
258       An IO::All file used as an array reference becomes tied using
259       Tie::File:
260
261           $file = io"file";
262           # Print last line of file
263           print $file->[-1];
264           # Insert new line in middle of file
265           $file->[$#$file / 2] = 'New line';
266
267       An IO::All file used as a hash reference becomes tied to a DBM class:
268
269           io('mydbm')->{ingy} = 'YAML';
270
271       An IO::All directory used as an array reference, will expose each file
272       or subdirectory as an element of the array.
273
274           print "$_\n" for @{io 'dir'};
275
276       IO::All directories used as hash references have file names as keys,
277       and IO::All objects as values:
278
279           print io('dir')->{'foo.txt'}->slurp;
280
281       Files used as scalar references get slurped:
282
283           print ${io('dir')->{'foo.txt'}};
284
285       Not all combinations of operations and object types are supported. Some
286       just haven't been added yet, and some just don't make sense. If you use
287       an invalid combination, an error will be thrown.
288

COOKBOOK

290       This section describes some various things that you can easily cook up
291       with IO::All.
292
293       File Locking
294
295       IO::All makes it very easy to lock files. Just use the "lock" method.
296       Here's a standalone program that demonstrates locking for both write
297       and read:
298
299           use IO::All;
300           my $io1 = io('myfile')->lock;
301           $io1->println('line 1');
302
303           fork or do {
304               my $io2 = io('myfile')->lock;
305               print $io2->slurp;
306               exit;
307           };
308
309           sleep 1;
310           $io1->println('line 2');
311           $io1->println('line 3');
312           $io1->unlock;
313
314       There are a lot of subtle things going on here. An exclusive lock is
315       issued for $io1 on the first "println". That's because the file isn't
316       actually opened until the first IO operation.
317
318       When the child process tries to read the file using $io2, there is a
319       shared lock put on it. Since $io1 has the exclusive lock, the slurp
320       blocks.
321
322       The parent process sleeps just to make sure the child process gets a
323       chance. The parent needs to call "unlock" or "close" to release the
324       lock. If all goes well the child will print 3 lines.
325
326       Round Robin
327
328       This simple example will read lines from a file forever. When the last
329       line is read, it will reopen the file and read the first one again.
330
331           my $io = io'file1.txt';
332           $io->autoclose(1);
333           while (my $line = $io->getline ⎪⎪ $io->getline) {
334               print $line;
335           }
336
337       Reading Backwards
338
339       If you call the "backwards" method on an IO::All object, the "getline"
340       and "getlines" will work in reverse. They will read the lines in the
341       file from the end to the beginning.
342
343           my @reversed;
344           my $io = io('file1.txt');
345           $io->backwards;
346           while (my $line = $io->getline) {
347               push @reversed, $line;
348           }
349
350       or more simply:
351
352           my @reversed = io('file1.txt')->backwards->getlines;
353
354       The "backwards" method returns the IO::All object so that you can chain
355       the calls.
356
357       NOTE: This operation requires that you have the File::ReadBackwards
358       module installed.
359
360       Client/Server Sockets
361
362       IO::All makes it really easy to write a forking socket server and a
363       client to talk to it.
364
365       In this example, a server will return 3 lines of text, to every client
366       that calls it. Here is the server code:
367
368           use IO::All;
369
370           my $socket = io(':12345')->fork->accept;
371           $socket->print($_) while <DATA>;
372           $socket->close;
373
374           __DATA__
375           On your mark,
376           Get set,
377           Go!
378
379       Here is the client code:
380
381           use IO::All;
382
383           my $io = io('localhost:12345');
384           print while $_ = $io->getline;
385
386       You can run the server once, and then run the client repeatedly (in
387       another terminal window). It should print the 3 data lines each time.
388
389       Note that it is important to close the socket if the server is forking,
390       or else the socket won't go out of scope and close.
391
392       A Tiny Web Server
393
394       Here is how you could write a simplistic web server that works with
395       static and dynamic pages:
396
397           perl -MIO::All -e 'io(":8080")->fork->accept->(sub { $_[0] < io(-x $1 ? "./$1 ⎪" : $1) if /^GET \/(.*) / })'
398
399       There is are a lot of subtle things going on here. First we accept a
400       socket and fork the server. Then we overload the new socket as a code
401       ref. This code ref takes one argument, another code ref, which is used
402       as a callback.
403
404       The callback is called once for every line read on the socket. The line
405       is put into $_ and the socket itself is passed in to the callback.
406
407       Our callback is scanning the line in $_ for an HTTP GET request. If one
408       is found it parses the file name into $1. Then we use $1 to create an
409       new IO::All file object... with a twist. If the file is executable
410       ("-x"), then we create a piped command as our IO::All object. This
411       somewhat approximates CGI support.
412
413       Whatever the resulting object is, we direct the contents back at our
414       socket which is in $_[0]. Pretty simple, eh?
415
416       DBM Files
417
418       IO::All file objects used as a hash reference, treat the file as a DBM
419       tied to a hash. Here I write my DB record to STDERR:
420
421           io("names.db")->{ingy} > io'=';
422
423       Since their are several DBM formats available in Perl, IO::All picks
424       the first one of these that is installed on your system:
425
426           DB_File GDBM_File NDBM_File ODBM_File SDBM_File
427
428       You can override which DBM you want for each IO::All object:
429
430           my @keys = keys %{io('mydbm')->dbm('SDBM_File')};
431
432       File Subclassing
433
434       Subclassing is easy with IO::All. Just create a new module and use
435       IO::All as the base class, like this:
436
437           package NewModule;
438           use IO::All -base;
439
440       You need to do it this way so that IO::All will export the "io" func‐
441       tion.  Here is a simple recipe for subclassing:
442
443       IO::Dumper inherits everything from IO::All and adds an extra method
444       called "dump", which will dump a data structure to the file we specify
445       in the "io" function. Since it needs Data::Dumper to do the dumping, we
446       override the "open" method to "require Data::Dumper" and then pass con‐
447       trol to the real "open".
448
449       First the code using the module:
450
451           use IO::Dumper;
452
453           io('./mydump')->dump($hash);
454
455       And next the IO::Dumper module itself:
456
457           package IO::Dumper;
458           use IO::All -base;
459           use Data::Dumper;
460
461           sub dump {
462               my $self = shift;
463               Dumper(@_) > $self;
464           }
465
466           1;
467
468       Inline Subclassing
469
470       This recipe does the same thing as the previous one, but without need‐
471       ing to write a separate module. The only real difference is the first
472       line.  Since you don't "use" IO::Dumper, you need to still call its
473       "import" method manually.
474
475           IO::Dumper->import;
476           io('./mydump')->dump($hash);
477
478           package IO::Dumper;
479           use IO::All -base;
480           use Data::Dumper;
481
482           sub dump {
483               my $self = shift;
484               Dumper(@_) > $self;
485           }
486

THE IO::All METHODS

488       This section gives a full description of all of the methods that you
489       can call on IO::All objects. The methods have been grouped into subsec‐
490       tions based on object construction, option settings, configuration,
491       action methods and support for specific modules.
492
493       Object Construction and Initialization Methods
494
495       * new
496           There are three ways to create a new IO::All object. The first is
497           with the special function "io" which really just calls
498           "IO::All->new".  The second is by calling "new" as a class method.
499           The third is calling "new" as an object instance method. In this
500           final case, the new objects attributes are copied from the instance
501           object.
502
503               io(file-descriptor);
504               IO::All->new(file-descriptor);
505               $io->new(file-descriptor);
506
507           All three forms take a single argument, a file descriptor. A file
508           descriptor can be any of the following:
509
510               - A file name
511               - A file handle
512               - A directory name
513               - A directory handle
514               - A typeglob reference
515               - A piped shell command. eq '⎪ ls -al'
516               - A socket domain/port.  eg 'perl.com:5678'
517               - '-' means STDIN or STDOUT (depending on usage)
518               - '=' means STDERR
519               - '$' means an IO::String object
520               - '?' means a temporary file
521               - A URI including: http, https, ftp and mailto
522               - An IO::All object
523
524           If you provide an IO::All object, you will simply get that same
525           object returned from the constructor.
526
527           If no file descriptor is provided, an object will still be created,
528           but it must be defined by one of the following methods before it
529           can be used for I/O:
530
531       * file
532               io->file(file-name);
533
534           Using the "file" method sets the type of the object to file and
535           sets the pathname of the file if provided.
536
537           It might be important to use this method if you had a file whose
538           name was '-', or if the name might otherwise be confused with a
539           directory or a socket. In this case, either of these statements
540           would work the same:
541
542               my $file = io('-')->file;
543               my $file = io->file('-');
544
545       * dir
546               io->file(dir-name);
547
548           Make the object be of type directory.
549
550       * socket
551               io->file(domain:port);
552
553           Make the object be of type socket.
554
555       * link
556               io->file(link-name);
557
558           Make the object be of type link.
559
560       * pipe
561               io->file(link-name);
562
563           Make the object be of type pipe. The following two statements are
564           equivalent:
565
566               my $io = io('ls -l ⎪');
567               my $io = io('ls -l')->pipe;
568               my $io = io->pipe('ls -l');
569
570       * dbm
571           This method takes the names of zero or more DBM modules. The first
572           one that is available is used to process the dbm file.
573
574               io('mydbm')->dbm('NDBM_File', 'SDBM_File')->{author} = 'ingy';
575
576           If no module names are provided, the first available of the follow‐
577           ing is used:
578
579               DB_File GDBM_File NDBM_File ODBM_File SDBM_File
580
581       * mldbm
582           Similar to the "dbm" method, except create a Multi Level DBM object
583           using the MLDBM module.
584
585           This method takes the names of zero or more DBM modules and an
586           optional serialization module. The first DBM module that is avail‐
587           able is used to process the MLDBM file. The serialization module
588           can be Data::Dumper, Storable or FreezeThaw.
589
590               io('mymldbm')->mldbm('GDBM_File', 'Storable')->{author} =
591                 {nickname => 'ingy'};
592
593       * string
594           Make the object be a IO::String object. These are equivalent:
595
596               my $io = io('$');
597               my $io = io->string;
598
599       * temp
600           Make the object represent a temporary file. It will automatically
601           be open for both read and write.
602
603       * stdio
604           Make the object represent either STDIN or STDOUT depending on how
605           it is used subsequently. These are equivalent:
606
607               my $io = io('-');
608               my $io = io->stdin;
609
610       * stdin
611           Make the object represent STDIN.
612
613       * stdout
614           Make the object represent STDOUT.
615
616       * stderr
617           Make the object represent STDERR.
618
619       * handle
620               io->handle(io-handle);
621
622           Forces the object to be created from an pre-existing IO handle. You
623           can chain calls together to indicate the type of handle:
624
625               my $file_object = io->file->handle($file_handle);
626               my $dir_object = io->dir->handle($dir_handle);
627
628       * http
629           Make the object represent an http uri. Requires IO-All-LWP.
630
631       * https
632           Make the object represent an https uri. Requires IO-All-LWP.
633
634       * ftp
635           Make the object represent a ftp uri. Requires IO-All-LWP.
636
637       * mailto
638           Make the object represent a mailto uri. Requires IO-All-Mailto.
639
640       If you need to use the same options to create a lot of objects, and
641       don't want to duplicate the code, just create a dummy object with the
642       options you want, and use that object to spawn other objects.
643
644           my $lt = io->lock->tie;
645           ...
646           my $io1 = $lt->new('file1');
647           my $io2 = $lt->new('file2');
648
649       Since the new method copies attributes from the calling object, both
650       $io1 and $io2 will be locked and tied.
651
652       Option Setting Methods
653
654       The following methods don't do any actual I/O, but they specify options
655       about how the I/O should be done.
656
657       Each option can take a single argument of 0 or 1. If no argument is
658       given, the value 1 is assumed. Passing 0 turns the option off.
659
660       All of these options return the object reference that was used to
661       invoke them. This is so that the option methods can be chained
662       together. For example:
663
664           my $io = io('path/file')->tie->assert->chomp->lock;
665
666       * absolute
667           Indicates that the "pathname" for the object should be made abso‐
668           lute.
669
670       * assert
671           This method ensures that the path for a file or directory actually
672           exists before the file is open. If the path does not exist, it is
673           created.
674
675       * autoclose
676           By default, IO::All will close an object opened for input when EOF
677           is reached. By closing the handle early, one can immediately do
678           other operations on the object without first having to close it.
679
680           This option is on by default, so if you don't want this behaviour,
681           say so like this:
682
683               $io->autoclose(0);
684
685           The object will then be closed when $io goes out of scope, or you
686           manually call "$io->close".
687
688       * autoflush
689           Proxy for IO::Handle::autoflush
690
691       * backwards
692           Sets the object to 'backwards' mode. All subsequent "getline" oper‐
693           ations will read backwards from the end of the file.
694
695           Requires the File::ReadBackwards CPAN module.
696
697       * binary
698           Indicates the file has binary content and should be opened with
699           "binmode".
700
701       * chdir
702           chdir() to the pathname of a directory object. When object goes out
703           of scope, chdir back to starting directory.
704
705       * chomp
706           Indicates that all operations that read lines should chomp the
707           lines. If the "separator" method has been called, chomp will remove
708           that value from the end of each record.
709
710       * confess
711           Errors should be reported with the very detailed Carp::confess
712           function.
713
714       * deep
715           Indicates that calls to the "all" family of methods should search
716           directories as deep as possible.
717
718       * fork
719           Indicates that the process should automatically be forked inside
720           the "accept" socket method.
721
722       * lock
723           Indicate that operations on an object should be locked using flock.
724
725       * rdonly
726           This option indicates that certain operations like DBM and
727           Tie::File access should be done in read-only mode.
728
729       * rdwr
730           This option indicates that DBM and MLDBM files should be opened in
731           read- write mode.
732
733       * relative
734           Indicates that the "pathname" for the object should be made rela‐
735           tive.
736
737       * sort
738           Indicates whether objects returned from one of the "all" methods
739           will be in sorted order by name. True by default.
740
741       * strict
742           Check the return codes of every single system call. To turn this on
743           for all calls in your module, use:
744
745               use IO::All -strict;
746
747       * tie
748           Indicate that the object should be tied to itself, thus allowing it
749           to be used as a filehandle in any of Perl's builtin IO operations.
750
751               my $io = io('foo')->tie;
752               @lines = <$io>;
753
754       * utf8
755           Indicates that IO should be done using utf8 encoding. Calls binmode
756           with ":utf8" layer.
757
758       Configuration Methods
759
760       The following methods don't do any actual I/O, but they set specific
761       values to configure the IO::All object.
762
763       If these methods are passed no argument, they will return their current
764       value. If arguments are passed they will be used to set the current
765       value, and the object reference will be returned for potential method
766       chaining.
767
768       * bcc
769           Set the Bcc field for a mailto object.
770
771       * binmode
772           Proxy for binmode. Requires a layer to be passed. Use "binary" for
773           plain binary mode.
774
775       * block_size
776           The default length to be used for "read" and "sysread" calls.
777           Defaults to 1024.
778
779       * buffer
780           Returns a reference to the internal buffer, which is a scalar. You
781           can use this method to set the buffer to a scalar of your choice.
782           (You can just pass in the scalar, rather than a reference to it.)
783
784           This is the buffer that "read" and "write" will use by default.
785
786           You can easily have IO::All objects use the same buffer:
787
788               my $input = io('abc');
789               my $output = io('xyz');
790               my $buffer;
791               $output->buffer($input->buffer($buffer));
792               $output->write while $input->read;
793
794       * cc
795           Set the Cc field for a mailto object.
796
797       * content
798           Get or set the content for an LWP operation manually.
799
800       * domain
801           Set the domain name or ip address that a socket should use.
802
803       * encoding
804           Set the encoding to be used for the PerlIO layer.
805
806       * errors
807           Use this to set a subroutine reference that gets called when an
808           internal error is thrown.
809
810       * filter
811           Use this to set a subroutine reference that will be used to grep
812           which objects get returned on a call to one of the "all" methods.
813           For example:
814
815               my @odd = io->curdir->filter(sub {$_->size % 2})->All_Files;
816
817           @odd will contain all the files under the current directory whose
818           size is an odd number of bytes.
819
820       * from
821           Indicate the sender for a mailto object.
822
823       * mailer
824           Set the mailer program for a mailto transaction. Defaults to 'send‐
825           mail'.
826
827       * mode
828           Set the mode for which the file should be opened. Examples:
829
830               $io->mode('>>')->open;
831               $io->mode(O_RDONLY);
832
833       * name
834           Set or get the name of the file or directory represented by the
835           IO::All object.
836
837       * password
838           Set the password for an LWP transaction.
839
840       * perms
841           Sets the permissions to be used if the file/directory needs to be
842           created.
843
844       * port
845           Set the port number that a socket should use.
846
847       * request
848           Manually specify the request object for an LWP transaction.
849
850       * response
851           Returns the resulting reponse object from an LWP transaction.
852
853       * separator
854           Sets the record (line) separator to whatever value you pass it.
855           Default is \n. Affects the chomp setting too.
856
857       * string_ref
858           Proxy for IO::String::string_ref
859
860           Returns a reference to the internal string that is acting like a
861           file.
862
863       * subject
864           Set the subject for a mailto transaction.
865
866       * to
867           Set the recipient address for a mailto request.
868
869       * uri
870           Direct access to the URI used in LWP transactions.
871
872       * user
873           Set the user name for an LWP transaction.
874
875       IO Action Methods
876
877       These are the methods that actually perform I/O operations on an
878       IO::All object. The stat methods and the File::Spec methods are docu‐
879       mented in separate sections below.
880
881       * accept
882           For sockets. Opens a server socket (LISTEN => 1, REUSE => 1).
883           Returns an IO::All socket object that you are listening on.
884
885           If the "fork" method was called on the object, the process will
886           automatically be forked for every connection.
887
888       * all
889           Read all contents into a single string.
890
891               compare(io('file1')->all, io('file2')->all);
892
893       * all (For directories)
894           Returns a list of IO::All objects for all files and subdirectories
895           in a directory.
896
897           '.' and '..' are excluded.
898
899           Takes an optional argument telling how many directories deep to
900           search. The default is 1. Zero (0) means search as deep as possi‐
901           ble.
902
903           The filter method can be used to limit the results.
904
905           The items returned are sorted by name unless "->sort(0)" is used.
906
907       * All
908           Same as all(0).
909
910       * all_dirs
911           Same as "all", but only return directories.
912
913       * All_Dirs
914           Same as all_dirs(0).
915
916       * all_files
917           Same as "all", but only return files.
918
919       * All_Files
920           Same as all_files(0).
921
922       * all_links
923           Same as "all", but only return links.
924
925       * All_Links
926           Same as all_links(0).
927
928       * append
929           Same as print, but sets the file mode to '>>'.
930
931       * appendf
932           Same as printf, but sets the file mode to '>>'.
933
934       * appendln
935           Same as println, but sets the file mode to '>>'.
936
937       * clear
938           Clear the internal buffer. This method is called by "write" after
939           it writes the buffer. Returns the object reference for chaining.
940
941       * close
942           Close will basically unopen the object, which has different mean‐
943           ings for different objects. For files and directories it will close
944           and release the handle. For sockets it calls shutdown. For tied
945           things it unties them, and it unlocks locked things.
946
947       * empty
948           Returns true if a file exists but has no size, or if a directory
949           exists but has no contents.
950
951       * eof
952           Proxy for IO::Handle::eof
953
954       * exists
955           Returns whether or not the file or directory exists.
956
957       * filename
958           Return the name portion of the file path in the object. For exam‐
959           ple:
960
961               io('my/path/file.txt')->filename;
962
963           would return "file.txt".
964
965       * fileno
966           Proxy for IO::Handle::fileno
967
968       * filepath
969           Return the path portion of the file path in the object. For exam‐
970           ple:
971
972               io('my/path/file.txt')->filename;
973
974           would return "my/path".
975
976       * get
977           Perform an LWP GET request manually.
978
979       * getc
980           Proxy for IO::Handle::getc
981
982       * getline
983           Calls IO::File::getline. You can pass in an optional record separa‐
984           tor.
985
986       * getlines
987           Calls IO::File::getlines. You can pass in an optional record sepa‐
988           rator.
989
990       * head
991           Return the first 10 lines of a file. Takes an optional argument
992           which is the number of lines to return. Works as expected in list
993           and scalar context. Is subject to the current line separator.
994
995       * io_handle
996           Direct access to the actual IO::Handle object being used on an
997           opened IO::All object.
998
999       * is_dir
1000           Returns boolean telling whether or not the IO::All object repre‐
1001           sents a directory.
1002
1003       * is_executable
1004           Returns true if file or directory is executable.
1005
1006       * is_dbm
1007           Returns boolean telling whether or not the IO::All object repre‐
1008           sents a dbm file.
1009
1010       * is_file
1011           Returns boolean telling whether or not the IO::All object repre‐
1012           sents a file.
1013
1014       * is_link
1015           Returns boolean telling whether or not the IO::All object repre‐
1016           sents a symlink.
1017
1018       * is_mldbm
1019           Returns boolean telling whether or not the IO::All object repre‐
1020           sents a mldbm file.
1021
1022       * is_open
1023           Indicates whether the IO::All is currently open for input/output.
1024
1025       * is_pipe
1026           Returns boolean telling whether or not the IO::All object repre‐
1027           sents a pipe operation.
1028
1029       * is_readable
1030           Returns true if file or directory is readable.
1031
1032       * is_socket
1033           Returns boolean telling whether or not the IO::All object repre‐
1034           sents a socket.
1035
1036       * is_stdio
1037           Returns boolean telling whether or not the IO::All object repre‐
1038           sents a STDIO file handle.
1039
1040       * is_string
1041           Returns boolean telling whether or not the IO::All object repre‐
1042           sents an IO::String object.
1043
1044       * is_temp
1045           Returns boolean telling whether or not the IO::All object repre‐
1046           sents a temporary file.
1047
1048       * is_writable
1049           Returns true if file or directory is writable.  Can also be spelled
1050           as "is_writeable".
1051
1052       * length
1053           Return the length of the internal buffer.
1054
1055       * mkdir
1056           Create the directory represented by the object.
1057
1058       * mkpath
1059           Create the directory represented by the object, when the path con‐
1060           tains more than one directory that doesn't exist. Proxy for
1061           File::Path::mkpath.
1062
1063       * next
1064           For a directory, this will return a new IO::All object for each
1065           file or subdirectory in the directory. Return undef on EOD.
1066
1067       * open
1068           Open the IO::All object. Takes two optional arguments "mode" and
1069           "perms", which can also be set ahead of time using the "mode" and
1070           "perms" methods.
1071
1072           NOTE: Normally you won't need to call open (or mode/perms), since
1073           this happens automatically for most operations.
1074
1075       * pathname
1076           Return the absolute or relative pathname for a file or directory,
1077           depending on whether object is in "absolute" or "relative" mode.
1078
1079       * print
1080           Proxy for IO::Handle::print
1081
1082       * printf
1083           Proxy for IO::Handle::printf
1084
1085       * println
1086           Same as print, but adds newline to each argument unless it already
1087           ends with one.
1088
1089       * put
1090           Perform an LWP PUT request manually.
1091
1092       * read
1093           This method varies depending on its context. Read carefully (no pun
1094           intended).
1095
1096           For a file, this will proxy IO::File::read. This means you must
1097           pass it a buffer, a length to read, and optionally a buffer offset
1098           for where to put the data that is read. The function returns the
1099           length actually read (which is zero at EOF).
1100
1101           If you don't pass any arguments for a file, IO::All will use its
1102           own internal buffer, a default length, and the offset will always
1103           point at the end of the buffer. The buffer can be accessed with the
1104           "buffer" method. The length can be set with the "block_size"
1105           method. The default length is 1024 bytes. The "clear" method can be
1106           called to clear the buffer.
1107
1108           For a directory, this will proxy IO::Dir::read.
1109
1110       * readdir
1111           Similar to the Perl "readdir" builtin. In scalar context, return
1112           the next directory entry (ie file or directory name), or undef on
1113           end of directory. In list context, return all directory entries.
1114
1115           Note that "readdir" does not return the special "." and ".."
1116           entries.
1117
1118       * readline
1119           Same as "getline".
1120
1121       * readlink
1122           Calls Perl's readlink function on the link represented by the
1123           object.  Instead of returning the file path, it returns a new
1124           IO::All object using the file path.
1125
1126       * recv
1127           Proxy for IO::Socket::recv
1128
1129       * rename
1130               my $new = $io->rename('new-name');
1131
1132           Calls Perl's rename function and returns an IO::All object for the
1133           renamed file. Returns false if the rename failed.
1134
1135       * rewind
1136           Proxy for IO::Dir::rewind
1137
1138       * rmdir
1139           Delete the directory represented by the IO::All object.
1140
1141       * rmtree
1142           Delete the directory represented by the IO::All object and all the
1143           files and directories beneath it. Proxy for File::Path::rmtree.
1144
1145       * scalar
1146           Deprecated. Same as "all()".
1147
1148       * seek
1149           Proxy for IO::Handle::seek. If you use seek on an unopened file, it
1150           will be opened for both read and write.
1151
1152       * send
1153           Proxy for IO::Socket::send
1154
1155       * shutdown
1156           Proxy for IO::Socket::shutdown
1157
1158       * slurp
1159           Read all file content in one operation. Returns the file content as
1160           a string. In list context returns every line in the file.
1161
1162       * stat
1163           Proxy for IO::Handle::stat
1164
1165       * sysread
1166           Proxy for IO::Handle::sysread
1167
1168       * syswrite
1169           Proxy for IO::Handle::syswrite
1170
1171       * tail
1172           Return the last 10 lines of a file. Takes an optional argument
1173           which is the number of lines to return. Works as expected in list
1174           and scalar context. Is subject to the current line separator.
1175
1176       * tell
1177           Proxy for IO::Handle::tell
1178
1179       * throw
1180           This is an internal method that gets called whenever there is an
1181           error.  It could be useful to override it in a subclass, to provide
1182           more control in error handling.
1183
1184       * touch
1185           Update the atime and mtime values for a file or directory. Creates
1186           an empty file if the file does not exist.
1187
1188       * truncate
1189           Proxy for IO::Handle::truncate
1190
1191       * type
1192           Returns a string indicated the type of io object. Possible values
1193           are:
1194
1195               file
1196               dir
1197               link
1198               socket
1199               string
1200               pipe
1201
1202           Returns undef if type is not determinable.
1203
1204       * unlink
1205           Unlink (delete) the file represented by the IO::All object.
1206
1207           NOTE: You can unlink a file after it is open, and continue using it
1208           until it is closed.
1209
1210       * unlock
1211           Release a lock from an object that used the "lock" method.
1212
1213       * utime
1214           Proxy for the utime Perl function.
1215
1216       * write
1217           Opposite of "read" for file operations only.
1218
1219           NOTE: When used with the automatic internal buffer, "write" will
1220           clear the buffer after writing it.
1221
1222       Stat Methods
1223
1224       This methods get individual values from a stat call on the file, direc‐
1225       tory or handle represented by th IO::All object.
1226
1227       * atime
1228           Last access time in seconds since the epoch
1229
1230       * blksize
1231           Preferred block size for file system I/O
1232
1233       * blocks
1234           Actual number of blocks allocated
1235
1236       * ctime
1237           Inode change time in seconds since the epoch
1238
1239       * device
1240           Device number of filesystem
1241
1242       * device_id
1243           Device identifier for special files only
1244
1245       * gid
1246           Numeric group id of file's owner
1247
1248       * inode
1249           Inode number
1250
1251       * modes
1252           File mode - type and permissions
1253
1254       * mtime
1255           Last modify time in seconds since the epoch
1256
1257       * nlink
1258           Number of hard links to the file
1259
1260       * size
1261           Total size of file in bytes
1262
1263       * uid
1264           Numeric user id of file's owner
1265
1266       File::Spec Methods
1267
1268       These methods are all adaptations from File::Spec. Each method actually
1269       does call the matching File::Spec method, but the arguments and return
1270       values differ slightly. Instead of being file and directory names, they
1271       are IO::All objects. Since IO::All objects stringify to their names,
1272       you can generally use the methods just like File::Spec.
1273
1274       * abs2rel
1275           Returns the relative path for the absolute path in the IO::All
1276           object.  Can take an optional argument indicating the base path.
1277
1278       * canonpath
1279           Returns the canonical path for the IO::All object.
1280
1281       * case_tolerant
1282           Returns 0 or 1 indicating whether the file system is case tolerant.
1283           Since an active IO::All object is not needed for this function, you
1284           can code it like:
1285
1286               IO::All->case_tolerant;
1287
1288           or more simply:
1289
1290               io->case_tolerant;
1291
1292       * catdir
1293           Concatenate the directory components together, and return a new
1294           IO::All object representing the resulting directory.
1295
1296       * catfile
1297           Concatenate the directory and file components together, and return
1298           a new IO::All object representing the resulting file.
1299
1300               my $contents = io->catfile(qw(dir subdir file))->slurp;
1301
1302           This is a very portable way to read "dir/subdir/file".
1303
1304       * catpath
1305           Concatenate the volume, directory and file components together, and
1306           return a new IO::All object representing the resulting file.
1307
1308       * curdir
1309           Returns an IO::All object representing the current directory.
1310
1311       * devnull
1312           Returns an IO::All object representing the /dev/null file.
1313
1314       * is_absolute
1315           Returns 0 or 1 indicating whether the "name" field of the IO::All
1316           object is an absolute path.
1317
1318       * join
1319           Same as "catfile".
1320
1321       * path
1322           Returns a list of IO::All directory objects for each directory in
1323           your path.
1324
1325       * rel2abs
1326           Returns the absolute path for the relative path in the IO::All
1327           object. Can take an optional argument indicating the base path.
1328
1329       * rootdir
1330           Returns an IO::All object representing the root directory on your
1331           file system.
1332
1333       * splitdir
1334           Returns a list of the directory components of a path in an IO::All
1335           object.
1336
1337       * splitpath
1338           Returns a volume directory and file component of a path in an
1339           IO::All object.
1340
1341       * tmpdir
1342           Returns an IO::All object representing a temporary directory on
1343           your file system.
1344
1345       * updir
1346           Returns an IO::All object representing the current parent direc‐
1347           tory.
1348

OPERATIONAL NOTES

1350       ·   Each IO::All object gets reblessed into an IO::All::* object as
1351           soon as IO::All can determine what type of object it should be.
1352           Sometimes it gets reblessed more than once:
1353
1354               my $io = io('mydbm.db');
1355               $io->dbm('DB_File');
1356               $io->{foo} = 'bar';
1357
1358           In the first statement, $io has a reference value of
1359           'IO::All::File', if "mydbm.db" exists. In the second statement, the
1360           object is reblessed into class 'IO::All::DBM'.
1361
1362       ·   An IO::All object will automatically be opened as soon as there is
1363           enough contextual information to know what type of object it is,
1364           and what mode it should be opened for. This is usually when the
1365           first read or write operation is invoked but might be sooner.
1366
1367       ·   The mode for an object to be opened with is determined heuristi‐
1368           cally unless specified explicitly.
1369
1370       ·   For input, IO::All objects will automatically be closed after EOF
1371           (or EOD). For output, the object closes when it goes out of scope.
1372
1373           To keep input objects from closing at EOF, do this:
1374
1375               $io->autoclose(0);
1376
1377       ·   You can always call "open" and "close" explicitly, if you need that
1378           level of control. To test if an object is currently open, use the
1379           "is_open" method.
1380
1381       ·   Overloaded operations return the target object, if one exists.
1382
1383           This would set $xxx to the IO::All object:
1384
1385               my $xxx = $contents > io('file.txt');
1386
1387           While this would set $xxx to the content string:
1388
1389               my $xxx = $contents < io('file.txt');
1390

STABILITY

1392       The goal of the IO::All project is to continually refine the module to
1393       be as simple and consistent to use as possible. Therefore, in the early
1394       stages of the project, I will not hesitate to break backwards compati‐
1395       bility with other versions of IO::All if I can find an easier and
1396       clearer way to do a particular thing.
1397
1398       IO is tricky stuff. There is definitely more work to be done. On the
1399       other hand, this module relies heavily on very stable existing IO mod‐
1400       ules; so it may work fairly well.
1401
1402       I am sure you will find many unexpected "features". Please send all
1403       problems, ideas and suggestions to ingy@cpan.org.
1404
1405       Known Bugs and Deficiencies
1406
1407       Not all possible combinations of objects and methods have been tested.
1408       There are many many combinations. All of the examples have been tested.
1409       If you find a bug with a particular combination of calls, let me know.
1410
1411       If you call a method that does not make sense for a particular object,
1412       the result probably won't make sense. Little attempt is made to check
1413       for improper usage.
1414

SEE ALSO

1416       IO::Handle, IO::File, IO::Dir, IO::Socket, IO::String, File::Spec,
1417       File::Path, File::ReadBackwards, Tie::File
1418

CREDITS

1420       A lot of people have sent in suggestions, that have become a part of
1421       IO::All. Thank you.
1422
1423       Special thanks to Ian Langworth for continued testing and patching.
1424
1425       Thank you Simon Cozens for tipping me off to the overloading possibili‐
1426       ties.
1427
1428       Finally, thanks to Autrijus Tang, for always having one more good idea.
1429
1430       (It seems IO::All of it to a lot of people!)
1431

AUTHOR

1433       Ingy döt Net <ingy@cpan.org>
1434
1436       Copyright (c) 2004. Brian Ingerson. All rights reserved.
1437
1438       Copyright (c) 2006. Ingy döt Net. All rights reserved.
1439
1440       This program is free software; you can redistribute it and/or modify it
1441       under the same terms as Perl itself.
1442
1443       See <http://www.perl.com/perl/misc/Artistic.html>
1444
1445
1446
1447perl v5.8.8                       2007-04-07                        IO::All(3)
Impressum