IO::Any(3)

📦
version 0.09 · 4 versions
, in epel 9

💅 IO::Any(3) — the IO::Any manual page, bestie edition 🎀

okay so this is the page for IO::Any, and honestly? it's giving "one module to rule them all" energy. it opens anything. files, strings, arrays, XML, JSON-looking stuff, globs — everything. let's get into it ✨

🌸 NAME 🌸

IO::Any — open anything. literally anything. no cap. 💅

✨ SYNOPSIS ✨

quick little vibe check on the code, keep it exactly like this because these are the actual calls:

    # NOTE commented out lines doesn't work (yet)
    use IO::Any;

    $fh = IO::Any->read('filename');
    $fh = IO::Any->read('file://var/log/syslog');
    #$fh = IO::Any->read('http://search.cpan.org/');
    #$fh = IO::Any->read('-');
    $fh = IO::Any->read(['folder', 'other-folder', 'filename']);
    $fh = IO::Any->read('folder');
    $fh = IO::Any->read("some text\nwith more lines\n");
    $fh = IO::Any->read(\"some text\nwith more lines\n");
    $fh = IO::Any->read('{"123":[1,2,3]}');
    $fh = IO::Any->read('<root><element>abc</element></root>');
    $fh = IO::Any->read(*DATA);
    $fh = IO::Any->read(IO::String->new("cba"));
    #$fh = IO::Any->read($object_with_toString_method);

    $fh = IO::Any->write('filename');
    $fh = IO::Any->write('file://var/log/syslog');
    #$fh = IO::Any->write('-');
    $fh = IO::Any->write(['folder', 'filename']);
    #$fh = IO::Any->write('=');
    my $string;
    $fh = IO::Any->write(\$string);

    my $content = IO::Any->slurp(['folder', 'filename']);
    IO::Any->spew(['folder2', 'filename'], $content);

    perl -MIO::Any -le 'print IO::Any->slurp("/etc/passwd")'
    perl -MIO::Any -le 'IO::Any->spew("/tmp/timetick", time())'
🫶 heads up bestie — the commented-out lines don't work (yet). they're future plans, not features. don't @ me.

💖 DESCRIPTION 💖

the whole point of this module is to give you read/write access to basically anything. it looks at $what and tries to guess what kind of thing you handed it, based on some rules. wanna see the examples? peep the new method Pod. wanna see how the sausage gets made? peep the new and _guess_what source code. iykyk 🔍

there are also two extra-special methods, slurp and spew, that read/write the whole entire $what in one go. one bite, whole thing. 🍓

🦋 MOTIVATION 🦋

the goal here is to let other modules use IO::Any whenever they need to read or write data, so they don't have to care about what kind of thing you passed in. the way an argument gets described can basically be: "pass anything that IO::Any accepts as an argument" — GLOBs, IO::File, Path::Class::File, IO::AtomicFile, IO::String, pointers to scalar, and pointer to array (array elements get passed to catfile in File::Spec as portable file addressing). chef's kiss 🌈

fun fact: this module was originally born for JSON::Util, where the encode/decode functions need to read and write data. main character origin story, honestly 👑

🔥 METHODS 🔥

💜 new($what, $how, $options)

open $what in $how mode. simple as that.

here's what $what can be, and what it turns into:

                'filename'                => [ 'file' => 'filename' ],
                'folder/filename'         => [ 'file' => 'folder/filename' ],
                'file:///folder/filename' => [ 'file' => '/folder/filename' ],
                [ 'folder', 'filename' ]  => [ 'file' => File::Spec->catfile('folder', 'filename') ],
                'http://a/b/c'            => [ 'http' => 'http://a/b/c' ],
                'https://a/b/c'           => [ 'http' => 'https://a/b/c' ],
                '{"123":[1,2,3]}'         => [ 'string' => '{"123":[1,2,3]}' ],
                '[1,2,3]'                 => [ 'string' => '[1,2,3]' ],
                '<xml></xml>'             => [ 'string' => '<xml></xml>' ],
                "a\nb\nc\n"               => [ 'string' => "a\nb\nc\n" ],
                *DATA                     => [ 'file' => *{DATA}{IO} ],

it returns a filehandle 🫶. IO::String for 'string', IO::File for 'file'. also: 'http' is not implemented yet — so don't come for me, it's on the list 💀

these are the %$options options you got available:

  • atomic — true/false, says whether the file operations should be done using IO::AtomicFile or IO::File
  • LOCK_SH — lock the file for shared access
  • LOCK_EX — lock the file for exclusive access
  • LOCK_NB — lock the file non-blocking (this one will throw an exception if the file is already locked, instead of just blocking the process — so like, it does not wait around 💅)

🧚 _guess_what

returns ($type, $what). $type can be:

    file
    string
    http
    iostring
    iofile

$what is the normalized path that you can use for IO::*. slay ✨

⭐ read($what)

same as IO::Any->new($what, '<'); or IO::Any->new($what);. both work, pick your fave 💖

⭐ write($what)

same as IO::Any->new($what, '>');

🌸 slurp($what)

returns the content of $what. easy.

ooh and if AnyEvent is loaded, it uses the event loop to read the content. fancy 💅

🌸 spew($what, $data, $opt)

writes $data to $what.

and same deal — if AnyEvent is loaded, it uses the event loop to write the content. 🔥

👀 SEE ALSO 👀

IO::All, File::Spec, Path::Class — go give them a little visit, they're iconic too 🎀

💜 AUTHOR 💜

Jozef Kutej, "<jkutej at cpan.org>" — the legend who made all this happen 👑

🫶 CONTRIBUTORS 🫶

the following people have contributed to the Sys::Path by committing their code, sending patches, reporting bugs, asking questions, suggesting useful advice, nitpicking, chatting on IRC or commenting on my blog (in no particular order, we don't rank our friends here):

    SREZIC [...] cpan.org
    Alexandr Ciornii
    Gabor Szabo
    Przemek WesoXek
    Slaven ReziX

every single one of y'all ate 💅💖

🙈 BUGS 🙈

please report any bugs or feature requests to "bug-io-any at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IO-Any>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. so like, you'll never be left on read 📲✨

🌈 SUPPORT 🌈

you can find documentation for this module with the perldoc command, bestie:

    perldoc IO::Any

you can also look for information at:

  • GitHub: issues

<http://github.com/jozef/IO-Any/issues>

  • RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=IO-Any>

  • AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/IO-Any>

  • CPAN Ratings

<http://cpanratings.perl.org/d/IO-Any>

  • Search CPAN

<http://search.cpan.org/dist/IO-Any>

Copyright 2009 Jozef Kutej, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

okay and that's the whole page bestie, you're officially an IO::Any girlie now 💅✨

tiny sign-off from the footer so nothing gets lost: this is perl v5.32.1, dated 2022-01-21, and it's the IO::Any(3) manpage. mwah 🫶
📦 where this page comes from