philiprehberger-csv_kit 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c35825a1d3ef7d421c3f81a39764ec731b1fdee58cb36233f8814d6bf64204a
-  data.tar.gz: 9ef07017bee59e872f3553ab00c2477f4e48b98f7667f1a90fa63280cf9454ed
+  metadata.gz: 2e1adf3b48028bff09be12a45a992c4a0166654770be8552e4bc5a7d49be7555
+  data.tar.gz: 5692fbac3a9152fe49d58b3ecd2a70ada46c3213ed7affd39c89020b4810f352
 SHA512:
-  metadata.gz: 63090fc561da814943591e38cb070ffacce6ea9a85104fbfd6a64850834f8ec0047ed3a6b5d9525aa2d1eb930d1883c07376a89f9e2add7859a362abafb8a407
-  data.tar.gz: 82a690e38566ecec250d8bc74bdbd02581c46dbdf34749cfc017c5dc174321c98bc8634b4e98b5abd0285e447efcf359fb543f1a8da2ee25200145c17c471804
+  metadata.gz: 9d735873d9123ad62afdff85ab07039d7b918438776c21a7e6b4a44b17632b9f537cb43f79aaf01daff7e057972697aba060f365964369a25ae893b61adbc76c
+  data.tar.gz: 7b16477c9f74e8714b5ed02e466c0c3fed53da9edf1c6d893b528a3d874f614c86c28ebcef9f3a9e389fa289472f8fa2150d37a5bb411ffdf1c7f4fecb1e2454

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-29
+
+### Added
+
+- CSV dialect support with predefined presets (`:excel`, `:excel_tab`, `:unix`) and custom dialects
+- Date/time type coercions via `Processor#type` — built-in `:date` and `:datetime` types with optional format strings
+- Streaming writer via `Writer.stream(io, headers:) { |w| w << row }` for incremental CSV output
+- Dialect integration into `process()`, `to_hashes()`, `pluck()`, and `filter()` methods
+
+## [0.2.6] - 2026-03-26
+
+### Changed
+
+- Add Sponsor badge and fix License link format in README
+
+## [0.2.5] - 2026-03-24
+
+### Changed
+- Expand test coverage to 60+ examples covering edge cases and error paths
+
+## [0.2.4] - 2026-03-24
+
+### Fixed
+- Align README one-liner with gemspec summary
+
 ## [0.2.3] - 2026-03-24
 
 ### Fixed

data/README.md

@@ -2,9 +2,14 @@
 
 [![Tests](https://github.com/philiprehberger/rb-csv-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-csv-kit/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-csv_kit.svg)](https://rubygems.org/gems/philiprehberger-csv_kit)
+[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-csv-kit)](https://github.com/philiprehberger/rb-csv-kit/releases)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-csv-kit)](https://github.com/philiprehberger/rb-csv-kit/commits/main)
 [![License](https://img.shields.io/github/license/philiprehberger/rb-csv-kit)](LICENSE)
+[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-csv-kit/bug)](https://github.com/philiprehberger/rb-csv-kit/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-csv-kit/enhancement)](https://github.com/philiprehberger/rb-csv-kit/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
-Streaming CSV processor with type coercion, validation, writing, and error recovery
+Streaming CSV processor with type coercion and validation
 
 ## Requirements
 
@@ -28,26 +33,22 @@ gem install philiprehberger-csv_kit
 
 ```ruby
 require "philiprehberger/csv_kit"
-```
-
-### Quick Load
 
-```ruby
-rows = Philiprehberger::CsvKit.to_hashes('data.csv')
+rows = Philiprehberger::CsvKit.to_hashes("data.csv")
 # => [{name: "Alice", age: "30"}, ...]
 ```
 
 ### Pluck Columns
 
 ```ruby
-names = Philiprehberger::CsvKit.pluck('data.csv', :name, :city)
+names = Philiprehberger::CsvKit.pluck("data.csv", :name, :city)
 # => [{name: "Alice", city: "Berlin"}, ...]
 ```
 
 ### Filter Rows
 
 ```ruby
-csv_string = Philiprehberger::CsvKit.filter('data.csv') do |row|
+csv_string = Philiprehberger::CsvKit.filter("data.csv") do |row|
   row[:age].to_i >= 30
 end
 ```
@@ -55,70 +56,75 @@ end
 ### Streaming Processor
 
 ```ruby
-rows = Philiprehberger::CsvKit.process('data.csv') do |p|
+rows = Philiprehberger::CsvKit.process("data.csv") do |p|
   p.transform(:age) { |v| v.to_i }
   p.validate(:age) { |v| v.to_i.positive? }
-  p.reject { |row| row[:city] == 'Unknown' }
+  p.reject { |row| row[:city] == "Unknown" }
   p.each { |row| puts row[:name] }
 end
 ```
 
+### Date/Time Type Coercions
+
+```ruby
+rows = Philiprehberger::CsvKit.process("data.csv") do |p|
+  p.type(:birthday, :date)
+  p.type(:created_at, :datetime, format: "%Y-%m-%dT%H:%M:%S")
+end
+```
+
+### CSV Dialects
+
+```ruby
+rows = Philiprehberger::CsvKit.to_hashes("data.csv", dialect: :excel)
+rows = Philiprehberger::CsvKit.process("data.csv", dialect: { delimiter: ";", quote: "'" }) do |p|
+  p.transform(:age, &:to_i)
+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|
+File.open("output.csv", "w") do |f|
   writer.write_to([{ name: "Alice", age: 30 }], f)
 end
 ```
 
-### Error Recovery
+### Streaming Writer
 
 ```ruby
-rows = Philiprehberger::CsvKit.process('data.csv') do |p|
-  p.on_error { |row, err| :skip }  # or :abort
-  p.transform(:age) { |v| Integer(v) }
+File.open("output.csv", "w") do |f|
+  Philiprehberger::CsvKit::Writer.stream(f, headers: [:name, :age]) do |w|
+    w << { name: "Alice", age: 30 }
+    w << { name: "Bob", age: 25 }
+  end
 end
 ```
 
-### Max Errors
+### Error Recovery
 
 ```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
+rows = Philiprehberger::CsvKit.process("data.csv") do |p|
+  p.on_error { |row, err| :skip }
+  p.transform(:age) { |v| Integer(v) }
 end
 ```
 
 ### Column Aliasing
 
 ```ruby
-rows = Philiprehberger::CsvKit.process('data.csv') do |p|
+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
-delimiter = Philiprehberger::CsvKit::Detector.detect('data.tsv')
+delimiter = Philiprehberger::CsvKit::Detector.detect("data.tsv")
 # => "\t"
 ```
 
@@ -126,12 +132,13 @@ delimiter = Philiprehberger::CsvKit::Detector.detect('data.tsv')
 
 | Method / Class | Description |
 |----------------|-------------|
-| `CsvKit.to_hashes(path)` | Load CSV into array of symbolized hashes |
-| `CsvKit.pluck(path, *keys)` | Extract specific columns |
-| `CsvKit.filter(path, &block)` | Filter rows, return CSV string |
-| `CsvKit.process(path_or_io, &block)` | Streaming DSL with transforms and validations |
+| `CsvKit.to_hashes(path, dialect:)` | Load CSV into array of symbolized hashes |
+| `CsvKit.pluck(path, *keys, dialect:)` | Extract specific columns |
+| `CsvKit.filter(path, dialect:, &block)` | Filter rows, return CSV string |
+| `CsvKit.process(path_or_io, dialect:, &block)` | Streaming DSL with transforms and validations |
 | `Processor#headers(*names)` | Override header names |
 | `Processor#transform(key, &block)` | Register column transform |
+| `Processor#type(key, type, **opts)` | Register built-in type coercion (:integer, :float, :string, :date, :datetime) |
 | `Processor#validate(key, &block)` | Register column validation (skip invalid) |
 | `Processor#reject(&block)` | Reject rows matching predicate |
 | `Processor#each(&block)` | Callback for each processed row |
@@ -143,6 +150,8 @@ delimiter = Philiprehberger::CsvKit::Detector.detect('data.tsv')
 | `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 |
+| `Writer.stream(io, headers:, dialect:)` | Stream CSV rows incrementally to an IO |
+| `Dialect.new(name_or_hash)` | Create a dialect from preset or custom hash |
 | `Detector.detect(path_or_io)` | Auto-detect CSV delimiter |
 | `Row#[](key)` | Access value by symbol key |
 | `Row#to_h` | Convert row to plain hash |
@@ -155,6 +164,13 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+
+[![LinkedIn](https://img.shields.io/badge/Philip%20Rehberger-LinkedIn-0A66C2?logo=linkedin)](https://www.linkedin.com/in/philiprehberger)
+[![More packages](https://img.shields.io/badge/more-open%20source%20packages-blue)](https://philiprehberger.com/open-source-packages)
+
 ## License
 
-MIT
+[MIT](LICENSE)

data/lib/philiprehberger/csv_kit/dialect.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CsvKit
+    # Predefined and custom CSV dialects for controlling parsing and writing behavior.
+    class Dialect
+      PRESETS = {
+        excel: { col_sep: ',', row_sep: "\r\n", strip: true },
+        excel_tab: { col_sep: "\t" },
+        unix: { col_sep: ',', row_sep: "\n" }
+      }.freeze
+
+      OPTION_MAP = {
+        delimiter: :col_sep,
+        quote: :quote_char,
+        line_ending: :row_sep
+      }.freeze
+
+      attr_reader :options
+
+      # Build a Dialect from a preset name or a custom options hash.
+      #
+      # @param name_or_hash [Symbol, Hash] preset name (:excel, :excel_tab, :unix) or custom hash
+      # @return [Dialect]
+      def initialize(name_or_hash)
+        @options = resolve(name_or_hash)
+      end
+
+      # Merge dialect options into a base CSV options hash.
+      #
+      # @param base [Hash] base CSV options
+      # @return [Hash] merged options
+      def merge_into(base)
+        base.merge(@options)
+      end
+
+      private
+
+      def resolve(name_or_hash)
+        case name_or_hash
+        when Symbol
+          preset = PRESETS[name_or_hash]
+          raise ArgumentError, "Unknown dialect: #{name_or_hash}" unless preset
+
+          preset.dup
+        when Hash
+          normalize_hash(name_or_hash)
+        else
+          raise ArgumentError, "Dialect must be a Symbol or Hash, got #{name_or_hash.class}"
+        end
+      end
+
+      def normalize_hash(hash)
+        hash.each_with_object({}) do |(key, value), opts|
+          csv_key = OPTION_MAP.fetch(key, key)
+          opts[csv_key] = value
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/csv_kit/processor.rb

@@ -7,8 +7,29 @@ module Philiprehberger
       include ErrorHandler
       include Callbacks
 
-      def initialize(path_or_io)
+      TYPE_COERCIONS = {
+        integer: ->(v, _opts) { Integer(v) },
+        float: ->(v, _opts) { Float(v) },
+        string: ->(v, _opts) { v.to_s },
+        date: lambda { |v, opts|
+          if opts[:format]
+            Date.strptime(v, opts[:format])
+          else
+            Date.parse(v)
+          end
+        },
+        datetime: lambda { |v, opts|
+          if opts[:format]
+            Time.strptime(v, opts[:format])
+          else
+            Time.parse(v)
+          end
+        }
+      }.freeze
+
+      def initialize(path_or_io, dialect: nil)
         @path_or_io = path_or_io
+        @dialect = dialect ? Dialect.new(dialect) : nil
         @transforms = {}
         @validations = {}
         @reject_block = nil
@@ -28,6 +49,18 @@ module Philiprehberger
         @transforms[key] = block
       end
 
+      # Register a built-in type coercion for a column.
+      #
+      # @param key [Symbol] column name
+      # @param type_name [Symbol] one of :integer, :float, :string, :date, :datetime
+      # @param opts [Hash] additional options (e.g. format: '%Y-%m-%d')
+      def type(key, type_name, **opts)
+        coercion = TYPE_COERCIONS[type_name]
+        raise ArgumentError, "Unknown type: #{type_name}" unless coercion
+
+        @transforms[key] = ->(v) { coercion.call(v, opts) }
+      end
+
       # Register a validation for a specific column.
       def validate(key, &block)
         @validations[key] = block
@@ -79,10 +112,13 @@ module Philiprehberger
       end
 
       def open_csv(&block)
+        csv_opts = { headers: true }
+        csv_opts = @dialect.merge_into(csv_opts) if @dialect
+
         if @path_or_io.is_a?(String)
-          CSV.open(@path_or_io, headers: true, &block)
+          CSV.open(@path_or_io, **csv_opts, &block)
         else
-          block.call(CSV.new(@path_or_io, headers: true))
+          block.call(CSV.new(@path_or_io, **csv_opts))
         end
       end
 

data/lib/philiprehberger/csv_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CsvKit
-    VERSION = '0.2.3'
+    VERSION = '0.3.0'
   end
 end

data/lib/philiprehberger/csv_kit/writer.rb

@@ -9,6 +9,19 @@ module Philiprehberger
         @headers = headers.map(&:to_sym)
       end
 
+      # Stream CSV rows incrementally to an IO object without buffering.
+      #
+      # @param io [IO] writable IO object
+      # @param headers [Array<Symbol, String>] column headers
+      # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
+      # @yield [StreamWriter] writer that accepts rows via <<
+      # @return [IO] the IO object
+      def self.stream(io, headers:, dialect: nil, &block)
+        writer = StreamWriter.new(io, headers: headers, dialect: dialect)
+        block.call(writer)
+        io
+      end
+
       # Write rows to a CSV string.
       #
       # @param rows [Array<Hash, Array>] data rows
@@ -41,6 +54,37 @@ module Philiprehberger
 
         row
       end
+
+      # Incremental writer that streams rows to an IO object one at a time.
+      class StreamWriter
+        # @param io [IO] writable IO object
+        # @param headers [Array<Symbol, String>] column headers
+        # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
+        def initialize(io, headers:, dialect: nil)
+          @headers = headers.map(&:to_sym)
+          csv_opts = {}
+          csv_opts = Dialect.new(dialect).merge_into(csv_opts) if dialect
+          @csv = CSV.new(io, **csv_opts)
+          @csv << @headers
+        end
+
+        # Append a single row to the CSV output.
+        #
+        # @param row [Hash, Array] a single data row
+        # @return [self]
+        def <<(row)
+          @csv << row_values(row)
+          self
+        end
+
+        private
+
+        def row_values(row)
+          return @headers.map { |h| row[h] } if row.is_a?(Hash)
+
+          row
+        end
+      end
     end
   end
 end

data/lib/philiprehberger/csv_kit.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require 'csv'
+require 'date'
+require 'time'
 require_relative 'csv_kit/version'
+require_relative 'csv_kit/dialect'
 require_relative 'csv_kit/detector'
 require_relative 'csv_kit/row'
 require_relative 'csv_kit/error_handler'
@@ -16,10 +19,11 @@ module Philiprehberger
     # Streaming DSL — yields a Processor for configuration, then executes.
     #
     # @param path_or_io [String, IO] file path or IO object
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
     # @yield [Processor] processor to configure transforms and validations
     # @return [Array<Row>] collected rows
-    def self.process(path_or_io, &block)
-      processor = Processor.new(path_or_io)
+    def self.process(path_or_io, dialect: nil, &block)
+      processor = Processor.new(path_or_io, dialect: dialect)
       block.call(processor)
       processor.run
     end
@@ -27,9 +31,12 @@ module Philiprehberger
     # Load an entire CSV into an array of symbolized hashes.
     #
     # @param path [String] file path
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
     # @return [Array<Hash{Symbol => String}>]
-    def self.to_hashes(path)
-      CSV.foreach(path, headers: true).map do |row|
+    def self.to_hashes(path, dialect: nil)
+      csv_opts = { headers: true }
+      csv_opts = Dialect.new(dialect).merge_into(csv_opts) if dialect
+      CSV.foreach(path, **csv_opts).map do |row|
         row.to_h.transform_keys(&:to_sym)
       end
     end
@@ -38,18 +45,20 @@ module Philiprehberger
     #
     # @param path [String] file path
     # @param keys [Array<Symbol>] column names to extract
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
     # @return [Array<Hash{Symbol => String}>]
-    def self.pluck(path, *keys)
-      to_hashes(path).map { |h| h.slice(*keys) }
+    def self.pluck(path, *keys, dialect: nil)
+      to_hashes(path, dialect: dialect).map { |h| h.slice(*keys) }
     end
 
     # Filter rows and return matching rows as a CSV string.
     #
     # @param path [String] file path
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
     # @yield [Hash{Symbol => String}] each row as a symbolized hash
     # @return [String] CSV string with headers
-    def self.filter(path, &)
-      rows = to_hashes(path).select(&)
+    def self.filter(path, dialect: nil, &)
+      rows = to_hashes(path, dialect: dialect).select(&)
       return '' if rows.empty?
 
       headers = rows.first.keys

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-03-30 00:00:00.000000000 Z
 dependencies: []
 description: Streaming CSV processor with row-by-row transforms, validations, column
   plucking, filtering, writing, error recovery, and automatic delimiter detection.
@@ -24,6 +24,7 @@ files:
 - lib/philiprehberger/csv_kit.rb
 - lib/philiprehberger/csv_kit/callbacks.rb
 - lib/philiprehberger/csv_kit/detector.rb
+- lib/philiprehberger/csv_kit/dialect.rb
 - lib/philiprehberger/csv_kit/error_handler.rb
 - lib/philiprehberger/csv_kit/processor.rb
 - lib/philiprehberger/csv_kit/row.rb