philiprehberger-csv_kit 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47d82c7f00d1c8263a9fe0c36db577a9b23d731ec0d0e29a0b937390e3b9ad5e
-  data.tar.gz: d6a7e13c1e99839d7b1b346a09cddf5997acc23f23b8a38804cb0ff8ff9a123b
+  metadata.gz: 63dcb3883c3732b41c45224ad90e4ae26ea4af2efced584db70089e0b5802be9
+  data.tar.gz: 672c6414f9620772b8cbb664b6cfdbc7a37f76b38d2456cdf72e83d947bca659
 SHA512:
-  metadata.gz: 05153db33d2ff42f6ba455456decfff96f0f2ecb453f9243e19c30fab41bde4dd48813a23795bb074a01d3a8d642758e881ee538c6044d0689664fc6288b4016
-  data.tar.gz: 8603bacec3217f03caea385b232c6801040ea084180ba348346c5a6f49dd35bba92b25a0eb7c60b29945f35044c46b007a91a8381853eb747f8429cea1e1fa0e
+  metadata.gz: ca664b0389948c7a12793a238f3b94189ef8bc7bbed4aeecdbb431cc986dfad0386f1e621922ba655bdfe85605ba9f2abcdd11550758604d5dad052e6b42d26e
+  data.tar.gz: 973ccc2da16d11249c0dc4c1f1826a42815503b6800bfa9def603f8884dc041e23c37c81ddd9f1fcd719df58438c445a815add96e4de214513f4b6e01f0679c3

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-09
+
+### Added
+- `CsvKit.each_hash(path, dialect:)` for streaming row-by-row iteration with constant memory; returns Enumerator if no block given
+- `Row` now includes `Enumerable` with `keys`, `values`, `size`, `each`, and `merge` methods
+
+## [0.4.0] - 2026-04-09
+
+### Added
+- `CsvKit.headers(path, dialect:)` to inspect header row without loading data
+- `CsvKit.count(path, dialect:)` to count data rows without loading into memory
+- `Processor#skip(n)` to skip the first N data rows
+- `Processor#limit(n)` to stop after processing N rows
+
 ## [0.3.1] - 2026-03-31
 
 ### Changed
@@ -76,3 +90,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Auto-detect delimiter
 - Type coercion and row validation
 - Quick load and filtering convenience methods
+
+[0.5.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.5.0
+[0.4.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.4.0
+[0.3.1]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.3.1
+[0.3.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.3.0
+[0.2.6]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.6
+[0.2.5]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.5
+[0.2.4]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.4
+[0.2.3]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.3
+[0.2.2]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.2
+[0.2.1]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.1
+[0.2.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.0
+[0.1.2]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.1.2
+[0.1.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.1.0

data/README.md

@@ -40,6 +40,35 @@ names = Philiprehberger::CsvKit.pluck("data.csv", :name, :city)
 # => [{name: "Alice", city: "Berlin"}, ...]
 ```
 
+### Inspect Headers
+
+```ruby
+Philiprehberger::CsvKit.headers("data.csv")
+# => [:name, :age, :city]
+```
+
+### Count Rows
+
+```ruby
+Philiprehberger::CsvKit.count("data.csv")
+# => 1000
+```
+
+### Streaming Row-by-Row
+
+Iterate rows with constant memory. Returns an `Enumerator` if no block is given:
+
+```ruby
+Philiprehberger::CsvKit.each_hash("large.csv") do |row|
+  puts row[:name]
+end
+
+# Or compose with Enumerator methods:
+adults = Philiprehberger::CsvKit.each_hash("data.csv")
+  .select { |r| r[:age].to_i >= 18 }
+  .first(10)
+```
+
 ### Filter Rows
 
 ```ruby
@@ -108,6 +137,15 @@ rows = Philiprehberger::CsvKit.process("data.csv") do |p|
 end
 ```
 
+### Skip and Limit
+
+```ruby
+rows = Philiprehberger::CsvKit.process("data.csv") do |p|
+  p.skip(10)   # skip first 10 rows
+  p.limit(50)  # stop after 50 rows
+end
+```
+
 ### Column Aliasing
 
 ```ruby
@@ -130,11 +168,16 @@ delimiter = Philiprehberger::CsvKit::Detector.detect("data.tsv")
 | `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.headers(path, dialect:)` | Return header row as array of symbols |
+| `CsvKit.count(path, dialect:)` | Count data rows without loading into memory |
+| `CsvKit.each_hash(path, dialect:, &block)` | Stream rows as symbolized hashes; returns Enumerator if no block |
 | `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#skip(n)` | Skip the first N data rows |
+| `Processor#limit(n)` | Stop after processing N rows |
 | `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`) |
@@ -149,6 +192,11 @@ delimiter = Philiprehberger::CsvKit::Detector.detect("data.tsv")
 | `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#keys` | Column names as array of symbols |
+| `Row#values` | Column values as array |
+| `Row#size` | Number of columns |
+| `Row#each { \|k, v\| }` | Iterate key-value pairs (Enumerable) |
+| `Row#merge(other)` | Return new Row with merged data |
 | `Row#to_h` | Convert row to plain hash |
 
 ## Development

data/lib/philiprehberger/csv_kit/processor.rb

@@ -35,6 +35,8 @@ module Philiprehberger
         @reject_block = nil
         @each_block = nil
         @header_names = nil
+        @skip_count = nil
+        @limit_count = nil
         init_error_handler
         init_callbacks
       end
@@ -66,6 +68,22 @@ module Philiprehberger
         @validations[key] = block
       end
 
+      # Skip the first N data rows during processing.
+      #
+      # @param n [Integer] number of rows to skip
+      # @return [void]
+      def skip(n)
+        @skip_count = n
+      end
+
+      # Stop after processing N rows.
+      #
+      # @param n [Integer] maximum rows to collect
+      # @return [void]
+      def limit(n)
+        @limit_count = n
+      end
+
       # Register a reject predicate.
       def reject(&block)
         @reject_block = block
@@ -87,7 +105,14 @@ module Philiprehberger
       private
 
       def process_rows(csv)
+        skipped = 0
         csv.each_with_object([]) do |csv_row, results|
+          if @skip_count && skipped < @skip_count
+            skipped += 1
+            next
+          end
+          break results if @limit_count && results.length >= @limit_count
+
           process_single_row(csv_row, results)
         end
       end

data/lib/philiprehberger/csv_kit/row.rb

@@ -4,11 +4,50 @@ module Philiprehberger
   module CsvKit
     # Wraps a CSV row as a hash with symbolized keys.
     class Row
+      include Enumerable
+
       # @param data [Hash{Symbol => String}]
       def initialize(data)
         @data = data
       end
 
+      # Iterate over key-value pairs.
+      #
+      # @yield [Symbol, Object] key and value
+      def each(&)
+        @data.each(&)
+      end
+
+      # Return column names.
+      #
+      # @return [Array<Symbol>]
+      def keys
+        @data.keys
+      end
+
+      # Return column values.
+      #
+      # @return [Array<Object>]
+      def values
+        @data.values
+      end
+
+      # Return the number of columns.
+      #
+      # @return [Integer]
+      def size
+        @data.size
+      end
+
+      # Merge another hash or Row into this row, returning a new Row.
+      #
+      # @param other [Hash, Row] data to merge
+      # @return [Row]
+      def merge(other)
+        other_data = other.is_a?(Row) ? other.to_h : other
+        Row.new(@data.merge(other_data))
+      end
+
       # Access a value by symbolized key.
       #
       # @param key [Symbol] column name

data/lib/philiprehberger/csv_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CsvKit
-    VERSION = '0.3.1'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/csv_kit.rb

@@ -51,6 +51,55 @@ module Philiprehberger
       to_hashes(path, dialect: dialect).map { |h| h.slice(*keys) }
     end
 
+    # Return the header row as an array of symbols.
+    #
+    # @param path [String] file path
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
+    # @return [Array<Symbol>]
+    def self.headers(path, dialect: nil)
+      csv_opts = {}
+      csv_opts = Dialect.new(dialect).merge_into(csv_opts) if dialect
+      CSV.open(path, **csv_opts) do |csv|
+        row = csv.shift
+        return [] unless row
+
+        row.map(&:to_sym)
+      end
+    end
+
+    # Count data rows without loading them all into memory.
+    #
+    # @param path [String] file path
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
+    # @return [Integer]
+    def self.count(path, dialect: nil)
+      csv_opts = { headers: true }
+      csv_opts = Dialect.new(dialect).merge_into(csv_opts) if dialect
+      n = 0
+      CSV.foreach(path, **csv_opts) { |_| n += 1 }
+      n
+    end
+
+    # Stream rows one at a time as symbolized hashes with constant memory.
+    # Returns an Enumerator if no block is given.
+    #
+    # @param path [String] file path
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
+    # @yield [Hash{Symbol => String}] each row
+    # @return [Enumerator, nil]
+    def self.each_hash(path, dialect: nil, &block)
+      csv_opts = { headers: true }
+      csv_opts = Dialect.new(dialect).merge_into(csv_opts) if dialect
+
+      enum = Enumerator.new do |yielder|
+        CSV.foreach(path, **csv_opts) do |row|
+          yielder.yield(row.to_h.transform_keys(&:to_sym))
+        end
+      end
+
+      block ? enum.each(&block) : enum
+    end
+
     # Filter rows and return matching rows as a CSV string.
     #
     # @param path [String] file path

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_kit
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-10 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.
+  plucking, streaming each_hash iteration, filtering, writing, error recovery, and
+  automatic delimiter detection.
 email:
 - me@philiprehberger.com
 executables: []
@@ -30,11 +31,11 @@ files:
 - 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
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-csv_kit
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-csv-kit
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-csv_kit
   source_code_uri: https://github.com/philiprehberger/rb-csv-kit
   changelog_uri: https://github.com/philiprehberger/rb-csv-kit/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-csv-kit/issues