1NAME
2 IO::Any - open anything
3
4SYNOPSIS
5 # NOTE commented out lines doesn't work (yet)
6 use IO::Any;
7
8 $fh = IO::Any->read('filename');
9 $fh = IO::Any->read('file://var/log/syslog');
10 #$fh = IO::Any->read('http://search.cpan.org/');
11 #$fh = IO::Any->read('-');
12 $fh = IO::Any->read(['folder', 'other-folder', 'filename']);
13 $fh = IO::Any->read('folder');
14 $fh = IO::Any->read("some text\nwith more lines\n");
15 $fh = IO::Any->read(\"some text\nwith more lines\n");
16 $fh = IO::Any->read('{"123":[1,2,3]}');
17 $fh = IO::Any->read('<root><element>abc</element></root>');
18 $fh = IO::Any->read(*DATA);
19 $fh = IO::Any->read(IO::String->new("cba"));
20 #$fh = IO::Any->read($object_with_toString_method);
21
22 $fh = IO::Any->write('filename');
23 $fh = IO::Any->write('file://var/log/syslog');
24 #$fh = IO::Any->write('-');
25 $fh = IO::Any->write(['folder', 'filename']);
26 #$fh = IO::Any->write('=');
27 my $string;
28 $fh = IO::Any->write(\$string);
29
30 my $content = IO::Any->slurp(['folder', 'filename']);
31 IO::Any->spew(['folder2', 'filename'], $content);
32
33 perl -MIO::Any -le 'print IO::Any->slurp("/etc/passwd")'
34 perl -MIO::Any -le 'IO::Any->spew("/tmp/timetick", time())'
35
36DESCRIPTION
37 The aim is to provide read/write anything. The module tries to guess
38 `$what' the "anything" is based on some rules. See new method Pod for
39 examples and the new and _guess_what entries elsewhere in this document
40 code for the implementation.
41
42 There are two methods the slurp and spew entries elsewhere in this
43 document to read/write whole `$what'.
44
45MOTIVATION
46 The purpose is to be able to use IO::Any in other modules that needs to
47 read or write data. The description for an argument could be - pass
48 anything that IO::Any accepts as argument - GLOBs, IO::File,
49 Path::Class::File, IO::AtomicFile, IO::String, pointers to scalar and
50 pointer to array (array elements are passed to File::Spec as portable
51 file addressing).
52
53 First time I've used IO::Any for JSON::Util where for the functions to
54 encode and decode needs to read/write data.
55
56METHODS
57 new($what, $how, $options)
58 Open `$what' in `$how' mode.
59
60 `$what' can be:
61
62 'filename' => [ 'file' => 'filename' ],
63 'folder/filename' => [ 'file' => 'folder/filename' ],
64 'file:///folder/filename' => [ 'file' => '/folder/filename' ],
65 [ 'folder', 'filename' ] => [ 'file' => File::Spec->catfile('folder', 'filename') ],
66 'http://a/b/c' => [ 'http' => 'http://a/b/c' ],
67 'https://a/b/c' => [ 'http' => 'https://a/b/c' ],
68 '{"123":[1,2,3]}' => [ 'string' => '{"123":[1,2,3]}' ],
69 '[1,2,3]' => [ 'string' => '[1,2,3]' ],
70 '<xml></xml>' => [ 'string' => '<xml></xml>' ],
71 "a\nb\nc\n" => [ 'string' => "a\nb\nc\n" ],
72 *DATA => [ 'file' => *{DATA}{IO} ],
73
74 Returns filehandle. IO::String for 'string', IO::File for 'file'. 'http'
75 not implemented yet.
76
77 Here are available `%$options' options:
78
79 atomic true/false if the file operations should be done using L<IO::AtomicFile> or L<IO::File>
80 LOCK_SH lock file for shared access
81 LOCK_EX lock file for exclusive
82 LOCK_NB lock file non blocking (will throw an excpetion if file is
83 already locked, instead of blocking the process)
84
85 _guess_what
86 Returns ($type, $what). $type can be:
87
88 file
89 string
90 http
91 iostring
92 iofile
93
94 `$what' is normalized path that can be used for IO::*.
95
96 read($what)
97 Same as `IO::Any->new($what, '<');' or `IO::Any->new($what);'.
98
99 write($what)
100 Same as `IO::Any->new($what, '>');'
101
102 slurp($what)
103 Returns content of `$what'.
104
105 If AnyEvent is loaded then uses event loop to read the content.
106
107 spew($what, $data, $opt)
108 Writes `$data' to `$what'.
109
110 If AnyEvent is loaded then uses event loop to write the content.
111
112SEE ALSO
113 IO::All, File::Spec, Path::Class
114
115AUTHOR
116 Jozef Kutej, `<jkutej at cpan.org>'
117
118CONTRIBUTORS
119 The following people have contributed to the Sys::Path by committing
120 their code, sending patches, reporting bugs, asking questions,
121 suggesting useful advice, nitpicking, chatting on IRC or commenting on
122 my blog (in no particular order):
123
124 SREZIC [...] cpan.org
125 Alexandr Ciornii
126 Gabor Szabo
127 Przemek Wesołek
128 Slaven Rezić
129
130BUGS
131 Please report any bugs or feature requests to `bug-io-any at
132 rt.cpan.org', or through the web interface at
133 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IO-Any. I will be
134 notified, and then you'll automatically be notified of progress on your
135 bug as I make changes.
136
137SUPPORT
138 You can find documentation for this module with the perldoc command.
139
140 perldoc IO::Any
141
142 You can also look for information at:
143
144 * GitHub: issues
145 http://github.com/jozef/IO-Any/issues
146
147 * RT: CPAN's request tracker
148 http://rt.cpan.org/NoAuth/Bugs.html?Dist=IO-Any
149
150 * AnnoCPAN: Annotated CPAN documentation
151 http://annocpan.org/dist/IO-Any
152
153 * CPAN Ratings
154 http://cpanratings.perl.org/d/IO-Any
155
156 * Search CPAN
157 http://search.cpan.org/dist/IO-Any
158
159COPYRIGHT & LICENSE
160 Copyright 2009 Jozef Kutej, all rights reserved.
161
162 This program is free software; you can redistribute it and/or modify it
163 under the same terms as Perl itself.
164
165