thekid/rfc — Issue #174: RFC 0174: io.collections interface additions / io.streams integration
Author: thekid
Created: 2011-10-09 15:35:21+00:00
State: open

Scope of Change
====
New methods will be added to the io.collections.IOElement interface:
* Origin accessors: Return / set the collection these elements originate from
* Stream accessors: Return streams to read from / write to this element

Rationale
====
Transparent iteration on filesystem, FTP and other implementations.

Functionality
====
Discovering the origin of an IOElement returned from an iteration may
be used for debugging and display purposes. It will be complemented by
a setter for iterators to inject the collection:

```php

```

To read from and write to elements returned from an iteration process,
this API will be collected to the io.streams API:

```php

```

Example
----
Consider the following sourcecode:

```php
getURI())); // !!!
}
?>
```

If we exchange `$origin`, which holds a FileCollection, with a
FtpCollection (for instance, others see below) the `file_get_contents()`
call will break.

More I/O Collections
----
The following implementations exist or are drafted:

* io.collections.FileCollection - filesystem
* io.collections.XarCollection - XAR archives
* peer.ftp.collections.FtpCollection - FTP directories
* io.zip.collections.ZipCollection - inside ZIP archives (see xp-framework/rfc #175)

Corrected version
----

```php
getInputStream(); $is->available() > 0; ) {
Console::write($is->read());
}
}
?>
```

Supporting additions
----
To read an IOElements' contents completely into a buffer in a single call,
the `io.streams.Streams` class will be extended:

```php
getInputStream()));
}
?>
```

Security considerations
====
None.

Speed impact
====
None.

Dependencies
====
Dependency `io.collections -> io.streams`

Related documents
====
[http://xp-framework.net/rfc/contrib/rfc0174.diff Implementing patch]

Comments
====
friebe, Tue Oct 21 10:41:36 2008
----
Should `io.streams.Streams::readAll()` close the stream it gets
passed or should it have a parameter `boolean close= TRUE`?

friebe, Thu Feb 5 20:27:29 2009
----
The `readAll()` method will not close the stream.