Add a new DataFrame::renameEach() (#1615)

Add a new `DataFrame::renameEach()`
Add a new functions `rename_style()`, `rename_replace()` & `rename_transliterate()`
Deprecate `Flow\ETL\DataFrame::renameAll()`
Deprecate `Flow\ETL\DataFrame::renameAllLowerCase()`
Deprecate `Flow\ETL\DataFrame::renameAllUpperCase()`
Deprecate `Flow\ETL\DataFrame::renameAllUpperCaseFirst()`
Deprecate `Flow\ETL\DataFrame::renameAllUpperCaseWord()`
Deprecate `Flow\ETL\RenameAllCaseTransformer`
Deprecate `Flow\ETL\RenameStrReplaceAllEntriesTransformer`

Author: stloyd

documentation/upgrading.md

@@ -5,13 +5,34 @@ Please follow the instructions for your specific version to ensure a smooth upgr
 
 ---
 
+## Upgrading from 0.15.x to 0.16.x
+
+### 1) Deprecated `Flow\ETL\DataFrame::renameAll*` methods
+
+Methods:
+- `Flow\ETL\DataFrame::renameAll()`,
+- `Flow\ETL\DataFrame::renameAllLowerCase()`,
+- `Flow\ETL\DataFrame::renameAllUpperCase()`,
+- `Flow\ETL\DataFrame::renameAllUpperCaseFirst()`,
+- `Flow\ETL\DataFrame::renameAllUpperCaseWord()`,
+
+Were deprecated in favor of using new method: `DataFrame::renameEach()` with proper `RenameEntryStrategy` object.
+
+### 2) Deprecated `RenameAllCaseTransformer` & `RenameStrReplaceAllEntriesTransformer`
+
+Selected transformers were deprecated in favor of using `DataFrame::renameEach()` with related `RenameEntryStrategy`:
+- `RenameAllCaseTransformer` -> `RenameCaseTransformer`,
+- `RenameStrReplaceAllEntriesTransformer` -> `RenameReplaceStrategy`,
+
+---
+
 ## Upgrading from 0.14.x to 0.15.x
 
-### 1) Removed `Flow\ETL\Row\Schema\Matcher` and implementations 
-Schema Matcher was the initial attempt to implement a schema evolution next to schema validation that over 
-time got replaced with different implementation of Schema Validator. 
+### 1) Removed `Flow\ETL\Row\Schema\Matcher` and implementations
+Schema Matcher was the initial attempt to implement a schema evolution next to schema validation that over
+time got replaced with a different implementation of Schema Validator.
 
-### 2) Renamed `Flow\ETL\Row\Schema` namespace into `Flow\ETL\Schema`. 
+### 2) Renamed `Flow\ETL\Row\Schema` namespace into `Flow\ETL\Schema`.
 This means all classes related to Schema now live under `Flow\ETL\Schema` namespace.
 
 ---
@@ -24,7 +45,7 @@ The old method is now deprecated and will be removed in the next release.
 
 ### 2) Replaced `Flow\ETL\Function\ScalarFunction\TypedScalarFunction` with `Flow\ETL\Function\ScalarFunction\ScalarResult`.
 
-The old interface was used to allow define the return type of the ScalarFunctions. 
+The old interface was used to allow defining the return type of the ScalarFunctions. 
 It was replaced with a ScalarResult value object that is much more flexible than the interface,
 because it's allowing to return any type dynamically without making the scalar function stateful. 
 
@@ -52,10 +73,10 @@ type_structure([
 
 From now options for: 
 
-- to_dbal_table_insert()
-- to_db_table_update()
+- `to_dbal_table_insert()`
+- `to_db_table_update()`
 
-are passed as an objects (instance of UpdateOptions|InsertOptions interfaces) and they are platform specific,
+are passed as objects (instance of UpdateOptions|InsertOptions interfaces) and they are platform specific,
 so please use the proper class for the platform you are using.
 
 - PostgreSQL
@@ -71,9 +92,9 @@ so please use the proper class for the platform you are using.
 ## Upgrading from 0.8.x to 0.10.x
 
 
-### 1) Providing multiple paths to single extractor
+### 1) Providing multiple paths to a single extractor
 
-From now in order to read from multiple locations use `from_all(Extractor ...$extractors) : Exctractor` extractor.
+From now to read from multiple locations use `from_all(Extractor ...$extractors) : Exctractor` extractor.
 
 Before:
 ```php
@@ -118,7 +139,7 @@ from_parquet(path(__DIR__ . '/data/1.parquet'))->withSchema($schema);
 
 ### 1) Joins
 
-In order to support joining bigger datasets, we had to move from initial NestedLoop join algorithm into Hash Join algorithm.
+To support joining bigger datasets, we had to move from initial NestedLoop join algorithm into Hash Join algorithm.
 
 - the only supported coin expression is `=` (equals) that can be grouped with `AND` and `OR` operators.
 - `joinPrefix` is now always required, and by default is set to 'joined_'
@@ -134,8 +155,8 @@ Above changes were introduced in all 3 types of joins:
 
 ### 2) GroupBy
 
-From now on, DataFrame::groupBy() method will return GroupedDataFrame object, which is nothing more than a GroupBy
-statement Builder. In order to get the results you first need to define the aggregation functions or optionally pivot the data.
+From now on, `DataFrame::groupBy()` method will return `GroupedDataFrame` object, which is nothing more than a GroupBy
+statement Builder. To get the results, you first need to define the aggregation functions or optionally pivot the data.
 
 ## Upgrading from 0.6.x to 0.7.x
 
@@ -188,7 +209,7 @@ DataFrame::parallelize() method is deprecated, and it will be removed, instead u
 
 ### 6) Rows in batch - Extractors
 
-From now, file based Extractors will always throw one Row at time, in order to merge them into bigger groups
+From now, file-based Extractors will always throw one Row at time, in order to merge them into bigger groups
 use `DataFrame::batchSize(int $size)` just after extractor method.
 
 Before:
@@ -218,7 +239,7 @@ Affected extractors:
 - Text
 - XML
 - Avro
-- DoctrineDBAL - rows_in_batch wasn't removed but now results are thrown row by row, instead of whole page.
+- DoctrineDBAL - `rows_in_batch` wasn't removed, but now results are thrown row by row, instead of whole page.
 - GoogleSheet
 
 ### 7) `GoogleSheetExtractor`

src/core/etl/src/Flow/ETL/DSL/functions.php

@@ -5,8 +5,7 @@
 namespace Flow\ETL\DSL;
 
 use Flow\Calculator\Rounding;
-use Flow\ETL\{
-    Analyze,
+use Flow\ETL\{Analyze,
     Attribute\DocumentationDSL,
     Attribute\DocumentationExample,
     Attribute\Module,
@@ -37,9 +36,9 @@
     Schema\SchemaFormatter,
     Transformation,
     Transformer,
+    Transformer\Rename\Style,
     Window,
-    WithEntry
-};
+    WithEntry};
 use Flow\ETL\ErrorHandler\{IgnoreError, SkipRows, ThrowError};
 use Flow\ETL\Exception\{InvalidArgumentException, RuntimeException, SchemaDefinitionNotFoundException};
 use Flow\ETL\Extractor\FilesExtractor;
@@ -349,6 +348,24 @@ function to_branch(ScalarFunction $condition, Loader $loader) : Loader\Branching
     return new Loader\BranchingLoader($condition, $loader);
 }
 
+#[DocumentationDSL(module: Module::CORE, type: DSLType::TRANSFORMER)]
+function rename_style(Style $style) : Transformer\Rename\RenameCaseEntryStrategy
+{
+    return new Transformer\Rename\RenameCaseEntryStrategy($style);
+}
+
+#[DocumentationDSL(module: Module::CORE, type: DSLType::TRANSFORMER)]
+function rename_replace(string $search, string $replace) : Transformer\Rename\RenameReplaceEntryStrategy
+{
+    return new Transformer\Rename\RenameReplaceEntryStrategy($search, $replace);
+}
+
+#[DocumentationDSL(module: Module::CORE, type: DSLType::TRANSFORMER)]
+function rename_transliterate(string $transliterator = 'Any-Latin; Latin-ASCII; Lower()') : Transformer\Rename\RenameTransliterateEntryStrategy
+{
+    return new Transformer\Rename\RenameTransliterateEntryStrategy($transliterator);
+}
+
 #[DocumentationDSL(module: Module::CORE, type: DSLType::ENTRY)]
 function bool_entry(string $name, ?bool $value, ?Schema\Metadata $metadata = null) : Entry\BooleanEntry
 {

src/core/etl/src/Flow/ETL/DataFrame.php

@@ -28,7 +28,8 @@
     VoidPipeline};
 use Flow\ETL\Row\{Formatter\ASCIISchemaFormatter, Reference, References};
 use Flow\ETL\Schema\Definition;
-use Flow\ETL\Transformer\{AutoCastTransformer,
+use Flow\ETL\Transformer\{
+    AutoCastTransformer,
     CallbackRowTransformer,
     CrossJoinRowsTransformer,
     DropDuplicatesTransformer,
@@ -41,14 +42,18 @@
     OrderEntriesTransformer,
     OrderEntries\Comparator,
     OrderEntries\TypeComparator,
-    RenameAllCaseTransformer,
+    RenameEachEntryTransformer,
     RenameEntryTransformer,
-    RenameStrReplaceAllEntriesTransformer,
+    Rename\RenameCaseEntryStrategy,
+    Rename\RenameEntryStrategy,
+    Rename\RenameReplaceEntryStrategy,
+    Rename\Style,
     ScalarFunctionFilterTransformer,
     ScalarFunctionTransformer,
     SelectEntriesTransformer,
     UntilTransformer,
-    WindowFunctionTransformer};
+    WindowFunctionTransformer
+};
 use Flow\Filesystem\Path\Filter;
 
 final class DataFrame
@@ -84,7 +89,8 @@ public function autoCast() : self
      * Merge/Split Rows yielded by Extractor into batches of given size.
      * For example, when Extractor is yielding one row at time, this method will merge them into batches of given size
      * before passing them to the next pipeline element.
-     * Similarly when Extractor is yielding batches of rows, this method will split them into smaller batches of given size.
+     * Similarly when Extractor is yielding batches of rows, this method will split them into smaller batches of given
+     * size.
      *
      * In order to merge all Rows into a single batch use DataFrame::collect() method or set size to -1 or 0.
      *
@@ -210,7 +216,8 @@ public function crossJoin(self $dataFrame, string $prefix = '') : self
 
     /**
      * @param int $limit maximum numbers of rows to display
-     * @param bool|int $truncate false or if set to 0 columns are not truncated, otherwise default truncate to 20 characters
+     * @param bool|int $truncate false or if set to 0 columns are not truncated, otherwise default truncate to 20
+     *                           characters
      * @param Formatter $formatter
      *
      * @trigger
@@ -258,7 +265,8 @@ public function dropDuplicates(string|Reference ...$entries) : self
     }
 
     /**
-     * Drop all partitions from Rows, additionally when $dropPartitionColumns is set to true, partition columns are also removed.
+     * Drop all partitions from Rows, additionally when $dropPartitionColumns is set to true, partition columns are
+     * also removed.
      *
      * @lazy
      */
@@ -625,28 +633,32 @@ public function rename(string $from, string $to) : self
 
     /**
      * @lazy
-     * Iterate over all entry names and replace given search string with replace string.
+     * Iterate over all entry names and replace the given search string with replace string.
+     *
+     * @deprecated use DataFrame::renameEach() with a RenameReplaceStrategy
      */
     public function renameAll(string $search, string $replace) : self
     {
-        $this->pipeline->add(new RenameStrReplaceAllEntriesTransformer($search, $replace));
+        $this->renameEach(new RenameReplaceEntryStrategy($search, $replace));
 
         return $this;
     }
 
     /**
      * @lazy
+     *
+     * @deprecated use DataFrame::renameEach() with a selected Style
      */
     public function renameAllLowerCase() : self
     {
-        $this->pipeline->add(new RenameAllCaseTransformer(lower: true));
+        $this->renameEach(new RenameCaseEntryStrategy(Style::LOWER));
 
         return $this;
     }
 
     /**
      * @lazy
-     * Rename all entries to given style.
+     * Rename all entries to a given style.
      * Please look into \Flow\ETL\Function\StyleConverter\StringStyles class for all available styles.
      */
     public function renameAllStyle(StringStyles|string $style) : self
@@ -658,30 +670,43 @@ public function renameAllStyle(StringStyles|string $style) : self
 
     /**
      * @lazy
+     *
+     * @deprecated use DataFrame::renameEach() with a selected Style
      */
     public function renameAllUpperCase() : self
     {
-        $this->pipeline->add(new RenameAllCaseTransformer(upper: true));
+        $this->renameEach(new RenameCaseEntryStrategy(Style::UPPER));
 
         return $this;
     }
 
     /**
      * @lazy
+     *
+     * @deprecated use DataFrame::renameEach() with a selected Style
      */
     public function renameAllUpperCaseFirst() : self
     {
-        $this->pipeline->add(new RenameAllCaseTransformer(ucfirst: true));
+        $this->renameEach(new RenameCaseEntryStrategy(Style::UCFIRST));
 
         return $this;
     }
 
     /**
      * @lazy
+     *
+     * @deprecated use DataFrame::renameEach() with a selected Style
      */
     public function renameAllUpperCaseWord() : self
     {
-        $this->pipeline->add(new RenameAllCaseTransformer(ucwords: true));
+        $this->renameEach(new RenameCaseEntryStrategy(Style::UCWORDS));
+
+        return $this;
+    }
+
+    public function renameEach(RenameEntryStrategy $strategy) : self
+    {
+        $this->pipeline->add(new RenameEachEntryTransformer($strategy));
 
         return $this;
     }
@@ -825,8 +850,8 @@ public function transform(Transformer|Transformation|Transformations|WithEntry $
     }
 
     /**
-     * The difference between filter and until is that filter will keep filtering rows until extractors finish yielding rows.
-     * Until will send a STOP signal to the Extractor when the condition is not met.
+     * The difference between filter and until is that filter will keep filtering rows until extractors finish yielding
+     * rows. Until will send a STOP signal to the Extractor when the condition is not met.
      *
      * @lazy
      */

src/core/etl/src/Flow/ETL/Pipeline/Optimizer/LimitOptimization.php

@@ -8,7 +8,16 @@
 use Flow\ETL\Function\ScalarFunction\ExpandResults;
 use Flow\ETL\{Loader, Pipeline, Transformer};
 use Flow\ETL\Pipeline\{BatchingPipeline, CollectingPipeline, LinkedPipeline, SynchronousPipeline, VoidPipeline};
-use Flow\ETL\Transformer\{CallbackRowTransformer, DropEntriesTransformer, EntryNameStyleConverterTransformer, LimitTransformer, RenameAllCaseTransformer, RenameEntryTransformer, RenameStrReplaceAllEntriesTransformer, ScalarFunctionTransformer, SelectEntriesTransformer};
+use Flow\ETL\Transformer\{CallbackRowTransformer,
+    DropEntriesTransformer,
+    EntryNameStyleConverterTransformer,
+    LimitTransformer,
+    RenameAllCaseTransformer,
+    RenameEachEntryTransformer,
+    RenameEntryTransformer,
+    RenameStrReplaceAllEntriesTransformer,
+    ScalarFunctionTransformer,
+    SelectEntriesTransformer};
 
 final class LimitOptimization implements Optimization
 {
@@ -27,6 +36,7 @@ final class LimitOptimization implements Optimization
         SelectEntriesTransformer::class,
         DropEntriesTransformer::class,
         RenameAllCaseTransformer::class,
+        RenameEachEntryTransformer::class,
         RenameEntryTransformer::class,
         RenameStrReplaceAllEntriesTransformer::class,
         LimitTransformer::class,