Stars: 332
Forks: 20
Pull Requests: 32
Issues: 10
Watchers: 11
Last Updated: 2021-04-29 19:09:54
Hoa is a modular, extensible and
structured set of PHP libraries.
Moreover, Hoa aims at being a bridge between industrial and research worlds.
This library provides a set of useful iterator (compatible with PHP iterators). Existing PHP iterators have been updated to get new features and prior PHP versions compatibility.
With Composer, to include this library into
your dependencies, you need to
require hoa/iterator
:
$ composer require hoa/iterator '~2.0'
For more installation procedures, please read the Source page.
Before running the test suites, the development dependencies must be installed:
$ composer install
Then, to run all the test suites:
$ vendor/bin/hoa test:run
For more information, please read the contributor guide.
We propose a quick overview of all iterators.
Hoa\Iterator\Iterator
defines the basis of an iterator. It extends
Iterator
.
Hoa\Iterator\Aggregate
allows a class to use an external iterator through the
getIterator
method. It extends
IteratorAggregate
Hoa\Iterator\IteratorIterator
transforms anything that is
traversable into an iterator. It extends
IteratorIterator
.
Hoa\Iterator\Outer
represents an iterator that iterates over iterators. It
extends OuterIterator
.
Hoa\Iterator\Mock
represents an empty iterator. It extends
EmptyIterator
.
Hoa\Iterator\Seekable
represents an iterator that can be seeked. It extends
SeekableIterator
.
Hoa\Iterator\Map
allows to iterate an array. It extends
ArrayIterator
.
$foobar = new Hoa\Iterator\Map(['f', 'o', 'o', 'b', 'a', 'r']);
foreach ($foobar as $value) {
echo $value;
}
/**
* Will output:
* foobar
*/
Hoa\Iterator\Filter
and Hoa\Iterator\CallbackFilter
allows to filter the
content of an iterator. It extends
FilterIterator
and
CallbackFilterIterator
.
$filter = new Hoa\Iterator\CallbackFilter(
$foobar,
function ($value, $key, $iterator) {
return false === in_array($value, ['a', 'e', 'i', 'o', 'u']);
}
);
foreach ($filter as $value) {
echo $value;
}
/**
* Will output:
* fbr
*/
Also, Hoa\Iterator\RegularExpression
allows to filter based on a regular
expression.
Hoa\Iterator\Limit
allows to iterate n elements of an iterator starting from
a specific offset. It extends LimitIterator
.
$limit = new Hoa\Iterator\Limit($foobar, 2, 3);
foreach ($limit as $value) {
echo $value;
}
/**
* Will output:
* oba
*/
Hoa\Iterator\Infinite
allows to iterate over and over again the same iterator.
It extends InfiniteIterator
.
$infinite = new Hoa\Iterator\Infinite($foobar);
$limit = new Hoa\Iterator\Limit($infinite, 0, 21);
foreach ($limit as $value) {
echo $value;
}
/**
* Will output:
* foobarfoobarfoobarfoo
*/
Also, Hoa\Iterator\NoRewind
is an iterator that does not rewind. It extends
NoRewindIterator
.
Hoa\Iterator\Repeater
allows to repeat an iterator n times.
$repeater = new Hoa\Iterator\Repeater(
$foobar,
3,
function ($i) {
echo "\n";
}
);
foreach ($repeater as $value) {
echo $value;
}
/**
* Will output:
* foobar
* foobar
* foobar
*/
Hoa\Iterator\Counter
is equivalent to a for($i = $from, $i < $to, $i += $step)
loop.
$counter = new Hoa\Iterator\Counter(0, 12, 3);
foreach ($counter as $value) {
echo $value, ' ';
}
/**
* Will output:
* 0 3 6 9
*/
Hoa\Iterator\Append
allows to iterate over iterators one after another. It
extends AppendIterator
.
$counter1 = new Hoa\Iterator\Counter(0, 12, 3);
$counter2 = new Hoa\Iterator\Counter(13, 23, 2);
$append = new Hoa\Iterator\Append();
$append->append($counter1);
$append->append($counter2);
foreach ($append as $value) {
echo $value, ' ';
}
/**
* Will output:
* 0 3 6 9 13 15 17 19 21
*/
Hoa\Iterator\Multiple
allows to iterate over several iterator at the same
times. It extends MultipleIterator
.
$foobar = new Hoa\Iterator\Map(['f', 'o', 'o', 'b', 'a', 'r']);
$baz = new Hoa\Iterator\Map(['b', 'a', 'z']);
$multiple = new Hoa\Iterator\Multiple(
Hoa\Iterator\Multiple::MIT_NEED_ANY
| Hoa\Iterator\Multiple::MIT_KEYS_ASSOC
);
$multiple->attachIterator($foobar, 'one', '!');
$multiple->attachIterator($baz, 'two', '?');
foreach ($multiple as $iterators) {
echo $iterators['one'], ' | ', $iterators['two'], "\n";
}
/**
* Will output:
* f | b
* o | a
* o | z
* b | ?
* a | ?
* r | ?
*/
Hoa\Iterator\Demultiplexer
demuxes result from another iterator. This iterator
is somehow the opposite of the Hoa\Iterator\Multiple
iterator.
$counter = new Hoa\Iterator\Counter(0, 10, 1);
$multiple = new Hoa\Iterator\Multiple();
$multiple->attachIterator($counter);
$multiple->attachIterator(clone $counter);
$demultiplexer = new Hoa\Iterator\Demultiplexer(
$multiple,
function ($current) {
return $current[0] * $current[1];
}
);
foreach ($demultiplexer as $value) {
echo $value, ' ';
}
/**
* Will output:
* 0 1 4 9 16 25 36 49 64 81
*/
Hoa\Iterator\Directory
and Hoa\Iterator\FileSystem
allow to iterate the file
system where files are represented by instances of Hoa\Iterator\SplFileInfo
.
They respectively extend
DirectoryIterator
,
FilesystemIterator
and
SplFileInfo
.
$directory = new Hoa\Iterator\Directory(resolve('hoa://Library/Iterator'));
foreach ($directory as $value) {
echo $value->getFilename(), "\n";
}
/**
* Will output:
* .
* ..
* .State
* Aggregate.php
* Append.php
* CallbackFilter.php
* composer.json
* Counter.php
* Demultiplexer.php
* …
*/
Also, the Hoa\Iterator\Glob
allows to iterator with the glob strategy. It
extends GlobIterator
. Thus:
$glob = new Hoa\Iterator\Glob(resolve('hoa://Library/Iterator') . '/M*.php');
foreach ($glob as $value) {
echo $value->getFilename(), "\n";
}
/**
* Will output:
* Map.php
* Mock.php
* Multiple.php
*/
Hoa\Iterator\Lookahead
allows to look ahead for the next element:
$counter = new Hoa\Iterator\Counter(0, 5, 1);
$lookahead = new Hoa\Iterator\Lookahead($counter);
foreach ($lookahead as $value) {
echo $value;
if (true === $lookahead->hasNext()) {
echo ' (next: ', $lookahead->getNext(), ')';
}
echo "\n";
}
/**
* Will output:
* 0 (next: 1)
* 1 (next: 2)
* 2 (next: 3)
* 3 (next: 4)
* 4
*/
The Hoa\Iterator\Lookbehind
also exists and allows to look behind for the
previous element.
Hoa\Iterator\Buffer
allows to move forward as usual but also backward up to a
given buffer size over another iterator:
$abcde = new Hoa\Iterator\Map(['a', 'b', 'c', 'd', 'e']);
$buffer = new Hoa\Iterator\Buffer($abcde, 3);
$buffer->rewind();
echo $buffer->current(); // a
$buffer->next();
echo $buffer->current(); // b
$buffer->next();
echo $buffer->current(); // c
$buffer->previous();
echo $buffer->current(); // b
$buffer->previous();
echo $buffer->current(); // a
$buffer->next();
echo $buffer->current(); // b
/**
* Will output:
* abcbab
*/
Hoa\Iterator\CallbackGenerator
allows to transform any callable into an
iterator. This is very useful when combined with other iterators, for instance
with Hoa\Iterator\Limit
:
$generator = new Hoa\Iterator\CallbackGenerator(function ($key) {
return mt_rand($key, $key * 2);
});
$limit = new Hoa\Iterator\Limit($generator, 0, 10);
foreach ($limit as $value) {
echo $value, ' ';
}
/**
* Could output:
* 0 2 3 4 4 7 8 10 12 18
*/
A recursive iterator is an iterator where its values is other iterators. The
most important interface is Hoa\Iterator\Recursive\Recursive
(it extends
RecursiveIterator
). Then we find (in
alphabetic order):
Hoa\Iterator\Recursive\CallbackFilter
(it extends
RecursiveCallbackFilterIterator
),Hoa\Iterator\Recursive\Directory
(it extends
RecursiveDirectoryIterator
),Hoa\Iterator\Recursive\Filter
(it extends
RecursiveFilterIterator
),Hoa\Iterator\Recursive\Iterator
(it extends
RecursiveIteratorIterator
),Hoa\Iterator\Recursive\Map
(it extends
RecursiveArrayIterator
),Hoa\Iterator\Recursive\Mock
,Hoa\Iterator\Recursive\RegularExpression
(it extends RecursiveRegularExpression
).The
hack book of Hoa\Iterator
contains
detailed information about how to use this library and how it works.
To generate the documentation locally, execute the following commands:
$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open
More documentation can be found on the project's website: hoa-project.net.
There are mainly two ways to get help:
#hoaproject
IRC channel,Do you want to contribute? Thanks! A detailed contributor guide explains everything you need to know.
Hoa is under the New BSD License (BSD-3-Clause). Please, see
LICENSE
for details.