Changed prefix preserve to include in new methods

Author: nyamsprod

CHANGELOG.md

@@ -7,14 +7,14 @@ All Notable changes to `Csv` will be documented in this file
 ### Added
 
 - Adding support for controlling empty record presence in `Reader::getRecords` return value.
-    - `Reader::preserveEmptyRecord`
-    - `Reader::skipEmptyRecord`
-    - `Reader::isEmptyRecordSkipped`
+    - `Reader::includeEmptyRecords`
+    - `Reader::skipEmptyRecords`
+    - `Reader::isEmptyRecordsIncluded`
 
 - Adding support for controlling Input BOM usage in the library:
     - `AbstractCsv::skipInputBOM`
-    - `AbstractCsv::preserveInputBOM`
-    - `AbstractCsv::isInputBOMSkipped`
+    - `AbstractCsv::includeInputBOM`
+    - `AbstractCsv::isInputBOMIncluded`
 
 ### Deprecated
 

docs/9.0/connections/bom.md

@@ -82,13 +82,13 @@ $bom = $csv->getOutputBOM(); //returns "\xEF\xBB\xBF"
 
 ~~~php
 AbstractCsv::skipInputBOM(): self;
-AbstractCsv::preserveInputBOM(): self;
-AbstractCsv::isInputBOMSkipped(): bool;
+AbstractCsv::includeInputBOM(): self;
+AbstractCsv::isInputBOMIncluded(): bool;
 ~~~
 
 - `skipInputBOM`: enables skipping the input BOM from your CSV document.
-- `preserveInputBOM`: preserves the input BOM from your CSV document while accessing its content.
-- `isInputBOMSkipped`: tells whether skipping the input BOM will be done.
+- `includeInputBOM`: preserves the input BOM from your CSV document while accessing its content.
+- `isInputBOMIncluded`: tells whether skipping or including the input BOM will be done.
 
 <p class="message-notice">By default and to avoid BC Break, the Input BOM is skipped.</p>
 
@@ -99,7 +99,7 @@ If your document does not contains any BOM sequence you can speed up the CSV ite
 $raw_csv = Reader::BOM_UTF8."john,doe,[email protected]\njane,doe,[email protected]\n";
 $csv = Reader::createFromString($raw_csv);
 $csv->setOutputBOM(Reader::BOM_UTF16_BE);
-$csv->preserveInputBOM();
+$csv->includeInputBOM();
 ob_start();
 $csv->output();
 $document = ob_get_clean();

docs/9.0/reader/index.md

@@ -212,14 +212,14 @@ foreach ($records as $offset => $record) {
 By default the CSV document normalization removes empty records. But you can control the presence of such records using the following methods:
 
 ~~~php
-Reader::skipEmptyRecord(): self;
-Reader::preserveEmptyRecord(): self;
-Reader::isEmptyRecordSkipped(): bool;
+Reader::skipEmptyRecords(): self;
+Reader::includeEmptyRecords(): self;
+Reader::isEmptyRecordsIncluded(): bool;
 ~~~
 
-- Calling `Reader::preserveEmptyRecord` will ensure empty records are left in the `Iterator` returned by `Reader::getRecords`,
-conversely `Reader::skipEmptyRecord` will ensure empty records are skipped.  
-- At any given time you can ask you Reader instance if empty records will be stripped using the `Reader::isEmptyRecordSkipped` method.
+- Calling `Reader::includeEmptyRecords` will ensure empty records are left in the `Iterator` returned by `Reader::getRecords`,
+conversely `Reader::skipEmptyRecords` will ensure empty records are skipped.  
+- At any given time you can ask you Reader instance if empty records will be stripped or included using the `Reader::isEmptyRecordsIncluded` method.
 - If no header offset is specified, the empty record will be represented by a empty `array`, conversely,
 for consistency, an empty record will be represented by an array filled with `null` values as expected from header presence normalization.
 
@@ -237,15 +237,15 @@ $source = <<<EOF
 EOF;
 
 $reader = Reader::createFromString($source);
-$reader->isEmptyRecordSkipped(); // return true;
+$reader->isEmptyRecordsIncluded(); // return true;
 iterator_to_array($reader, true);
 // [
 //     0 => ['parent name', 'child name', 'title'],
 //     3 => ['parentA', 'childA', 'titleA'],
 // ];
 
-$reader->preserveEmptyRecord();
-$reader->isEmptyRecordSkipped(); // return false;
+$reader->includeEmptyRecords();
+$reader->isEmptyRecordsIncluded(); // return false;
 iterator_to_array($reader, true);
 // [
 //     0 => ['parent name', 'child name', 'title'],
@@ -262,8 +262,8 @@ iterator_to_array($reader, true);
 //     3 => ['parent name' => 'parentA', 'child name' => 'childA', 'title' => 'titleA'],
 // ]; 
 
-$reader->skipEmptyRecord();
-$reader->isEmptyRecordSkipped(); // return true;
+$reader->skipEmptyRecords();
+$reader->isEmptyRecordsIncluded(); // return false;
 $res = iterator_to_array($reader, true);
 // [
 //     3 => ['parent name' => 'parentA', 'child name' => 'childA', 'title' => 'titleA'],
@@ -300,11 +300,11 @@ If empty record are to be preserved, the number of records will be affected.
 use League\Csv\Reader;
 
 $reader = Reader::createFromPath('/path/to/my/file-with-two-empty-records.csv', 'r');
-$reader->isEmptyRecordSkipped(); //returns true
+$reader->isEmptyRecordsIncluded(); //returns false
 count($records); // returns 2
 
-$reader->preserveEmptyRecords();
-$reader->isEmptyRecordSkipped(); //returns false
+$reader->includeEmptyRecordss();
+$reader->isEmptyRecordsIncluded(); //returns true
 count($records); // returns 4
 ~~~
 

src/AbstractCsv.php

@@ -89,11 +89,11 @@ abstract class AbstractCsv implements ByteSequence
     protected $document;
 
     /**
-     * Tells whether the Input BOM must be stripped.
+     * Tells whether the Input BOM must be included or skipped.
      *
      * @var bool
      */
-    protected $is_input_bom_skipped = true;
+    protected $is_input_bom_included = false;
 
     /**
      * New instance.
@@ -257,9 +257,9 @@ public function hasStreamFilter(string $filtername): bool
     /**
      * Tells whether the BOM can be stripped if presents.
      */
-    public function isInputBOMSkipped(): bool
+    public function isInputBOMIncluded(): bool
     {
-        return $this->is_input_bom_skipped;
+        return $this->is_input_bom_included;
     }
 
     /**
@@ -327,7 +327,7 @@ public function output(string $filename = null): int
         }
 
         $this->document->rewind();
-        if ($this->is_input_bom_skipped) {
+        if (!$this->is_input_bom_included) {
             $this->document->fseek(strlen($this->getInputBOM()));
         }
 
@@ -445,7 +445,7 @@ public function setEscape(string $escape): self
      */
     public function skipInputBOM(): self
     {
-        $this->is_input_bom_skipped = true;
+        $this->is_input_bom_included = false;
 
         return $this;
     }
@@ -455,9 +455,9 @@ public function skipInputBOM(): self
      *
      * @return static
      */
-    public function preserveInputBOM(): self
+    public function includeInputBOM(): self
     {
-        $this->is_input_bom_skipped = false;
+        $this->is_input_bom_included = true;
 
         return $this;
     }

src/Reader.php

@@ -79,7 +79,7 @@ class Reader extends AbstractCsv implements Countable, IteratorAggregate, JsonSe
     /**
      * @var bool
      */
-    protected $is_empty_records_skipped = true;
+    protected $is_empty_records_included = false;
 
     /**
      * {@inheritdoc}
@@ -270,11 +270,11 @@ public function getRecords(array $header = []): Iterator
     {
         $header = $this->computeHeader($header);
         $normalized = function ($record): bool {
-            return is_array($record) && (!$this->is_empty_records_skipped || $record != [null]);
+            return is_array($record) && ($this->is_empty_records_included || $record != [null]);
         };
 
         $bom = '';
-        if ($this->is_input_bom_skipped) {
+        if (!$this->is_input_bom_included) {
             $bom = $this->getInputBOM();
         }
 
@@ -286,7 +286,7 @@ public function getRecords(array $header = []): Iterator
             });
         }
 
-        if (!$this->is_empty_records_skipped) {
+        if ($this->is_empty_records_included) {
             $normalized_empty_records = static function (array $record): array {
                 if ([null] === $record) {
                     return [];
@@ -402,10 +402,10 @@ public function setHeaderOffset($offset): self
     /**
      * Enable skipping empty records.
      */
-    public function skipEmptyRecord(): self
+    public function skipEmptyRecords(): self
     {
-        if (!$this->is_empty_records_skipped) {
-            $this->is_empty_records_skipped = true;
+        if ($this->is_empty_records_included) {
+            $this->is_empty_records_included = false;
             $this->nb_records = -1;
         }
 
@@ -415,10 +415,10 @@ public function skipEmptyRecord(): self
     /**
      * Disable skipping empty records.
      */
-    public function preserveEmptyRecord(): self
+    public function includeEmptyRecords(): self
     {
-        if ($this->is_empty_records_skipped) {
-            $this->is_empty_records_skipped = false;
+        if (!$this->is_empty_records_included) {
+            $this->is_empty_records_included = true;
             $this->nb_records = -1;
         }
 
@@ -428,8 +428,8 @@ public function preserveEmptyRecord(): self
     /**
      * Tells whether empty records are skipped by the instance.
      */
-    public function isEmptyRecordSkipped(): bool
+    public function isEmptyRecordsIncluded(): bool
     {
-        return $this->is_empty_records_skipped;
+        return $this->is_empty_records_included;
     }
 }

tests/CsvTest.php

@@ -461,18 +461,18 @@ public function testGetPathnameWithTempFile()
     }
 
     /**
-     * @covers ::isInputBOMSkipped
-     * @covers ::preserveInputBOM
+     * @covers ::isInputBOMIncluded
+     * @covers ::includeInputBOM
      * @covers ::skipInputBOM
      */
     public function testBOMStripping()
     {
         $reader = Reader::createFromString();
-        self::assertTrue($reader->isInputBOMSkipped());
-        $reader->preserveInputBOM();
-        self::assertFalse($reader->isInputBOMSkipped());
+        self::assertFalse($reader->isInputBOMIncluded());
+        $reader->includeInputBOM();
+        self::assertTrue($reader->isInputBOMIncluded());
         $reader->skipInputBOM();
-        self::assertTrue($reader->isInputBOMSkipped());
+        self::assertFalse($reader->isInputBOMIncluded());
     }
 
     /**
@@ -490,7 +490,7 @@ public function testOutputDoesNotStripBOM()
         self::assertNotContains(Reader::BOM_UTF8, $result);
         self::assertContains(Reader::BOM_UTF16_BE, $result);
 
-        $csv->preserveInputBOM();
+        $csv->includeInputBOM();
         ob_start();
         $csv->output();
         $result = ob_get_clean();

tests/ReaderTest.php

@@ -334,7 +334,7 @@ public function testDisablingBOMStripping()
         $fp = fopen('php://temp', 'r+');
         fputcsv($fp, $expected_record);
         $csv = Reader::createFromStream($fp);
-        $csv->preserveInputBOM();
+        $csv->includeInputBOM();
         self::assertSame(Reader::BOM_UTF16_LE, $csv->getInputBOM());
         foreach ($csv as $offset => $record) {
             self::assertSame($expected_record, $record);
@@ -476,9 +476,9 @@ public function testCreateFromPath()
 
     /**
      * @dataProvider sourceProvider
-     * @covers ::preserveEmptyRecord
-     * @covers ::skipEmptyRecord
-     * @covers ::isEmptyRecordSkipped
+     * @covers ::includeEmptyRecords
+     * @covers ::skipEmptyRecords
+     * @covers ::isEmptyRecordsIncluded
      * @covers ::getRecords
      */
     public function testSkippingEmptyRecords(
@@ -488,28 +488,28 @@ public function testSkippingEmptyRecords(
         array $expected_with_skipping_with_header,
         array $expected_with_preserving_with_header
     ) {
-        self::assertTrue($reader->isEmptyRecordSkipped());
+        self::assertFalse($reader->isEmptyRecordsIncluded());
         self::assertSame(count($expected_with_skipping), count($reader));
         foreach ($reader as $offset => $record) {
             self::assertSame($expected_with_skipping[$offset], $record);
         }
 
-        $reader->preserveEmptyRecord();
-        self::assertFalse($reader->isEmptyRecordSkipped());
+        $reader->includeEmptyRecords();
+        self::assertTrue($reader->isEmptyRecordsIncluded());
         self::assertSame(count($expected_with_preserving), count($reader));
         foreach ($reader as $offset => $record) {
             self::assertSame($expected_with_preserving[$offset], $record);
         }
 
         $reader->setHeaderOffset(0);
-        self::assertFalse($reader->isEmptyRecordSkipped());
+        self::assertTrue($reader->isEmptyRecordsIncluded());
         self::assertSame(count($expected_with_preserving_with_header), count($reader));
         foreach ($reader as $offset => $record) {
             self::assertSame($expected_with_preserving_with_header[$offset], $record);
         }
 
-        $reader->skipEmptyRecord();
-        self::assertTrue($reader->isEmptyRecordSkipped());
+        $reader->skipEmptyRecords();
+        self::assertFalse($reader->isEmptyRecordsIncluded());
         self::assertSame(count($expected_with_skipping_with_header), count($reader));
         foreach ($reader as $offset => $record) {
             self::assertSame($expected_with_skipping_with_header[$offset], $record);