Updates: Remove units, add controversial ability to read lines to iterator to direct usage in app

Author: jakubboucek

README.md

@@ -41,9 +41,17 @@ You can write result to file or another stream, use methods:
 
 ```php
  ->toFile('path/to/your/output.txt'); // Write to file
- ->toStream($stream);                 // Write to stream 
+ ->toStream($stream);                 // Write to stream
+ ->toIterator();                      // Get iterator containting lines as strings
 ```
 
+> [!WARNING]  
+> The `->toIterator()` method reads the every line to memory. Use it carefully - when you load huge file with very long
+> lines, it can cause memory issues. Be aware especially when you load unknown files, when file doesn't have line
+> separators (e.g. if you accidentally load binary file), whole file will be loaded to memory. To prevent unexpected
+> behavior is method limited to 1MB of data. You can change this limit by passing the argument `$maxLineSize`.
+
+
 ## License
 
 The MIT License (MIT). Please see [License File](LICENSE) for more information.

src/Builder/Input.php

@@ -9,10 +9,10 @@
 use JakubBoucek\Tail\Stream\FileMode;
 use JakubBoucek\Tail\Stream\Stream;
 use JakubBoucek\Tail\Tail;
+use Traversable;
 
 class Input
 {
-
     private Stream $input;
     private Tail $tail;
 
@@ -24,12 +24,12 @@ public function __construct(Tail $tail, Stream $input)
 
     public function toFile(string $file): void
     {
-        $this->tail->process($this->input, new File($file, FileMode::Write));
+        $this->tail->processStream($this->input, new File($file, FileMode::Write));
     }
 
     public function toStream($stream): void
     {
-        $this->tail->process($this->input, new ExternalStream($stream));
+        $this->tail->processStream($this->input, new ExternalStream($stream));
     }
 
     public function toOutput(): void
@@ -38,6 +38,11 @@ public function toOutput(): void
             ? new ExternalStream(STDOUT)
             : new File('php://output', FileMode::Write);
 
-        $this->tail->process($this->input, $output);
+        $this->tail->processStream($this->input, $output);
+    }
+
+    public function toIterator(int $maxLineSize = Tail::DefaultMaxLineSize): Traversable
+    {
+        return $this->tail->processIterator($this->input, $maxLineSize);
     }
 }

src/Processor.php

@@ -7,6 +7,7 @@
 use JakubBoucek\Tail\Exceptions\IOException;
 use JakubBoucek\Tail\Stream\Stream;
 use LogicException;
+use Traversable;
 
 class Processor
 {
@@ -31,6 +32,38 @@ public function lines(
         $outputStream->close();
     }
 
+    /**
+     * @param int $count Count if lines
+     * @param Stream $inputStream Input stream
+     * @param int $blocksSizes Size of blocks to read during backward search of lines - affects consumed memory
+     * @param int $maxLineSize Size of maximal size of line - if line is longer, it will be split
+     * @param string $delimiter Delimiter of lines
+     * @return Traversable<string> Searched lines as string
+     */
+    public function linesIterator(
+        int $count,
+        Stream $inputStream,
+        int $blocksSizes,
+        int $maxLineSize,
+        string $delimiter
+    ): Traversable {
+        $input = $inputStream->open();
+
+        [$start, $end] = $this->searchLines($count, $input, $blocksSizes, $delimiter);
+
+        $this->seek($input, $start);
+
+        do {
+            $line = stream_get_line($input, $maxLineSize, $delimiter);
+            if ($line === false) {
+                break;
+            }
+            yield $line;
+        } while (ftell($input) < $end);
+
+        $inputStream->close();
+    }
+
     /**
      * @param resource $input
      */

src/Tail.php

@@ -6,34 +6,35 @@
 
 use JakubBoucek\Tail\Builder\Setup;
 use JakubBoucek\Tail\Stream\Stream;
+use Traversable;
 
 class Tail
 {
+    public const DefaultMaxLineSize = 2 ** 20;
+
     private int $blockSize = 4096;
     private string $rowDelimiter = "\n";
     private int $count;
-    private Units $units;
 
-    /**
-     * @param Units $units (unused - for future use)
-     */
-    public function __construct(int $count = 10, Units $units = Units::Lines)
+    public function __construct(int $count = 10)
     {
         $this->count = $count;
-        $this->units = $units;
     }
 
     public static function lines(int $count): Setup
     {
-        return new Setup(new Tail($count, Units::Lines));
+        return new Setup(new Tail($count));
+    }
+
+    public function processStream(Stream $input, Stream $output): void
+    {
+        $processor = new Processor();
+        $processor->lines($this->count, $input, $output, $this->blockSize, $this->rowDelimiter);
     }
 
-    public function process(Stream $input, Stream $output): void
+    public function processIterator(Stream $input, int $maxLineSize = self::DefaultMaxLineSize): Traversable
     {
         $processor = new Processor();
-        match ($this->units) {
-            Units::Lines => $processor->lines($this->count, $input, $output, $this->blockSize, $this->rowDelimiter),
-            //Units::Bytes => $processor->bytes($this->count, $input, $output, $this->bufferSize),
-        };
+        return $processor->linesIterator($this->count, $input, $this->blockSize, $maxLineSize, $this->rowDelimiter);
     }
 }

src/Units.php

@@ -12,6 +12,7 @@
 
 require __DIR__ . '/bootstrap.php';
 
+/** @testCase */
 class ProcessorTest extends TestCase
 {
     public function dataSearchInBlock(): array
@@ -130,10 +131,7 @@ public function testLines(
         fseek($input, 0);
 
         $processor = new Processor();
-        // Method is private - use closure
-        $method = new ReflectionMethod(Processor::class, 'lines');
-        $closure = $method->getClosure($processor);
-        $closure($count, $inputSteam, $outputStream, $blocksSizes, $delimiter);
+        $processor->lines($count, $inputSteam, $outputStream, $blocksSizes, $delimiter);
 
         fseek($output, 0);
         $result = stream_get_contents($output);
@@ -143,6 +141,41 @@ public function testLines(
 
         Assert::equal($expected, $result);
     }
+
+    public function dataLinesIterator(): array
+    {
+        return [
+            ['a.......a......a.....a....a', ['......','.....','....'], 'a', 3, 1024, 1_000_000],
+            ['....b....b....b....', ['....','....','....'], 'b', 3, 1024, 1_000_000],
+        ];
+    }
+    /**
+     * @dataProvider dataLinesIterator
+     */
+    public function testLinesIterator(
+        string $content,
+        array $expected,
+        string $delimiter,
+        int $count,
+        int $blocksSizes,
+        int $maxLineSize,
+    ):void
+    {
+        $input = fopen('php://memory', 'wb+');
+        $inputSteam = new ExternalStream($input);
+
+        fwrite($input, $content);
+        fseek($input, 0);
+
+        $processor = new Processor();
+        $iterator = $processor->linesIterator($count, $inputSteam, $blocksSizes, $maxLineSize, $delimiter);
+
+        $result = iterator_to_array($iterator);
+
+        fclose($input);
+
+        Assert::equal($expected, $result);
+    }
 }
 
 (new ProcessorTest())->run();