IO::All this crap to mst, frew, and Mithaldu

gistfile1.md

This is this a little doc to talk about how IO::All should behave in a more perfect implementation:

First we support these variations, from formal, to whipitup.

# All the same:
use IO::All;
IO::All::File->new(pathname => 'foo.txt')->open('w')->println('hello world')->close;
IO::All::File->new(pathname => 'foo.txt')->open('w')->println('hello world');
IO::All::File->new(pathname => 'foo.txt')->println('hello world');
IO::All->new->file('foo.txt')->println('hello world');
io->file('foo.txt')->println('hello world');
io('foo.txt')->println('hello world');

We also support:

use IO::All -overload;
io('foo.txt') < 'hello world';

Operator overloading should not be on by default.

The DWIM form only supports ::File and ::Dir by default. In other words:

# No
use IO::All;
$html = io('http://example.com/foo')->get;

# Yes
use IO::All;
use IO::All::HTTP;
$html = io('http://example.com/foo')->get;

# Yes also:
use IO::All with => ['HTTP'];
$html = io('http://example.com/foo')->get;

Also:

• All operations die (throw exceptions) (with good msging) on failure. (strawman)
• IO::All plugins can register their DWIMs to the current scope.
• The io() export, is scoped (at most) to the current package.
  • See below for possible tighter scoping.
• An IO::All object created with explicit new, has immutable slots (strawman).
• Otherwise chaining is support everywhere it makes sense. (ie read can't chain, but write can).

Dash usage options act as default operations:

# This
use IO::All;
io('foo')->utf8->print('ok');
# Can be:
use IO::All -utf8;
io('foo')->print('ok');

To get 2 different io constructors in one namespace (advanced usage):

# Normal `io` exported constructor:
use IO::All;
# One with utf8 and HTTP, exported as `io8`:
use IO::All -overload, -utf8, with => ['HTTP'], as => 'io8';
# use together
io8('file8') << io('file');

(Idea) To limit the scope of an IO::All exported constructor to a block use -local:

use IO::All -local, ...<options>...;