Enhancement: Implement SequentialValueGenerator

CHANGELOG.md

@@ -13,11 +13,13 @@ For a full diff see [`f4208b3...main`][f4208b3...main].
 - Added `ValueGenerator` ([#1]), by [@localheinz]
 - Added `OptionalValueGenerator` ([#2]), by [@localheinz]
 - Added `ConcatenatingValueGenerator` ([#3]), by [@localheinz]
+- Added `SequentialValueGenerator` ([#4]), by [@localheinz]
 
 [f4208b3...main]: https://github.com/ergebnis/data-generator/compare/f4208b3...main
 
 [#1]: https://github.com/ergebnis/data-generator/pull/1
 [#2]: https://github.com/ergebnis/data-generator/pull/2
 [#3]: https://github.com/ergebnis/data-generator/pull/3
+[#4]: https://github.com/ergebnis/data-generator/pull/4
 
 [@localheinz]: https://github.com/localheinz

README.md

@@ -28,6 +28,7 @@ This project comes with the following data generators:
 
 - [`Ergebnis\DataGenerator\ConcatenatingValueGenerator`](#ConcatenatingValuegenerator)
 - [`Ergebnis\DataGenerator\OptionalValueGenerator`](#optionalvaluegenerator)
+- [`Ergebnis\DataGenerator\SequentialValueGenerator`](#sequentialvaluegenerator)
 - [`Ergebnis\DataGenerator\ValueGenerator`](#valuegenerator)
 
 ### `ConcatenatingValueGenerator`
@@ -93,6 +94,40 @@ foreach ($generator->generate() as $value) {
 // baz
 ```
 
+### `SequentialValueGenerator`
+
+Use the `SequentialValueGenerator` to generate one or more values from one or more `StringGenerator`s:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Ergebnis\DataGenerator;
+
+$generator = new DataGenerator\SequentialValueGenerator(
+    new DataGenerator\ValueGenerator(
+        'foo',
+        'bar',
+        'baz',
+    ),
+    new DataGenerator\ValueGenerator(
+      'qux',
+      'quux',
+    ),
+);
+
+foreach ($generator->generate() as $value) {
+    echo $value . PHP_EOL
+}
+
+// foo
+// bar
+// baz
+// qux
+// quux
+```
+
 ### `ValueGenerator`
 
 Use the `ValueGenerator` to generate one or more values from a list of `string` values:

psalm-baseline.xml

@@ -10,6 +10,11 @@
       <code>$values</code>
     </MixedArgument>
   </file>
+  <file src="test/Unit/SequentialValueGeneratorTest.php">
+    <MixedArgument>
+      <code>$values</code>
+    </MixedArgument>
+  </file>
   <file src="test/Unit/ValueGeneratorTest.php">
     <MixedArgument>
       <code>$values</code>

src/SequentialValueGenerator.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Copyright (c) 2023 Andreas Möller
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE.md file that was distributed with this source code.
+ *
+ * @see https://github.com/ergebnis/data-generator
+ */
+
+namespace Ergebnis\DataGenerator;
+
+final class SequentialValueGenerator implements StringGenerator
+{
+    /**
+     * @var array<StringGenerator>
+     */
+    private readonly array $generators;
+
+    /**
+     * @throws Exception\InvalidGeneratorsException
+     */
+    public function __construct(StringGenerator ...$generators)
+    {
+        if ([] === $generators) {
+            throw Exception\InvalidGeneratorsException::empty();
+        }
+
+        $this->generators = $generators;
+    }
+
+    public function generate(): \Generator
+    {
+        foreach ($this->generators as $generator) {
+            foreach ($generator->generate() as $value) {
+                yield $value;
+            }
+        }
+    }
+}

test/Unit/SequentialValueGeneratorTest.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Copyright (c) 2023 Andreas Möller
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE.md file that was distributed with this source code.
+ *
+ * @see https://github.com/ergebnis/data-generator
+ */
+
+use Ergebnis\DataGenerator\Exception;
+use Ergebnis\DataGenerator\SequentialValueGenerator;
+use Ergebnis\DataGenerator\Test;
+use Ergebnis\DataGenerator\ValueGenerator;
+use PHPUnit\Framework;
+
+#[Framework\Attributes\CoversClass(SequentialValueGenerator::class)]
+#[Framework\Attributes\UsesClass(Exception\InvalidGeneratorsException::class)]
+#[Framework\Attributes\UsesClass(ValueGenerator::class)]
+final class SequentialValueGeneratorTest extends Framework\TestCase
+{
+    use Test\Util\Helper;
+
+    public function testConstructorRejectsEmptyGenerators(): void
+    {
+        $this->expectException(Exception\InvalidGeneratorsException::class);
+
+        new SequentialValueGenerator();
+    }
+
+    public function testGenerateReturnsGeneratorThatYieldsValuesFromOneGenerator(): void
+    {
+        $values = self::faker()->words();
+
+        $generator = new SequentialValueGenerator(new ValueGenerator(...$values));
+
+        $generated = \iterator_to_array($generator->generate());
+
+        self::assertSame($values, $generated);
+    }
+
+    public function testGenerateReturnsGeneratorThatYieldsValuesFromTwoGenerators(): void
+    {
+        $generator = new SequentialValueGenerator(
+            new ValueGenerator(
+                'foo',
+                'bar',
+                'baz',
+            ),
+            new ValueGenerator(
+                'qux',
+                'quux',
+            ),
+        );
+
+        $generated = \iterator_to_array($generator->generate());
+
+        $expected = [
+            'foo',
+            'bar',
+            'baz',
+            'qux',
+            'quux',
+        ];
+
+        self::assertSame($expected, $generated);
+    }
+}