IO::Any(3pm)

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

NAME

6       IO::Any - open anything
7

SYNOPSIS

9           # NOTE commented out lines doesn't work (yet)
10           use IO::Any;
11
12           $fh = IO::Any->read('filename');
13           $fh = IO::Any->read('file://var/log/syslog');
14           #$fh = IO::Any->read('http://search.cpan.org/');
15           #$fh = IO::Any->read('-');
16           $fh = IO::Any->read(['folder', 'other-folder', 'filename']);
17           $fh = IO::Any->read('folder');
18           $fh = IO::Any->read("some text\nwith more lines\n");
19           $fh = IO::Any->read(\"some text\nwith more lines\n");
20           $fh = IO::Any->read('{"123":[1,2,3]}');
21           $fh = IO::Any->read('<root><element>abc</element></root>');
22           $fh = IO::Any->read(*DATA);
23           $fh = IO::Any->read(IO::String->new("cba"));
24           #$fh = IO::Any->read($object_with_toString_method);
25
26           $fh = IO::Any->write('filename');
27           $fh = IO::Any->write('file://var/log/syslog');
28           #$fh = IO::Any->write('-');
29           $fh = IO::Any->write(['folder', 'filename']);
30           #$fh = IO::Any->write('=');
31           my $string;
32           $fh = IO::Any->write(\$string);
33
34           my $content = IO::Any->slurp(['folder', 'filename']);
35           IO::Any->spew(['folder2', 'filename'], $content);
36
37           perl -MIO::Any -le 'print IO::Any->slurp("/etc/passwd")'
38           perl -MIO::Any -le 'IO::Any->spew("/tmp/timetick", time())'
39

DESCRIPTION

41       The aim is to provide read/write anything. The module tries to guess
42       $what the "anything" is based on some rules. See "new" method Pod for
43       examples and "new" and "_guess_what" code for the implementation.
44
45       There are two methods "slurp" and "spew" to read/write whole $what.
46

MOTIVATION

48       The purpose is to be able to use IO::Any in other modules that needs to
49       read or write data. The description for an argument could be - pass
50       anything that IO::Any accepts as argument - GLOBs, IO::File,
51       Path::Class::File, IO::AtomicFile, IO::String, pointers to scalar and
52       pointer to array (array elements are passed to "catfile" in File::Spec
53       as portable file addressing).
54
55       First time I've used IO::Any for JSON::Util where for the functions to
56       encode and decode needs to read/write data.
57

METHODS

59   new($what, $how, $options)
60       Open $what in $how mode.
61
62       $what can be:
63
64                       'filename'                => [ 'file' => 'filename' ],
65                       'folder/filename'         => [ 'file' => 'folder/filename' ],
66                       'file:///folder/filename' => [ 'file' => '/folder/filename' ],
67                       [ 'folder', 'filename' ]  => [ 'file' => File::Spec->catfile('folder', 'filename') ],
68                       'http://a/b/c'            => [ 'http' => 'http://a/b/c' ],
69                       'https://a/b/c'           => [ 'http' => 'https://a/b/c' ],
70                       '{"123":[1,2,3]}'         => [ 'string' => '{"123":[1,2,3]}' ],
71                       '[1,2,3]'                 => [ 'string' => '[1,2,3]' ],
72                       '<xml></xml>'             => [ 'string' => '<xml></xml>' ],
73                       "a\nb\nc\n"               => [ 'string' => "a\nb\nc\n" ],
74                       *DATA                     => [ 'file' => *{DATA}{IO} ],
75
76       Returns filehandle. IO::String for 'string', IO::File for 'file'.
77       'http' not implemented yet.
78
79       Here are available %$options options:
80
81           atomic    true/false if the file operations should be done using L<IO::AtomicFile> or L<IO::File>
82           LOCK_SH   lock file for shared access
83           LOCK_EX   lock file for exclusive
84           LOCK_NB   lock file non blocking (will throw an excpetion if file is
85                         already locked, instead of blocking the process)
86
87   _guess_what
88       Returns ($type, $what). $type can be:
89
90           file
91           string
92           http
93           iostring
94           iofile
95
96       $what is normalized path that can be used for IO::*.
97
98   read($what)
99       Same as "IO::Any->new($what, '<');" or "IO::Any->new($what);".
100
101   write($what)
102       Same as "IO::Any->new($what, '>');"
103
104   slurp($what)
105       Returns content of $what.
106
107       If AnyEvent is loaded then uses event loop to read the content.
108
109   spew($what, $data, $opt)
110       Writes $data to $what.
111
112       If AnyEvent is loaded then uses event loop to write the content.
113

AUTHOR

118       Jozef Kutej, "<jkutej at cpan.org>"
119

CONTRIBUTORS

121       The following people have contributed to the Sys::Path by committing
122       their code, sending patches, reporting bugs, asking questions,
123       suggesting useful advice, nitpicking, chatting on IRC or commenting on
124       my blog (in no particular order):
125
126           SREZIC [...] cpan.org
127           Alexandr Ciornii
128           Gabor Szabo
129           Przemek Wesołek
130           Slaven Rezić
131

BUGS

133       Please report any bugs or feature requests to "bug-io-any at
134       rt.cpan.org", or through the web interface at
135       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IO-Any>.  I will be
136       notified, and then you'll automatically be notified of progress on your
137       bug as I make changes.
138

SUPPORT

140       You can find documentation for this module with the perldoc command.
141
142           perldoc IO::Any
143
144       You can also look for information at:
145
146       •   GitHub: issues
147
148           <http://github.com/jozef/IO-Any/issues>
149
150       •   RT: CPAN's request tracker
151
152           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=IO-Any>
153
154       •   AnnoCPAN: Annotated CPAN documentation
155
156           <http://annocpan.org/dist/IO-Any>
157
158       •   CPAN Ratings
159
160           <http://cpanratings.perl.org/d/IO-Any>
161
162       •   Search CPAN
163
164           <http://search.cpan.org/dist/IO-Any>
165

COPYRIGHT & LICENSE

167       Copyright 2009 Jozef Kutej, all rights reserved.
168
169       This program is free software; you can redistribute it and/or modify it
170       under the same terms as Perl itself.
171
172
173
174perl v5.36.0                      2023-01-20                        IO::Any(3)