diff --git a/CHANGELOG.md b/CHANGELOG.md index 88e792ea..00277ca8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All Notable changes to `Csv` will be documented in this file -## [Next](https://github.com/thephpleague/csv/compare/9.17.0...master) - TBD +## [9.18.0](https://github.com/thephpleague/csv/compare/9.17.0...9.18.0) - 2024-10-18 ### Added @@ -12,6 +12,7 @@ All Notable changes to `Csv` will be documented in this file ### Deprecated - `League\Csv\AbstractCsv::output` use `League\Csv\AbstractCsv::download` instead +- `League\Csv\FragmentFinder` and derived methods are marked as **experimental** as their results will be changed in the next major version. ### Fixed diff --git a/docs/9.0/reader/statement.md b/docs/9.0/reader/statement.md index 1ba8766a..1043834f 100644 --- a/docs/9.0/reader/statement.md +++ b/docs/9.0/reader/statement.md @@ -409,6 +409,10 @@ documents or `TabularDataReader` instances if needed. ## FragmentFinder

This mechanism is introduced with version 9.12.0.

+

This implementation is marked as experimetal since version 9.12.0. +The public API is stable but the implementation and returned value will change in the next version to +take into account edge cases and improve error and selection handling. It is recommended to avoid using +the current implementation or restrict its usage for simple selection in version 9.

The second mechanism is based on [RFC7111](https://www.rfc-editor.org/rfc/rfc7111) and allow selecting part of your document according to its rows, columns or cells coordinates. The RFC, and thus, our class diff --git a/src/FragmentFinder.php b/src/FragmentFinder.php index d0bc54c0..51178fd8 100644 --- a/src/FragmentFinder.php +++ b/src/FragmentFinder.php @@ -25,7 +25,11 @@ use const FILTER_VALIDATE_INT; /** + * EXPERIMENTAL WARNING! This class implementation will change in the next major point release. + * * @phpstan-type selection array{selection:string, start:int<-1, max>, end:?int, length:int, columns:array} + * + * @experimental */ class FragmentFinder { @@ -42,8 +46,13 @@ public static function create(): self } /** - * @throws SyntaxError + * EXPERIMENTAL WARNING! This method implementation will change in the next major point release. * + * Extract all found fragment identifiers for the specifield tabular data + * + * @experimental since version 9.12.0 + * + * @throws SyntaxError * @return iterable */ public function findAll(string $expression, TabularDataReader $tabularDataReader): iterable @@ -52,6 +61,12 @@ public function findAll(string $expression, TabularDataReader $tabularDataReader } /** + * EXPERIMENTAL WARNING! This method implementation will change in the next major point release. + * + * Extract the first found fragment identifier of the tabular data or returns null + * + * @experimental since version 9.12.0 + * * @throws SyntaxError */ public function findFirst(string $expression, TabularDataReader $tabularDataReader): ?TabularDataReader @@ -65,6 +80,12 @@ public function findFirst(string $expression, TabularDataReader $tabularDataRead } /** + * EXPERIMENTAL WARNING! This method implementation will change in the next major point release. + * + * Extract the first found fragment identifier of the tabular data or fail + * + * @experimental since version 9.12.0 + * * @throws SyntaxError * @throws FragmentNotFound if the expression can not be parsed */ diff --git a/src/Reader.php b/src/Reader.php index d41e63f3..5168d1c8 100644 --- a/src/Reader.php +++ b/src/Reader.php @@ -411,17 +411,42 @@ public function sorted(Query\Sort|Closure $orderBy): TabularDataReader return Statement::create()->orderBy($orderBy)->process($this); } + /** + * EXPERIMENTAL WARNING! This method implementation will change in the next major point release. + * + * Extract all found fragment identifiers for the specifield tabular data + * + * @experimental since version 9.12.0 + * + * @throws SyntaxError + * @return iterable + */ public function matching(string $expression): iterable { return FragmentFinder::create()->findAll($expression, $this); } + /** + * EXPERIMENTAL WARNING! This method implementation will change in the next major point release. + * + * Extract the first found fragment identifier of the tabular data or returns null + * + * @experimental since version 9.12.0 + * + * @throws SyntaxError + */ public function matchingFirst(string $expression): ?TabularDataReader { return FragmentFinder::create()->findFirst($expression, $this); } /** + * EXPERIMENTAL WARNING! This method implementation will change in the next major point release. + * + * Extract the first found fragment identifier of the tabular data or fail + * + * @experimental since version 9.12.0 + * * @throws SyntaxError * @throws FragmentNotFound */ diff --git a/src/ResultSet.php b/src/ResultSet.php index bfde262d..013d0424 100644 --- a/src/ResultSet.php +++ b/src/ResultSet.php @@ -259,17 +259,42 @@ public function select(string|int ...$columns): TabularDataReader return new self(new MapIterator($this, $callback), $hasHeader ? $header : []); } + /** + * EXPERIMENTAL WARNING! This method implementation will change in the next major point release. + * + * Extract all found fragment identifiers for the specifield tabular data + * + * @experimental since version 9.12.0 + * + * @throws SyntaxError + * @return iterable + */ public function matching(string $expression): iterable { return FragmentFinder::create()->findAll($expression, $this); } + /** + * EXPERIMENTAL WARNING! This method implementation will change in the next major point release. + * + * Extract the first found fragment identifier of the tabular data or returns null + * + * @experimental since version 9.12.0 + * + * @throws SyntaxError + */ public function matchingFirst(string $expression): ?TabularDataReader { return FragmentFinder::create()->findFirst($expression, $this); } /** + * EXPERIMENTAL WARNING! This method implementation will change in the next major point release. + * + * Extract the first found fragment identifier of the tabular data or fail + * + * @experimental since version 9.12.0 + * * @throws SyntaxError * @throws FragmentNotFound */