dev-master / 2.1.x-dev 2016-09-26 12:05 UTC

README

Build Status

ZerusTech IO Component

The ZerusTech IO Component provides some commonly used I/O related classes, such as some input stream and output stream classes.

This library was developed along with the zerustech/terminal component, when we could not find the stream implementations that best fit our requirements.

Installation

You can install this component in 2 different ways:

  • Install it via Composer
$ cd <project-root-directory>
$ composer require zerustech/io

Examples

FileInputStream

A file input stream obtains input bytes from a file.

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Input\FileInputStream;

$input = new FileInputStream('foo.txt', 'rb');

$count = $input->read($string, 10); // reads upto 10 bytes from foo.txt

printf("%d bytes read: %s\n", $count, $string);

StringInputStream

This class allows an application to create an input stream in which the bytes are supplied by the contents of a string.

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Input\StringInputStream;

$input = new StringInputStream("hello, world!");

$count = $input->read($string, 5); // returns 'hello'

printf("%d bytes read: %s\n", $count, $string);

BufferedInputStream

This class allows an application to create an input stream that buffers input from an underlying implementation.

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Input\StringInputStream;
use ZerusTech\Component\IO\Stream\Input\BufferedInputStream;

$input = new StringInputStream("0123456789ABCDEF");

$buffer = new BufferedInputStream($input, 4);

//  buffer:
//  ------
//  0123 
// ^ (mark)
//    ^ (pos)
//      ^ (count)
$buffer->skip(2);

//  buffer:
//  -------
//  0123 
//    ^ (mark)
//    ^ (pos)
//      ^ (count)
$buffer->mark(6);

//  buffer:
//  -------
//  01234567
//    ^ (mark)
//         ^ (pos)
//          ^ (count)
$count = $buffer->read($string, 5);

printf("%d bytes read: %s\n", $count, $string); // "23456"

//  buffer:
//  -------
//  01234567
//    ^ (mark)
//    ^ (pos)
//          ^ (count)
$buffer->reset();

//  buffer:
//  -------
//  01234567
//    ^ (mark)
//       ^ (pos)
//          ^ (count)
$count = $buffer->read($string, 3);

printf("%d bytes read: %s\n", $count, $string); // "234"

//  buffer:
//  -------
//  89AB
// ^ (mark)
//   ^ (pos)
//      ^ (count)
$count = $buffer->read($string, 4);

printf("%d bytes read: %s\n", $count, $string); // "5678"

LineInputStream

This class reads one line each time from the subordinate stream. Unlike the fgets() function, it does not have limit on the length of the line.

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Input\StringInputStream;
use ZerusTech\Component\IO\Stream\Input\LineInputStream;

$in = new LineInputStream(new StringInputStream("ABC\nDEF\r\nHIJ"));

printf("%s", $in->readLine()); // ABC\n

printf("%s", $in->readLine()); // DEF\r\n

printf("%s", $in->readLine()); // HIJ

PushbackInputStream

This class provides the ability to unread data from a stream. It maintains an internal buffer of unread data that is supplied to the next read operation. This is conceptually similar to mark/reset functionality, except that in this case the position to reset the stream to does not need to be known

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Input\PushbackInputStream;
use ZerusTech\Component\IO\Stream\Input\StringInputStream;

// The default pushback buffer size is 1 bytes, let's change it to 5 bytes.
$stream = new PushbackInputStream(new StringInputStream('hello'), 5);

$count = $stream->read($string, 2);

printf("%d bytes read: %s\n", $count, $string); // "he"

$stream->unread($string); // Now, pushback 'he' to the stream.

$count = $stream->read($string, 2);

printf("%d bytes read: %s\n", $count, $string); // "he"

FileOutputStream

A file output stream is an output stream for writing data to a file.

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Output\FileOutputStream;

$out = new FileOutputStream('foo.txt', 'wb');

$count = $out->write('hello, world!');

printf("%d bytes written.\n", $count);

StringOutputStream

This class writes bytes to a string. This is useful for connecting a string with other streams.

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Output\StringOutputStream;

$out = new StringOutputStream();

$count = $out->write('hello');

printf("%d bytes written: %s\n", $count, $out->__toString()); // "hello"

PipedInputStream and PipedOutputStream

The PipedInputStream and PipedOutputStream can be connected to create a communication pipe. The PipedOutputStream writes data to the PipedInputStream.

The implementation in this component is not thread-safe, so it does not support wait and notify features. For piped stream classes in multi-threaded environment, check zerustech/threaded for details.

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Input\PipedInputStream;
use ZerusTech\Component\IO\Stream\Output\PipedOutputStream;

$output = new PipedOutputStream();

$input = new PipedInputStream($output);

$output->write('hello');

$count = $input->read($data, 5); // returns 'hello'

printf("%d bytes read: %s\n", $count, $data);

FilterInputStreamFactoryInterface and FilterInputStreamFactory

Factory classes that implement the FilterInputStreamFactoryInterface interface, creates specific filter input stream instances.

The factory classes should also implement the support() method to test if the filter input stream supports the data format of the subordinate input stream.

It's typically used by a filter input stream factory resolver to resolve a suitable factory.

The FilterInputStreamFactory is the default implementation of the factory interface, which supports any buffered input stream.

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Input\Factory\FilterInputStreamFactory;
use ZerusTech\Component\IO\Stream\Input\StringInputStream;
use ZerusTech\Component\IO\Stream\Input\BufferedInputStream;

// In order to detect the data format, the factory need fetch some leading bytes
// from the subordinate stream, so it must support mark and reset.
$in = new BufferedInputStream(new StringInputStream('hello'));

$factory = new FilterInputStreamFactory();

if ($factory->support($in)) {

    $filter = $factory->create($in);

    $count = $filter->read($string, 5);

    printf("%d bytes read: %s\n", $count, $string);
}

FilterInputStreamResolverInterface and FilterInputStreamResolver

This interface detects the data format of the input stream and resolves it to a filter input stream that is suitable for parsing the data format.

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\IO\Stream\Input\Factory\FilterInputStreamFactory;
use ZerusTech\Component\IO\Stream\Input\Resolver\FilterInputStreamResolver;
use ZerusTech\Component\IO\Stream\Input\StringInputStream;
use ZerusTech\Component\IO\Stream\Input\BufferedInputStream;

$in = new BufferedInputStream(new StringInputStream('hello'));
$factory = new FilterInputStreamFactory();
$resolver = new FilterInputStreamResolver();
$resolver->addFactory($factory);

if (null !==($filter = $resolver->resolve($in))) {

    $count = $filter->read($string, 5);

    printf("%d bytes read: %s\n", $count, $string);
}

References

License

The ZerusTech IO Component is published under the MIT License.