philiprehberger-csv_builder 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a303ee02020135b1ce25af2882b415847487b5ee10f5b3f7fc929586150c750d
-  data.tar.gz: b7cde53364fd15eacca588c5df3ca2056a3abc40d552ba650b7fad1681f804f2
+  metadata.gz: 574dc6604faf705d2e8f54f778e8e27f7595d0aedd3db13b4a54c9adb857bfbf
+  data.tar.gz: 22e3ca9d324548d233a5bd86b5c087590ad78f1a871b9107b3f5ab6fb1cdbe57
 SHA512:
-  metadata.gz: 98272067c382b0d1a89d4400886e4162913efa72fbc6677dc3445599bcc9bdba85177894b5a89fdc9a28bd44c440279afa8a254917b208d766e3aa703e4bdc6e
-  data.tar.gz: ee0c236b83966c409af73445c43bb626330c7227964cba73054ac475b2cb3db7218f95ef4167901e9086f64c1af348f4adbc998abfdbbcc770472937fb80fa9f
+  metadata.gz: 91a8ce738a72a3e08276e50d66510ea0ff1c96b625207160471bf0985f2cc5e4a55cae26a2a978cf9a795eabd0d24f5e578a554255dfd294c7f56bc18963a6ab
+  data.tar.gz: a31eee12211d6453c4b87dc2cee21a7a14a6e0fda9189685d4165370a888b9dd88fac8a0a63716a66bda8553e2bc0dad6f2d98a1c6d806b1fefc8ef23ec79583

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-14
+
+### Added
+- `CsvBuilder.tsv` shorthand for tab-separated output
+- `CsvBuilder.psv` shorthand for pipe-separated output
+- `Builder#validate` registers a validation block; raises `CsvBuilder::ValidationError` on failure
+- `Builder#transform_header` registers a proc applied to all column headers during rendering
+- `Builder#total(column, &block)` shorthand for adding a footer row with computed total
+
+## [0.5.0] - 2026-04-11
+
+### Added
+- UTF-8 BOM support via `bom: true` option for Excel-compatible output
+- Custom output encoding via `encoding:` option
+
+### Fixed
+- Bug report template now requires Ruby version and gem version fields
+- Feature request template now includes "Alternatives considered" field
+
 ## [0.4.0] - 2026-04-10
 
 ### Added
@@ -65,6 +84,8 @@ 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.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
 [0.3.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.3.0
 [0.2.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.2.0

data/README.md

@@ -94,6 +94,82 @@ builder = Philiprehberger::CsvBuilder.build(records, quote_char: "'") do
 end
 ```
 
+### TSV and PSV Output
+
+Use the `tsv` and `psv` shorthands instead of passing `delimiter:` manually:
+
+```ruby
+# Tab-separated
+builder = Philiprehberger::CsvBuilder.tsv(records) do
+  column :name
+  column :email
+end
+
+puts builder.to_csv
+# name	email
+# Alice	alice@example.com
+
+# Pipe-separated
+builder = Philiprehberger::CsvBuilder.psv(records) do
+  column :name
+  column :email
+end
+
+puts builder.to_csv
+# name|email
+# Alice|alice@example.com
+```
+
+Both accept the same options as `build` (e.g. `bom:`, `encoding:`).
+
+### Row Validation
+
+Register one or more validation blocks. Rows are checked before `to_csv`, `to_file`, or `to_io`. If any block returns falsy or raises, a `CsvBuilder::ValidationError` is raised:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name
+  column :email
+  validate { |row| row[:email].include?('@') }
+end
+
+builder.to_csv  # raises ValidationError if any email is missing '@'
+```
+
+### Header Transforms
+
+Apply a transformation to all column headers during rendering:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :first_name
+  column :last_name
+  transform_header { |h| h.upcase }
+end
+
+builder.headers  # => ["FIRST_NAME", "LAST_NAME"]
+```
+
+### Total Rows
+
+Add a footer row with a computed total for a named column:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name
+  column :amount
+  total :amount
+end
+
+# Outputs a footer row: ,60.0
+```
+
+Pass a block for custom aggregation:
+
+```ruby
+total(:amount) { |values| values.max }
+```
+
 ### Column Aliases
 
 ```ruby
@@ -197,6 +273,27 @@ end
 
 `offset` and `limit` are applied after filtering and sorting.
 
+### Excel-Compatible Output (BOM)
+
+Prepend a UTF-8 BOM so Excel opens the CSV with correct encoding:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records, bom: true) do
+  column :name
+  column :email
+end
+
+builder.to_file('export.csv')
+```
+
+### Custom Encoding
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records, encoding: 'ISO-8859-1') do
+  column :name
+end
+```
+
 ### Streaming
 
 ```ruby
@@ -232,10 +329,15 @@ builder.headers  # => ["name", "email"]
 
 | Method | Description |
 |--------|-------------|
-| `CsvBuilder.build(records, delimiter:, quote_char:, &block)` | Build a CSV using the column DSL |
+| `CsvBuilder.build(records, delimiter:, quote_char:, bom:, encoding:, &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 |
 | `Builder#filter(&block)` | Filter records (block returns true to include) |
 | `Builder#sort_by(direction:, &block)` | Sort records by block key (`:asc` or `:desc`) |
+| `Builder#validate(&block)` | Register a row validation block; raises `ValidationError` on failure |
+| `Builder#transform_header(&block)` | Register a proc applied to all column headers |
+| `Builder#total(column, &block)` | Add a footer row with computed total for the named column |
 | `Builder#footer(&block)` | Append a computed footer row (block receives filtered records) |
 | `Builder#limit(n)` | Cap output to N rows |
 | `Builder#offset(n)` | Skip first N filtered/sorted records |

data/lib/philiprehberger/csv_builder/builder.rb

@@ -16,10 +16,13 @@ module Philiprehberger
       # @param records [Array] the source records
       # @param delimiter [String] the column separator (default: ",")
       # @param quote_char [String] the quote character (default: '"')
-      def initialize(records, delimiter: ',', quote_char: '"')
+      # @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')
         @records = records
         @columns = []
         @filters = []
+        @validations = []
         @row_number_header = nil
         @delimiter = delimiter
         @quote_char = quote_char
@@ -28,6 +31,9 @@ module Philiprehberger
         @limit_count = nil
         @offset_count = nil
         @footer_block = nil
+        @header_transform = nil
+        @bom = bom
+        @encoding = encoding
       end
 
       # Sort records before CSV output
@@ -39,7 +45,8 @@ module Philiprehberger
       # @raise [Error] if direction is not :asc or :desc
       def sort_by(direction: :asc, &block)
         raise Error, 'A block is required for sort_by' unless block
-        raise Error, "direction must be :asc or :desc (got #{direction.inspect})" unless %i[asc desc].include?(direction)
+        raise Error, "direction must be :asc or :desc (got #{direction.inspect})" unless %i[asc
+                                                                                            desc].include?(direction)
 
         @sort_by = block
         @sort_direction = direction
@@ -74,6 +81,46 @@ module Philiprehberger
         self
       end
 
+      # Register a validation block for rows
+      #
+      # @yield [row] block that validates the row hash
+      # @yieldparam row [Hash] column-name to value mapping
+      # @return [self]
+      def validate(&block)
+        @validations << block
+        self
+      end
+
+      # Register a proc applied to all column headers during rendering
+      #
+      # @yield [name] block that transforms a header name
+      # @yieldparam name [String] the original header label
+      # @return [self]
+      def transform_header(&block)
+        @header_transform = block
+        self
+      end
+
+      # Shorthand for adding a footer row with a computed total for the named column
+      #
+      # @param column_name [Symbol, String] the column to total
+      # @yield [values] optional block to compute the total (receives array of numeric values)
+      # @return [self]
+      def total(column_name, &block)
+        col_name = column_name.to_sym
+        @footer_block = lambda do |recs|
+          columns.map do |col|
+            if col.name == col_name
+              values = recs.map { |r| col.extract(r).to_f }
+              block ? block.call(values) : values.sum
+            else
+              ''
+            end
+          end
+        end
+        self
+      end
+
       # Define a column
       #
       # @param name [Symbol, String] the column name
@@ -110,6 +157,7 @@ module Philiprehberger
       # @return [Array<String>]
       def headers
         base = @columns.map(&:header)
+        base = base.map { |h| @header_transform.call(h) } if @header_transform
         @row_number_header ? [@row_number_header] + base : base
       end
 
@@ -133,15 +181,19 @@ module Philiprehberger
       # Generate the CSV as a string
       #
       # @return [String]
+      # @raise [ValidationError] if any row fails validation
       def to_csv
         recs = filtered_records
-        CSV.generate(**csv_options) do |csv|
+        validate_rows!(recs) unless @validations.empty?
+        csv_string = CSV.generate(**csv_options) do |csv|
           csv << headers
           recs.each_with_index do |record, index|
             csv << build_row(record, index)
           end
           csv << @footer_block.call(recs) if @footer_block
         end
+        csv_string = csv_string.encode(@encoding) unless @encoding == 'UTF-8'
+        @bom ? "\xEF\xBB\xBF#{csv_string}" : csv_string
       end
 
       # Write the CSV to a file
@@ -149,15 +201,18 @@ module Philiprehberger
       # @param path [String] the output file path
       # @return [void]
       def to_file(path)
-        File.write(path, to_csv)
+        File.binwrite(path, to_csv)
       end
 
       # Stream CSV to any IO object
       #
       # @param io [IO, StringIO] the IO object to write to
       # @return [void]
+      # @raise [ValidationError] if any row fails validation
       def to_io(io)
+        io.write("\xEF\xBB\xBF") if @bom
         recs = filtered_records
+        validate_rows!(recs) unless @validations.empty?
         csv = CSV.new(io, **csv_options)
         csv << headers
         recs.each_with_index do |record, index|
@@ -173,6 +228,27 @@ module Philiprehberger
         { col_sep: @delimiter, quote_char: @quote_char }
       end
 
+      # Validate all rows against registered validation blocks
+      #
+      # @param recs [Array] the filtered records
+      # @return [void]
+      # @raise [ValidationError] if any row fails validation
+      def validate_rows!(recs)
+        recs.each_with_index do |record, index|
+          row_hash = @columns.to_h do |col|
+            [col.name, col.extract(record)]
+          end
+          @validations.each do |v|
+            result = v.call(row_hash)
+            raise ValidationError, "Row #{index + 1} failed validation" unless result
+          rescue ValidationError
+            raise
+          rescue StandardError => e
+            raise ValidationError, "Row #{index + 1} failed validation: #{e.message}"
+          end
+        end
+      end
+
       # Build a single row array for the given record
       #
       # @param record [Object] the source record

data/lib/philiprehberger/csv_builder/version.rb

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

data/lib/philiprehberger/csv_builder.rb

@@ -7,22 +7,49 @@ require_relative 'csv_builder/builder'
 module Philiprehberger
   module CsvBuilder
     class Error < StandardError; end
+    class ValidationError < Error; end
 
     # Build a CSV from records using a declarative DSL
     #
     # @param records [Array] the source records
     # @param delimiter [String] the column separator (default: ",")
     # @param quote_char [String] the quote character (default: '"')
+    # @param bom [Boolean] prepend UTF-8 BOM for Excel compatibility (default: false)
+    # @param encoding [String] output encoding name (default: "UTF-8")
     # @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: '"', &block)
+    def self.build(records, delimiter: ',', quote_char: '"', bom: false, encoding: 'UTF-8', &block)
       raise Error, 'A block is required' unless block
 
-      builder = Builder.new(records, delimiter: delimiter, quote_char: quote_char)
+      builder = Builder.new(
+        records,
+        delimiter: delimiter, quote_char: quote_char,
+        bom: bom, encoding: encoding
+      )
       builder.instance_eval(&block)
       builder
     end
+
+    # Shorthand for tab-separated output
+    #
+    # @param records [Array] the source records
+    # @param options [Hash] additional options passed to .build
+    # @yield [builder] the builder instance for defining columns
+    # @return [Builder] the configured builder
+    def self.tsv(records, **options, &)
+      build(records, **options, delimiter: "\t", &)
+    end
+
+    # Shorthand for pipe-separated output
+    #
+    # @param records [Array] the source records
+    # @param options [Hash] additional options passed to .build
+    # @yield [builder] the builder instance for defining columns
+    # @return [Builder] the configured builder
+    def self.psv(records, **options, &)
+      build(records, **options, delimiter: '|', &)
+    end
   end
 end

metadata

@@ -1,18 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_builder
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-10 00:00:00.000000000 Z
+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, and custom delimiters.
+  computed footer rows, row numbers, streaming output, custom delimiters, TSV/PSV
+  shorthands, row validation, header transforms, and total rows.
 email:
 - me@philiprehberger.com
 executables: []