philiprehberger-csv_kit 0.1.2 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec0358461e5ad62f3a288a5e040be44f7b68b1e6fe42ad067f7a5eea5a26d304
-  data.tar.gz: 39e0e6cdd8fda4b74200a5ba9f02019ee845b3b2a95bf251019a6e97cd5c73f6
+  metadata.gz: 5102ddea76ed2da14ae72a63b471103facb61636ba548e7d0f00fa985b53cbf1
+  data.tar.gz: e193e57fac4958f2ef09faca2f5b3811c2561932bc83c785f8dd044bf390267d
 SHA512:
-  metadata.gz: c3b78d43a8678bad749b381387091f783a533a7dbaebef06f4cbab09a9b01009b3e172eb1be2daa0519d8bdddfb80a668804645def75a109989e0f581a29dc7c
-  data.tar.gz: 62ae27c26356c622e149e4cb42195c59e54a8bd97774d2cb21289c0f177b3135dc24fee0ed67f0075cd98f0596e3228e356674476d2bf678d0b554a9a77e7f75
+  metadata.gz: aaeeece43096c75e90321a44dde352f1822f5d9685ebacb89240554d6c782076c1bb467b43b8899c274dcadd6a221873c8cdf126144e589ad1af256bacfa73ff
+  data.tar.gz: 7781416688fa5abde89f73acf7891209511ea590ed10147565887db513fc114d81b116606b8f3bd2e5579699c617722d82d95c5bbd245a5fe75dd3113d266e51

data/CHANGELOG.md

@@ -1,15 +1,32 @@
 # Changelog
 
-## 0.1.2
+## 0.2.2
 
-- Add License badge to README
-- Add bug_tracker_uri to gemspec
+- Revert gemspec to single-quoted strings per RuboCop default configuration
+
+## 0.2.1
+
+- Fix RuboCop Style/StringLiterals violations in gemspec
 
 All notable changes to this gem will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-03-17
+
+### Added
+- CSV writing via `Writer` class — generate CSV from arrays/hashes, write to string or IO
+- Configurable per-row error handling with `on_error` — return `:skip` or `:abort`
+- Max error tracking with `max_errors(n)` — stop processing after N errors
+- Column aliasing with `rename(:from, :to)` — rename columns during processing
+- Row callbacks with `after_each` — hook after each row is fully transformed
+
+## [0.1.2]
+
+- Add License badge to README
+- Add bug_tracker_uri to gemspec
+
 ## [Unreleased]
 
 ## [0.1.0] - 2026-03-15

data/README.md

@@ -4,7 +4,7 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-csv_kit.svg)](https://rubygems.org/gems/philiprehberger-csv_kit)
 [![License](https://img.shields.io/github/license/philiprehberger/rb-csv-kit)](LICENSE)
 
-Streaming CSV processor with type coercion and validation.
+Streaming CSV processor with type coercion, validation, writing, and error recovery.
 
 ## Requirements
 
@@ -69,6 +69,58 @@ rows = Philiprehberger::CsvKit.process('data.csv') do |p|
 end
 ```
 
+### Writing CSV
+
+```ruby
+writer = Philiprehberger::CsvKit::Writer.new(headers: [:name, :age])
+csv_string = writer.write([{ name: "Alice", age: 30 }, { name: "Bob", age: 25 }])
+
+# Write to a file
+File.open('output.csv', 'w') do |f|
+  writer.write_to([{ name: "Alice", age: 30 }], f)
+end
+```
+
+### Error Recovery
+
+```ruby
+rows = Philiprehberger::CsvKit.process('data.csv') do |p|
+  p.on_error { |row, err| :skip }  # or :abort
+  p.transform(:age) { |v| Integer(v) }
+end
+```
+
+### Max Errors
+
+```ruby
+processor = Philiprehberger::CsvKit::Processor.new('data.csv')
+processor.max_errors(10)
+processor.on_error { |row, err| :skip }
+processor.transform(:age) { |v| Integer(v) }
+
+begin
+  processor.run
+rescue Philiprehberger::CsvKit::Error
+  puts processor.errors.length  # collected errors
+end
+```
+
+### Column Aliasing
+
+```ruby
+rows = Philiprehberger::CsvKit.process('data.csv') do |p|
+  p.rename(:raw_col, :clean_col)
+end
+```
+
+### Row Callbacks
+
+```ruby
+rows = Philiprehberger::CsvKit.process('data.csv') do |p|
+  p.after_each { |row| puts row.to_h }
+end
+```
+
 ### Delimiter Detection
 
 ```ruby
@@ -89,6 +141,14 @@ delimiter = Philiprehberger::CsvKit::Detector.detect('data.tsv')
 | `Processor#validate(key, &block)` | Register column validation (skip invalid) |
 | `Processor#reject(&block)` | Reject rows matching predicate |
 | `Processor#each(&block)` | Callback for each processed row |
+| `Processor#on_error(&block)` | Per-row error handler (return `:skip` or `:abort`) |
+| `Processor#max_errors(n)` | Stop after N errors |
+| `Processor#errors` | Collected errors from last run |
+| `Processor#rename(from, to)` | Rename column during processing |
+| `Processor#after_each(&block)` | Callback after each row is fully processed |
+| `Writer.new(headers:)` | Create a CSV writer with given headers |
+| `Writer#write(rows)` | Generate CSV string from rows |
+| `Writer#write_to(rows, io)` | Write CSV to an IO object |
 | `Detector.detect(path_or_io)` | Auto-detect CSV delimiter |
 | `Row#[](key)` | Access value by symbol key |
 | `Row#to_h` | Convert row to plain hash |

data/lib/philiprehberger/csv_kit/callbacks.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CsvKit
+    # Mixin for column aliasing and row callbacks.
+    module Callbacks
+      # Register a callback to run after each row is processed.
+      #
+      # @yield [Row] the processed row
+      def after_each(&block)
+        @after_each_block = block
+      end
+
+      # Rename a column during processing.
+      #
+      # @param from [Symbol] original column name
+      # @param to [Symbol] new column name
+      def rename(from, to)
+        @renames[from.to_sym] = to.to_sym
+      end
+
+      private
+
+      def init_callbacks
+        @after_each_block = nil
+        @renames = {}
+      end
+
+      def apply_renames!(row)
+        @renames.each do |from, to|
+          next unless row.key?(from)
+
+          row[to] = row[from]
+          row.delete(from)
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/csv_kit/error_handler.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CsvKit
+    # Mixin for per-row error handling and max-error tracking.
+    module ErrorHandler
+      # Configure a per-row error handler.
+      #
+      # @yield [Hash, StandardError] the row data and the error
+      # @yieldreturn [:skip, :abort] action to take
+      def on_error(&block)
+        @error_handler = block
+      end
+
+      # Set a maximum number of errors before aborting.
+      #
+      # @param limit [Integer] max errors allowed
+      # @return [self]
+      def max_errors(limit)
+        @max_errors = limit
+        self
+      end
+
+      # Returns collected errors from the last run.
+      #
+      # @return [Array<Hash>] error details
+      def errors
+        @errors ||= []
+      end
+
+      private
+
+      def init_error_handler
+        @error_handler = nil
+        @max_errors = nil
+        @errors = []
+      end
+
+      def handle_row_error(row, err)
+        @errors << { row: row.to_h, error: err }
+        check_max_errors!
+        resolve_error_action(row, err)
+      end
+
+      def check_max_errors!
+        return unless @max_errors && @errors.length >= @max_errors
+
+        raise Error, "Max errors (#{@max_errors}) reached"
+      end
+
+      def resolve_error_action(row, err)
+        return :skip unless @error_handler
+
+        @error_handler.call(row, err)
+      end
+    end
+  end
+end

data/lib/philiprehberger/csv_kit/processor.rb

@@ -4,6 +4,9 @@ module Philiprehberger
   module CsvKit
     # Streaming CSV processor with a DSL for transforms, validations, and filtering.
     class Processor
+      include ErrorHandler
+      include Callbacks
+
       def initialize(path_or_io)
         @path_or_io = path_or_io
         @transforms = {}
@@ -11,41 +14,31 @@ module Philiprehberger
         @reject_block = nil
         @each_block = nil
         @header_names = nil
+        init_error_handler
+        init_callbacks
       end
 
       # Override header names used for symbolized keys.
-      #
-      # @param names [Array<Symbol>] header names
       def headers(*names)
         @header_names = names.map(&:to_sym)
       end
 
       # Register a transform for a specific column.
-      #
-      # @param key [Symbol] column name
-      # @yield [String] raw cell value
       def transform(key, &block)
         @transforms[key] = block
       end
 
-      # Register a validation for a specific column. Rows failing validation are skipped.
-      #
-      # @param key [Symbol] column name
-      # @yield [String] cell value
+      # Register a validation for a specific column.
       def validate(key, &block)
         @validations[key] = block
       end
 
-      # Register a reject predicate. Rows matching are excluded.
-      #
-      # @yield [Row] the row
+      # Register a reject predicate.
       def reject(&block)
         @reject_block = block
       end
 
       # Register a callback for each processed row.
-      #
-      # @yield [Row] the row
       def each(&block)
         @each_block = block
       end
@@ -54,6 +47,7 @@ module Philiprehberger
       #
       # @return [Array<Row>] collected rows
       def run
+        @collected_errors = []
         open_csv { |csv| process_rows(csv) }
       end
 
@@ -61,30 +55,41 @@ module Philiprehberger
 
       def process_rows(csv)
         csv.each_with_object([]) do |csv_row, results|
-          row = build_row(csv_row)
-          next unless valid?(row)
-          next if rejected?(row)
-
-          apply_transforms!(row)
-          @each_block&.call(row)
-          results << row
+          process_single_row(csv_row, results)
         end
       end
 
+      def process_single_row(csv_row, results)
+        row = build_row(csv_row)
+        return unless valid?(row)
+        return if rejected?(row)
+
+        apply_transforms!(row)
+        apply_renames!(row)
+        @each_block&.call(row)
+        @after_each_block&.call(row)
+        results << row
+      rescue StandardError => e
+        handle_error_for_row(row, e, results)
+      end
+
+      def handle_error_for_row(row, err, _results)
+        action = handle_row_error(row, err)
+        raise Error, "Aborted: #{err.message}" if action == :abort
+      end
+
       def open_csv(&block)
         if @path_or_io.is_a?(String)
           CSV.open(@path_or_io, headers: true, &block)
         else
-          csv = CSV.new(@path_or_io, headers: true)
-          block.call(csv)
+          block.call(CSV.new(@path_or_io, headers: true))
         end
       end
 
       def build_row(csv_row)
         data = csv_row.to_h
         if @header_names
-          values = data.values
-          mapped = @header_names.zip(values).to_h
+          mapped = @header_names.zip(data.values).to_h
           Row.new(mapped)
         else
           Row.new(data.transform_keys(&:to_sym))

data/lib/philiprehberger/csv_kit/row.rb

@@ -25,6 +25,22 @@ module Philiprehberger
         @data[key] = value
       end
 
+      # Check if a key exists.
+      #
+      # @param key [Symbol] column name
+      # @return [Boolean]
+      def key?(key)
+        @data.key?(key)
+      end
+
+      # Delete a key from the row.
+      #
+      # @param key [Symbol] column name
+      # @return [Object, nil] removed value
+      def delete(key)
+        @data.delete(key)
+      end
+
       # Return the row as a plain hash.
       #
       # @return [Hash{Symbol => Object}]

data/lib/philiprehberger/csv_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CsvKit
-    VERSION = '0.1.2'
+    VERSION = '0.2.2'
   end
 end

data/lib/philiprehberger/csv_kit/writer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CsvKit
+    # Generates CSV output from arrays of hashes or arrays.
+    class Writer
+      # @param headers [Array<Symbol, String>] column headers
+      def initialize(headers:)
+        @headers = headers.map(&:to_sym)
+      end
+
+      # Write rows to a CSV string.
+      #
+      # @param rows [Array<Hash, Array>] data rows
+      # @return [String] CSV string
+      def write(rows)
+        generate_csv(rows, StringIO.new).string
+      end
+
+      # Write rows to an IO object.
+      #
+      # @param rows [Array<Hash, Array>] data rows
+      # @param io [IO] writable IO
+      # @return [IO] the IO object
+      def write_to(rows, io)
+        generate_csv(rows, io)
+        io
+      end
+
+      private
+
+      def generate_csv(rows, io)
+        csv = CSV.new(io)
+        csv << @headers
+        rows.each { |row| csv << row_values(row) }
+        csv
+      end
+
+      def row_values(row)
+        return @headers.map { |h| row[h] } if row.is_a?(Hash)
+
+        row
+      end
+    end
+  end
+end

data/lib/philiprehberger/csv_kit.rb

@@ -4,7 +4,10 @@ require 'csv'
 require_relative 'csv_kit/version'
 require_relative 'csv_kit/detector'
 require_relative 'csv_kit/row'
+require_relative 'csv_kit/error_handler'
+require_relative 'csv_kit/callbacks'
 require_relative 'csv_kit/processor'
+require_relative 'csv_kit/writer'
 
 module Philiprehberger
   module CsvKit

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.2
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-16 00:00:00.000000000 Z
+date: 2026-03-19 00:00:00.000000000 Z
 dependencies: []
 description: Streaming CSV processor with row-by-row transforms, validations, column
-  plucking, filtering, and automatic delimiter detection.
+  plucking, filtering, writing, error recovery, and automatic delimiter detection.
 email:
 - me@philiprehberger.com
 executables: []
@@ -22,10 +22,13 @@ files:
 - LICENSE
 - README.md
 - lib/philiprehberger/csv_kit.rb
+- lib/philiprehberger/csv_kit/callbacks.rb
 - lib/philiprehberger/csv_kit/detector.rb
+- lib/philiprehberger/csv_kit/error_handler.rb
 - lib/philiprehberger/csv_kit/processor.rb
 - lib/philiprehberger/csv_kit/row.rb
 - lib/philiprehberger/csv_kit/version.rb
+- lib/philiprehberger/csv_kit/writer.rb
 homepage: https://github.com/philiprehberger/rb-csv-kit
 licenses:
 - MIT