philiprehberger-csv_kit 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47d82c7f00d1c8263a9fe0c36db577a9b23d731ec0d0e29a0b937390e3b9ad5e
-  data.tar.gz: d6a7e13c1e99839d7b1b346a09cddf5997acc23f23b8a38804cb0ff8ff9a123b
+  metadata.gz: a31a3bf217dace4e2ec6ba7214191c13a4c6123112f660b59faa3bf5819c1ea9
+  data.tar.gz: e1f0a82cd1f02cae5b80c9cd78426b7fec741facd8504f15fa02922c8dd4c489
 SHA512:
-  metadata.gz: 05153db33d2ff42f6ba455456decfff96f0f2ecb453f9243e19c30fab41bde4dd48813a23795bb074a01d3a8d642758e881ee538c6044d0689664fc6288b4016
-  data.tar.gz: 8603bacec3217f03caea385b232c6801040ea084180ba348346c5a6f49dd35bba92b25a0eb7c60b29945f35044c46b007a91a8381853eb747f8429cea1e1fa0e
+  metadata.gz: cbe2e1d0ef8ae1294e0fa4d4b51ddf4b614afb3cc2b2b943af7d51969f87f181faf60961da29b2661096865f67ddde39245a617adb6c6f25f130a85cf625ad7b
+  data.tar.gz: e519bc86bf1a6c6d35ff992e32dd41f6ab7ca89fbcaf2a9eac24e3dac3a9848cbe9b0ceac337ef9fb9cb1a2b2684aa2d5ac4a58d8e61eed642a63accdb14fd67

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

data/README.md

@@ -40,6 +40,20 @@ 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
+```
+
 ### Filter Rows
 
 ```ruby
@@ -108,6 +122,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 +153,15 @@ 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.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`) |

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/version.rb

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

data/lib/philiprehberger/csv_kit.rb

@@ -51,6 +51,35 @@ 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
+
     # Filter rows and return matching rows as a CSV string.
     #
     # @param path [String] file path

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_kit
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.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.
@@ -30,11 +30,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