|Welcome to the Monastery|
My main objection to this module is that it's a catch-all for everything. If I do
then, what is it? What do I expect it to be, a file, a directory? It can be either. It can even be something else entirely, I don't know.
Yet, later on, if it's a directory, I can do $foo->next, if it's a file, I can do $foo->slurp, but not vice versa.
This is the exact opposite of where strong typing wants to go: bugs aren't visible at compile time, it won't even complain at run time before you've already gone deep into the code: at the time of the next/slurp call.
I don't like this. If you want a dir, say so. If you want a file, idem ditto. The module shouldn't have to guess. Because the chances are, it guesses wrong.
No, I don't think one constructor io() for everything is a proper API.
Ideally, I'd like an io::dir() call to produce a directory thingy, and a io::file() call for a file. These look nice, but, as those a fully qualified names, thus you can't subclass them. io_dir() or io_file() don't look even half as nice.