philiprehberger-csv_builder 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 574dc6604faf705d2e8f54f778e8e27f7595d0aedd3db13b4a54c9adb857bfbf
-  data.tar.gz: 22e3ca9d324548d233a5bd86b5c087590ad78f1a871b9107b3f5ab6fb1cdbe57
+  metadata.gz: fbaf1a09bda94dd3fff6302860abacf5ad60eb1376520f145f984da9ec8fb7b1
+  data.tar.gz: 625b0af93c07cc624d51a2aed8239c5bebd465981bea6cdc7b9ef91433a2c645
 SHA512:
-  metadata.gz: 91a8ce738a72a3e08276e50d66510ea0ff1c96b625207160471bf0985f2cc5e4a55cae26a2a978cf9a795eabd0d24f5e578a554255dfd294c7f56bc18963a6ab
-  data.tar.gz: a31eee12211d6453c4b87dc2cee21a7a14a6e0fda9189685d4165370a888b9dd88fac8a0a63716a66bda8553e2bc0dad6f2d98a1c6d806b1fefc8ef23ec79583
+  metadata.gz: 562365a1e93a6d9386a31630011021186ecf45029f6764e05fa594ccd872dcbe0a932477897c469dade5a95a2ca02d0d9c7f2a656b48210ff5d4c71c6d7ff9cf
+  data.tar.gz: 7805ee034ea1c75bf1e8ccbea4854d1bbaab80ddbc0def7b7ba30b0be301280bfec22d8b9450e34da4e43fb9943b627c0a11a1397cd9fe5c1b04ded3a441f843

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-04-15
+
+### Added
+- `Builder#write_to(path, mode:)` for writing CSV with an explicit file mode
+- `Builder#append_to(path)` shorthand that appends data rows (no header, no BOM) to an existing file
+- `row_sep:` option on `CsvBuilder.build` for custom line separators (e.g. `"\r\n"`)
+- `empty_value:` option on `CsvBuilder.build` to replace `nil` / empty values with a placeholder
+- `Builder#to_s` alias for `to_csv` (enables string interpolation)
+- `Builder#to_a` returns the CSV as `[headers, *rows, footer?]`
+
+### Fixed
+- `Column#extract` no longer silently drops `false` and `0` values when looking up symbol keys in a hash record (hash lookup now uses `Hash#key?` instead of `||`)
+
 ## [0.6.0] - 2026-04-14
 
 ### Added
@@ -84,6 +97,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for hash records with symbol and string keys
 - Proper CSV escaping for values with commas and quotes
 
+[0.7.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.7.0
 [0.6.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.6.0
 [0.5.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.5.0
 [0.4.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.4.0

data/README.md

@@ -314,6 +314,62 @@ io = StringIO.new
 builder.to_io(io)
 ```
 
+### Writing and Appending
+
+`write_to` accepts an explicit open mode so you can overwrite or append:
+
+```ruby
+# Overwrite (default behaviour, same as to_file)
+builder.write_to('output.csv')
+
+# Append data rows only (no header, no BOM) to an existing file
+builder.append_to('output.csv')
+
+# Or explicitly
+builder.write_to('output.csv', mode: 'ab')
+```
+
+`append_to` is handy for combining multiple builders into one file while keeping a single header row.
+
+### Custom Line Separator
+
+Use `row_sep:` to switch between Unix (`\n`, default), Windows (`\r\n`) or any other line ending:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records, row_sep: "\r\n") do
+  column :name
+  column :email
+end
+```
+
+### Custom Empty Value
+
+Replace `nil` and empty string values with a placeholder:
+
+```ruby
+records = [{ name: 'Alice', email: nil }]
+
+builder = Philiprehberger::CsvBuilder.build(records, empty_value: 'N/A') do
+  column :name
+  column :email
+end
+
+puts builder.to_csv
+# name,email
+# Alice,N/A
+```
+
+### String and Array Conversion
+
+```ruby
+# to_s is an alias for to_csv (handy for string interpolation)
+puts "CSV:\n#{builder}"
+
+# to_a returns [headers, *rows, footer?] for programmatic use
+builder.to_a
+# => [["name", "email"], ["Alice", "alice@example.com"], ["Bob", "bob@example.com"]]
+```
+
 ### Headers
 
 ```ruby
@@ -329,7 +385,7 @@ builder.headers  # => ["name", "email"]
 
 | Method | Description |
 |--------|-------------|
-| `CsvBuilder.build(records, delimiter:, quote_char:, bom:, encoding:, &block)` | Build a CSV using the column DSL |
+| `CsvBuilder.build(records, delimiter:, quote_char:, row_sep:, bom:, encoding:, empty_value:, &block)` | Build a CSV using the column DSL |
 | `CsvBuilder.tsv(records, **options, &block)` | Shorthand for tab-separated output |
 | `CsvBuilder.psv(records, **options, &block)` | Shorthand for pipe-separated output |
 | `Builder#column(name, header:, &block)` | Define a column with optional alias and transform |
@@ -343,7 +399,11 @@ builder.headers  # => ["name", "email"]
 | `Builder#offset(n)` | Skip first N filtered/sorted records |
 | `Builder#row_number(header:)` | Add auto-incrementing row number column |
 | `Builder#to_csv` | Generate CSV as a string |
-| `Builder#to_file(path)` | Write CSV to a file |
+| `Builder#to_s` | Alias for `to_csv` (enables string interpolation) |
+| `Builder#to_a` | Return CSV as an array of row arrays (headers + data + footer) |
+| `Builder#to_file(path)` | Write CSV to a file (overwrites) |
+| `Builder#write_to(path, mode:)` | Write CSV with an explicit file mode (`'wb'` default, `'ab'` to append body only) |
+| `Builder#append_to(path)` | Append data rows (no header, no BOM) to an existing CSV file |
 | `Builder#to_io(io)` | Stream CSV to any IO object |
 | `Builder#headers` | Return column header names |
 

data/lib/philiprehberger/csv_builder/builder.rb

@@ -16,9 +16,12 @@ module Philiprehberger
       # @param records [Array] the source records
       # @param delimiter [String] the column separator (default: ",")
       # @param quote_char [String] the quote character (default: '"')
+      # @param row_sep [String] the line separator (default: "\n")
       # @param bom [Boolean] prepend UTF-8 BOM (default: false)
       # @param encoding [String] output encoding name (default: "UTF-8")
-      def initialize(records, delimiter: ',', quote_char: '"', bom: false, encoding: 'UTF-8')
+      # @param empty_value [String] placeholder for nil/empty values (default: "")
+      def initialize(records, delimiter: ',', quote_char: '"', row_sep: "\n",
+                     bom: false, encoding: 'UTF-8', empty_value: '')
         @records = records
         @columns = []
         @filters = []
@@ -26,6 +29,7 @@ module Philiprehberger
         @row_number_header = nil
         @delimiter = delimiter
         @quote_char = quote_char
+        @row_sep = row_sep
         @sort_by = nil
         @sort_direction = :asc
         @limit_count = nil
@@ -34,6 +38,7 @@ module Philiprehberger
         @header_transform = nil
         @bom = bom
         @encoding = encoding
+        @empty_value = empty_value
       end
 
       # Sort records before CSV output
@@ -111,7 +116,7 @@ module Philiprehberger
         @footer_block = lambda do |recs|
           columns.map do |col|
             if col.name == col_name
-              values = recs.map { |r| col.extract(r).to_f }
+              values = recs.map { |r| col.extract(r, empty_value: @empty_value).to_f }
               block ? block.call(values) : values.sum
             else
               ''
@@ -196,6 +201,13 @@ module Philiprehberger
         @bom ? "\xEF\xBB\xBF#{csv_string}" : csv_string
       end
 
+      # Alias for {#to_csv} so instances behave nicely with string interpolation.
+      #
+      # @return [String]
+      def to_s
+        to_csv
+      end
+
       # Write the CSV to a file
       #
       # @param path [String] the output file path
@@ -204,6 +216,32 @@ module Philiprehberger
         File.binwrite(path, to_csv)
       end
 
+      # Write the CSV to a file with an explicit mode. Useful for appending
+      # to existing files or combining multiple builders into one file.
+      #
+      # When appending (`mode: 'ab'` / `'a'`), the header row and BOM from
+      # subsequent writes are suppressed so the file keeps a single header.
+      #
+      # @param path [String] the output file path
+      # @param mode [String] file open mode (default: "wb")
+      # @return [void]
+      def write_to(path, mode: 'wb')
+        appending = mode.start_with?('a')
+        if appending
+          File.open(path, mode) { |f| write_body_rows(f) }
+        else
+          to_file(path)
+        end
+      end
+
+      # Append data rows (no header, no BOM) to an existing CSV file.
+      #
+      # @param path [String] the output file path
+      # @return [void]
+      def append_to(path)
+        write_to(path, mode: 'ab')
+      end
+
       # Stream CSV to any IO object
       #
       # @param io [IO, StringIO] the IO object to write to
@@ -221,11 +259,38 @@ module Philiprehberger
         csv << @footer_block.call(recs) if @footer_block
       end
 
+      # Return the CSV as an array of row arrays (headers + data + footer).
+      #
+      # @return [Array<Array>]
+      # @raise [ValidationError] if any row fails validation
+      def to_a
+        recs = filtered_records
+        validate_rows!(recs) unless @validations.empty?
+        rows = [headers]
+        recs.each_with_index { |record, index| rows << build_row(record, index) }
+        rows << @footer_block.call(recs) if @footer_block
+        rows
+      end
+
       private
 
       # @return [Hash] CSV library options
       def csv_options
-        { col_sep: @delimiter, quote_char: @quote_char }
+        { col_sep: @delimiter, quote_char: @quote_char, row_sep: @row_sep }
+      end
+
+      # Write only the data rows (and footer) to the given IO. Used by
+      # {#write_to} / {#append_to} so subsequent appends don't duplicate
+      # the header row.
+      #
+      # @param io [IO] the IO object to write to
+      # @return [void]
+      def write_body_rows(io)
+        recs = filtered_records
+        validate_rows!(recs) unless @validations.empty?
+        csv = CSV.new(io, **csv_options)
+        recs.each_with_index { |record, index| csv << build_row(record, index) }
+        csv << @footer_block.call(recs) if @footer_block
       end
 
       # Validate all rows against registered validation blocks
@@ -236,7 +301,7 @@ module Philiprehberger
       def validate_rows!(recs)
         recs.each_with_index do |record, index|
           row_hash = @columns.to_h do |col|
-            [col.name, col.extract(record)]
+            [col.name, col.extract(record, empty_value: @empty_value)]
           end
           @validations.each do |v|
             result = v.call(row_hash)
@@ -255,7 +320,7 @@ module Philiprehberger
       # @param index [Integer] zero-based row index
       # @return [Array]
       def build_row(record, index)
-        row = @columns.map { |col| col.extract(record) }
+        row = @columns.map { |col| col.extract(record, empty_value: @empty_value) }
         @row_number_header ? [index + 1] + row : row
       end
     end

data/lib/philiprehberger/csv_builder/column.rb

@@ -22,17 +22,25 @@ module Philiprehberger
       # Extract the value for this column from a record
       #
       # @param record [Hash, Object] the source record
+      # @param empty_value [String] placeholder for nil / missing values
       # @return [String] the extracted and converted value
-      def extract(record)
+      def extract(record, empty_value: '')
         value = if @transform
                   @transform.call(record)
                 elsif record.is_a?(Hash)
-                  record[@name] || record[@name.to_s]
+                  if record.key?(@name)
+                    record[@name]
+                  else
+                    record[@name.to_s]
+                  end
                 elsif record.respond_to?(@name)
                   record.send(@name)
                 end
 
-        value.to_s
+        return empty_value if value.nil?
+
+        str = value.to_s
+        str.empty? ? empty_value : str
       end
 
       # Return the header label for this column

data/lib/philiprehberger/csv_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CsvBuilder
-    VERSION = '0.6.0'
+    VERSION = '0.7.0'
   end
 end

data/lib/philiprehberger/csv_builder.rb

@@ -14,19 +14,22 @@ module Philiprehberger
     # @param records [Array] the source records
     # @param delimiter [String] the column separator (default: ",")
     # @param quote_char [String] the quote character (default: '"')
+    # @param row_sep [String] the line separator (default: "\n")
     # @param bom [Boolean] prepend UTF-8 BOM for Excel compatibility (default: false)
     # @param encoding [String] output encoding name (default: "UTF-8")
+    # @param empty_value [String] string used to represent nil/empty values (default: "")
     # @yield [builder] the builder instance for defining columns
     # @yieldparam builder [Builder]
     # @return [Builder] the configured builder
     # @raise [Error] if no block is given
-    def self.build(records, delimiter: ',', quote_char: '"', bom: false, encoding: 'UTF-8', &block)
+    def self.build(records, delimiter: ',', quote_char: '"', row_sep: "\n",
+                   bom: false, encoding: 'UTF-8', empty_value: '', &block)
       raise Error, 'A block is required' unless block
 
       builder = Builder.new(
         records,
-        delimiter: delimiter, quote_char: quote_char,
-        bom: bom, encoding: encoding
+        delimiter: delimiter, quote_char: quote_char, row_sep: row_sep,
+        bom: bom, encoding: encoding, empty_value: empty_value
       )
       builder.instance_eval(&block)
       builder

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_builder
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Philip Rehberger
@@ -12,8 +12,9 @@ date: 2026-04-15 00:00:00.000000000 Z
 dependencies: []
 description: Build CSV files from record collections using a declarative DSL with
   column definitions, custom transforms, filtering, sorting, pagination via limit/offset,
-  computed footer rows, row numbers, streaming output, custom delimiters, TSV/PSV
-  shorthands, row validation, header transforms, and total rows.
+  computed footer rows, row numbers, streaming output, custom delimiters and line
+  separators, TSV/PSV shorthands, row validation, header transforms, total rows, append-to-file
+  support, and custom empty-value placeholders.
 email:
 - me@philiprehberger.com
 executables: []