Add a new DataFrame::renameEach()

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\StyleConverter\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\StyleConverter\RenameCaseEntryStrategy
+{
+    return new Transformer\StyleConverter\RenameCaseEntryStrategy($style);
+}
+
+#[DocumentationDSL(module: Module::CORE, type: DSLType::TRANSFORMER)]
+function rename_replace(string $search, string $replace) : Transformer\StyleConverter\RenameReplaceEntryStrategy
+{
+    return new Transformer\StyleConverter\RenameReplaceEntryStrategy($search, $replace);
+}
+
+#[DocumentationDSL(module: Module::CORE, type: DSLType::TRANSFORMER)]
+function rename_transliterate(string $transliterator = 'Any-Latin; Latin-ASCII; Lower()') : Transformer\StyleConverter\RenameTransliterateEntryStrategy
+{
+    return new Transformer\StyleConverter\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,
@@ -43,13 +44,16 @@
     OrderEntries\TypeComparator,
     RenameEachTransformer,
     RenameEntryTransformer,
-    RenameStrReplaceAllEntriesTransformer,
     ScalarFunctionFilterTransformer,
     ScalarFunctionTransformer,
     SelectEntriesTransformer,
-    StyleConverter\RenameStrategy,
+    StyleConverter\RenameCaseEntryStrategy,
+    StyleConverter\RenameEntryStrategy,
+    StyleConverter\RenameReplaceEntryStrategy,
+    StyleConverter\Style,
     UntilTransformer,
-    WindowFunctionTransformer};
+    WindowFunctionTransformer
+};
 use Flow\Filesystem\Path\Filter;
 
 final class DataFrame
@@ -629,30 +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 RenameStrategy
+     * @deprecated use DataFrame::renameEach() with a selected Style
      */
     public function renameAllLowerCase() : self
     {
-        $this->renameEach(RenameStrategy::LOWER);
+        $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
@@ -665,40 +671,40 @@ public function renameAllStyle(StringStyles|string $style) : self
     /**
      * @lazy
      *
-     * @deprecated use DataFrame::renameEach() with a selected RenameStrategy
+     * @deprecated use DataFrame::renameEach() with a selected Style
      */
     public function renameAllUpperCase() : self
     {
-        $this->renameEach(RenameStrategy::UPPER);
+        $this->renameEach(new RenameCaseEntryStrategy(Style::UPPER));
 
         return $this;
     }
 
     /**
      * @lazy
      *
-     * @deprecated use DataFrame::renameEach() with a selected RenameStrategy
+     * @deprecated use DataFrame::renameEach() with a selected Style
      */
     public function renameAllUpperCaseFirst() : self
     {
-        $this->renameEach(RenameStrategy::UCFIRST);
+        $this->renameEach(new RenameCaseEntryStrategy(Style::UCFIRST));
 
         return $this;
     }
 
     /**
      * @lazy
      *
-     * @deprecated use DataFrame::renameEach() with a selected RenameStrategy
+     * @deprecated use DataFrame::renameEach() with a selected Style
      */
     public function renameAllUpperCaseWord() : self
     {
-        $this->renameEach(RenameStrategy::UCWORDS);
+        $this->renameEach(new RenameCaseEntryStrategy(Style::UCWORDS));
 
         return $this;
     }
 
-    public function renameEach(RenameStrategy $strategy) : self
+    public function renameEach(RenameEntryStrategy $strategy) : self
     {
         $this->pipeline->add(new RenameEachTransformer($strategy));
 

src/core/etl/src/Flow/ETL/Transformer/RenameAllCaseTransformer.php

@@ -4,14 +4,19 @@
 
 namespace Flow\ETL\Transformer;
 
-use Flow\ETL\{FlowContext, Rows, Transformer, Transformer\StyleConverter\RenameStrategy};
+use Flow\ETL\{FlowContext,
+    Row,
+    Rows,
+    Transformer,
+    Transformer\StyleConverter\RenameCaseEntryStrategy,
+    Transformer\StyleConverter\Style};
 
 /**
- * @deprecated use RenameEachTransformer with a selected RenameStrategy
+ * @deprecated Use `DataFrame::renameEach()` and `RenameCaseTransformer`
  */
 final class RenameAllCaseTransformer implements Transformer
 {
-    private RenameEachTransformer $transformer;
+    private RenameCaseEntryStrategy $transformer;
 
     public function __construct(
         bool $upper = false,
@@ -20,24 +25,30 @@ public function __construct(
         bool $ucwords = false,
     ) {
         if ($upper) {
-            $this->transformer = new RenameEachTransformer(RenameStrategy::UPPER);
+            $this->transformer = new RenameCaseEntryStrategy(Style::UPPER);
         }
 
         if ($lower) {
-            $this->transformer = new RenameEachTransformer(RenameStrategy::LOWER);
+            $this->transformer = new RenameCaseEntryStrategy(Style::LOWER);
         }
 
         if ($ucfirst) {
-            $this->transformer = new RenameEachTransformer(RenameStrategy::UCFIRST);
+            $this->transformer = new RenameCaseEntryStrategy(Style::UCFIRST);
         }
 
         if ($ucwords) {
-            $this->transformer = new RenameEachTransformer(RenameStrategy::UCWORDS);
+            $this->transformer = new RenameCaseEntryStrategy(Style::UCWORDS);
         }
     }
 
     public function transform(Rows $rows, FlowContext $context) : Rows
     {
-        return $this->transformer->transform($rows, $context);
+        return $rows->map(function (Row $row) use ($context) : Row {
+            foreach ($row->entries()->all() as $entry) {
+                $row = $this->transformer->rename($row, $entry, $context);
+            }
+
+            return $row;
+        });
     }
 }