zlight_csv 0.1.1-aarch64-linux → 0.2.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03f08458d8b03148a0a945369c97697ad7db3ba3d6a67f3c1869fc2932d0cd21
-  data.tar.gz: 80da34e4c72dac467ffe7bb248c368d0ef02eae176345710fe74522e889efaeb
+  metadata.gz: dd53dcf4937f1cda9a6514ab0e881dc79efc7eeb534fbb770f187b64c8fb605a
+  data.tar.gz: 372b67f7913d030344b4a6489fdb153eeacbd06a9696a898314981d43bfa8738
 SHA512:
-  metadata.gz: 421912c62937fd59d61b2e96d5f15942df95741a29bf1c52a40edd9dd7d985df91460e9db012a94ff830f96a75a7282dc9bc30c3f9b6150d8bb2ed4933d254a5
-  data.tar.gz: 9ad24ada8c16312362b3290eaf549a5d59513dd7f23486cc6e5694f7f41b559343f2fe7be7e4e00bb988e2de1ffb99952ec2ca683b3a5dba6bf3f53694ed983a
+  metadata.gz: ce9062dcbd21109821f5fe11be17d04df11556531059ae60e8cc5c88eb05cf9a910fa3af614498ec8523e91e416886353e5a66c384cad69f267654c0d7cbeb58
+  data.tar.gz: f1cc6aaa1c0e17be7e319098b2a72144c297b5a7299ab4280ce92c398d4bb341e0138791dc80d4dc2b7c2ad437e09bd252cf37cc637d2d63c7714f78a0b82d79

data/README.md

@@ -1,346 +1,144 @@
-# ZLight
+# ZLight CSV
 
 [![Gem Version](https://badge.fury.io/rb/zlight_csv.svg)](https://badge.fury.io/rb/zlight_csv)
-[![CI](https://github.com/yourusername/zlight-csv/actions/workflows/ci.yml/badge.svg)](https://github.com/yourusername/zlight-csv/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A blazing-fast CSV parser for Ruby, powered by Rust. ZLight provides a simple API for parsing CSV files **up to 30x faster** than Ruby's standard CSV library.
+A fast CSV parser for Ruby, powered by Rust.
 
-## Features
+## Why ZLight?
 
-- **High Performance**: Built with Rust's `csv` crate for maximum speed
-- **Simple API**: Just `ZLight.parse(csv_string)`
-- **Automatic Type Conversion**: Optional numeric conversion for integer and float fields
-- **Symbol Headers**: Automatically converts headers to symbols
-- **Cross-Platform**: Pre-built binaries for Linux, macOS, and Windows
+Ruby's built-in CSV library is slow. ZLight parses CSV files **up to 30x faster** by using Rust under the hood.
 
-## Benchmarks
+### Benchmark Results
 
-Parsing 100,000 rows with headers and numeric conversion:
+Parsing with headers and numeric conversion (Apple M1):
 
-```
-                           user     system      total        real
-Ruby StdLib CSV:       1.49s
-ZLight (Rust):         0.05s
-```
+| Dataset | Ruby CSV | ZLight | Speedup |
+|---------|----------|--------|---------|
+| 1K rows | 12.6ms | 0.3ms | **42x faster** |
+| 10K rows | 133ms | 4.4ms | **30x faster** |
+| 100K rows | 1,458ms | 78ms | **19x faster** |
 
-**~30x faster** than Ruby's standard CSV library!
+File reading comparison (100K rows):
 
-## Installation
+| Method | Ruby CSV | ZLight | Speedup |
+|--------|----------|--------|---------|
+| Read all | 1,596ms | 58ms | **27x faster** |
+| Streaming | 1,104ms | 74ms | **15x faster** |
 
-Add this line to your application's Gemfile:
+Iterations per second (10K rows):
 
-```ruby
-gem 'zlight_csv'
 ```
-
-Then execute:
-
-```bash
-bundle install
+ZLight.parse:   253 i/s
+ZLight.stream:  159 i/s
+Ruby CSV:         8 i/s  — 33x slower
 ```
 
-Or install it directly:
+## Installation
 
-```bash
-gem install zlight_csv
+```ruby
+gem 'zlight_csv'
 ```
 
-### Prebuilt Binaries (No Rust Required)
-
-ZLight ships **prebuilt native gems** for the following platforms:
-
-| Platform | Architecture |
-|----------|--------------|
-| Linux | x86_64, aarch64 |
-| Linux (musl/Alpine) | x86_64 |
-| macOS | x86_64 (Intel), arm64 (Apple Silicon) |
-| Windows | x64 (UCRT) |
-
-When you run `gem install zlight_csv`, RubyGems automatically downloads the correct prebuilt binary for your platform. **No Rust toolchain required!**
-
-### Requirements
-
-- Ruby >= 3.0.0 (3.0, 3.1, 3.2, 3.3)
-- Supported platforms: Linux, macOS, Windows (see above)
+No Rust toolchain required — prebuilt binaries are available for Linux, macOS, and Windows.
 
 ## Usage
 
-### Basic Parsing
-
 ```ruby
 require 'zlight_csv'
 
-csv_data = <<~CSV
-  name,age,city
-  Alice,30,New York
-  Bob,25,London
-  Charlie,35,Paris
-CSV
+# Parse a CSV string
+data = ZLight.parse("name,age\nAlice,30\nBob,25")
+# => [{:name=>"Alice", :age=>"30"}, {:name=>"Bob", :age=>"25"}]
 
-# Parse with headers (returns array of hashes with symbol keys)
-result = ZLight.parse(csv_data, headers: true)
-# => [{:name=>"Alice", :age=>"30", :city=>"New York"}, ...]
+# With automatic numeric conversion
+data = ZLight.parse(csv_string, converters: :numeric)
+# => [{:name=>"Alice", :age=>30}, {:name=>"Bob", :age=>25}]
 
-# headers: true is the default
-result = ZLight.parse(csv_data)
-```
-
-### Numeric Conversion
-
-```ruby
-# Automatically convert numeric strings to integers/floats
-result = ZLight.parse(csv_data, headers: true, converters: :numeric)
-# => [{:name=>"Alice", :age=>30, :city=>"New York"}, ...]
-```
+# Read from a file
+data = ZLight.read("users.csv")
 
-### Without Headers
-
-```ruby
-csv_data = "Alice,30,New York\nBob,25,London"
-
-result = ZLight.parse(csv_data, headers: false)
-# => [["Alice", "30", "New York"], ["Bob", "25", "London"]]
-
-# With numeric conversion
-result = ZLight.parse(csv_data, headers: false, converters: :numeric)
-# => [["Alice", 30, "New York"], ["Bob", 25, "London"]]
-```
-
-### Reading Files
-
-```ruby
-# Read and parse a CSV file
-result = ZLight.read("path/to/file.csv", headers: true, converters: :numeric)
-```
-
-### Iteration
-
-```ruby
 # Iterate over rows
-ZLight.foreach(csv_data, headers: true) do |row|
+ZLight.foreach(csv_string) do |row|
   puts row[:name]
 end
-
-# With Enumerator
-enum = ZLight.foreach(csv_data, headers: true)
-enum.map { |row| row[:name].upcase }
-```
-
-### Custom Delimiters
-
-```ruby
-# Tab-separated values
-tsv_data = "name\tage\nAlice\t30"
-result = ZLight.parse(tsv_data, headers: true, col_sep: "\t")
-
-# Semicolon-separated (common in European locales)
-result = ZLight.parse(data, headers: true, col_sep: ";")
 ```
 
-### Options Reference
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `headers` | Boolean | `true` | Treat first row as headers |
-| `converters` | Symbol | `nil` | Set to `:numeric` for auto-conversion |
-| `col_sep` | String | `","` | Column separator character |
-| `quote_char` | String | `"` | Quote character |
-| `flexible` | Boolean | `true` | Allow variable length records |
-
-## Development
+### Streaming Large Files
 
-### Prerequisites
+For large files, use streaming to process rows one at a time without loading everything into memory:
 
-1. Docker (for cross-compilation)
-2. Rust toolchain (for local development)
-   ```bash
-   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-   ```
-
-### Local Development
-
-```bash
-# Clone the repository
-git clone https://github.com/yourusername/zlight-csv.git
-cd zlight-csv
-
-# Install dependencies
-bundle install
-
-# Compile the native extension (requires Rust)
-bundle exec rake compile
-
-# Run tests
-bundle exec rake spec
+```ruby
+# Stream from a file (auto-closes when block exits)
+ZLight.open("large_file.csv") do |reader|
+  reader.each do |row|
+    process(row)
+  end
+end
 
-# Run benchmarks
-bundle exec rake benchmark
+# Lazy enumeration — stop early without loading remaining rows
+ZLight.open("huge_file.csv", converters: :numeric) do |reader|
+  high_scores = reader.lazy
+                      .select { |row| row[:score] > 90 }
+                      .first(100)
+end
 
-# Clean build artifacts
-bundle exec rake clean
+# Manual control
+reader = ZLight.stream_file("data.csv")
+while row = reader.next_row
+  break if row[:id] > 1000
+  process(row)
+end
+reader.close
 ```
 
-## Publishing to RubyGems
-
-### Automated Release (Recommended)
+**Streaming is especially efficient for partial reads:**
 
-Releases are fully automated via GitHub Actions. When you push a version tag:
-
-1. Builds prebuilt native gems for all 6 platforms
-2. Publishes all gems to RubyGems
-3. Creates a GitHub Release with all gem files attached
-
-**To release:**
-
-```bash
-# 1. Update version
-vim VERSION
-
-# 2. Update changelog
-vim CHANGELOG.md
-
-# 3. Commit and tag
-git add -A
-git commit -m "Release v0.1.0"
-git tag v0.1.0
-git push origin main --tags
 ```
+Finding first 100 rows from 100K dataset:
 
-GitHub Actions handles the rest automatically.
-
-### RubyGems setup (one-time)
-
-Publishing uses [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC from GitHub Actions — no API key secret).
-
-Because `zlight_csv` is not on RubyGems yet, register a **pending** trusted publisher:
-
-1. Sign in at [rubygems.org](https://rubygems.org/)
-2. Open [Pending trusted publishers](https://rubygems.org/profile/oidc/pending_trusted_publishers) → **Create**
-3. Set:
-   - **Gem name:** `zlight_csv`
-   - **Repository owner:** `zaidanch`
-   - **Repository name:** `zlight`
-   - **Workflow filename:** `release.yml`
-4. Save. The first successful workflow run will create the gem and add you as owner.
-
-If publish fails with an auth error, confirm the workflow filename is exactly `release.yml` and matches what you registered on RubyGems.
-
-**Important:** Trusted publishing only works after the updated `release.yml` is on GitHub (`main`). Older workflow runs used a `RUBYGEMS_API_KEY` secret and ignored your pending publisher.
-
-If you set **Environment** to `release` on RubyGems, uncomment `environment: release` under the `release` job in `.github/workflows/release.yml`.
-
-### Re-run after pushing the workflow fix
-
-```bash
-git push origin main
-# Actions → Release → Run workflow   (uses main; no tag required)
-# or move the tag to the latest commit and push the tag again
+Ruby CSV (full parse):  1,696ms
+ZLight.parse (full):       73ms
+ZLight.stream (lazy):     0.3ms  ← 5,600x faster!
 ```
 
-### Manual Release (Local Build)
-
-Build locally with Docker:
+### Options
 
-```bash
-# Install cross-compilation tools
-gem install rake-compiler-dock
+| Option | Default | Description |
+|--------|---------|-------------|
+| `headers` | `true` | Use first row as headers (returns hashes). Set `false` for arrays. |
+| `converters` | `nil` | Set to `:numeric` to convert numbers automatically |
+| `col_sep` | `","` | Column separator (`"\t"` for TSV, `";"` for European CSV) |
+| `quote_char` | `"` | Quote character |
+| `flexible` | `true` | Allow rows with varying column counts |
 
-# Build for a single platform (requires Docker on the host)
-rake dock:arm64-darwin
+## Compatibility
 
-# Build for ALL platforms
-rake dock:all
+Works as a drop-in replacement for common `CSV.parse` patterns:
 
-# Output in pkg/:
-#   zlight_csv-0.1.0-x86_64-linux.gem
-#   zlight_csv-0.1.0-arm64-darwin.gem
-#   zlight_csv-0.1.0-x64-mingw-ucrt.gem
-#   ... etc
-
-# Push all gems to RubyGems
-rake release:push
-```
-
-## Project Structure
+```ruby
+# Before
+CSV.parse(data, headers: true, header_converters: :symbol, converters: :numeric)
 
-```
-zlight-csv/
-├── ext/
-│   └── zlight_csv/           # Rust native extension
-│       ├── src/
-│       │   ├── lib.rs        # Entry point & Ruby bindings
-│       │   ├── error.rs      # Error types (enum-based)
-│       │   ├── options.rs    # Parse options handling
-│       │   ├── parser.rs     # CSV parsing logic
-│       │   └── converter.rs  # Type conversion utilities
-│       ├── Cargo.toml        # Rust dependencies
-│       └── extconf.rb        # Extension configuration
-├── lib/
-│   ├── zlight_csv.rb         # Main Ruby entry point
-│   └── zlight_csv/
-│       └── version.rb        # Reads VERSION from gem root
-├── spec/                     # RSpec tests
-├── benchmark/                # Performance benchmarks
-├── Gemfile                   # Ruby dependencies
-├── Rakefile                  # Build tasks
-├── zlight_csv.gemspec        # Gem specification
-├── VERSION                   # Single source of truth for release version
-└── README.md
+# After
+ZLight.parse(data, converters: :numeric)
 ```
 
-## API Compatibility with Ruby CSV
+## Requirements
 
-| Ruby CSV | ZLight | Status |
-|----------|--------|--------|
-| `CSV.parse(str, headers: true)` | `ZLight.parse(str, headers: true)` | ✅ |
-| `CSV.parse(str, header_converters: :symbol)` | Automatic | ✅ |
-| `CSV.parse(str, converters: :numeric)` | `ZLight.parse(str, converters: :numeric)` | ✅ |
-| `CSV.read(path)` | `ZLight.read(path)` | ✅ |
-| `CSV.foreach(str) { }` | `ZLight.foreach(str) { }` | ✅ |
-| `CSV.parse(str, col_sep: "\t")` | `ZLight.parse(str, col_sep: "\t")` | ✅ |
-| Streaming/lazy parsing | Not yet supported | 🚧 |
-| Writing CSV | Not supported | ❌ |
+- Ruby 3.0+
+- Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), or Windows (x64)
 
-## Error Handling
+## Roadmap
 
-ZLight provides descriptive error messages:
-
-```ruby
-begin
-  ZLight.parse(invalid_csv)
-rescue => e
-  puts e.class   # RuntimeError, ArgumentError, EncodingError, etc.
-  puts e.message # Descriptive error message
-end
-```
-
-Error types:
-- `ArgumentError` - Invalid arguments or options
-- `EncodingError` - Invalid UTF-8 in headers
-- `RuntimeError` - CSV parsing errors
-- `IOError` - File reading errors
+- [x] Streaming/lazy parsing for large files
+- [ ] CSV writing support
+- [ ] Custom converter procs
 
 ## Contributing
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-### Running Tests
-
-```bash
-bundle exec rake spec
-```
+Bug reports and pull requests are welcome on [GitHub](https://github.com/zaidanch/zlight).
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Acknowledgments
-
-- [csv](https://crates.io/crates/csv) - Rust CSV parsing library by BurntSushi
-- [magnus](https://crates.io/crates/magnus) - Ruby bindings for Rust
-- [rb-sys](https://github.com/oxidize-rb/rb-sys) - Ruby build system integration
+MIT

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/zlight_csv.rb

@@ -10,31 +10,230 @@ rescue LoadError
   require_relative 'zlight_csv/zlight_csv'
 end
 
+# ZLight is a high-performance CSV parser for Ruby, powered by Rust.
+#
+# It provides a simple, Ruby CSV-compatible API for parsing CSV files
+# up to 30x faster than the standard library.
+#
+# @example Basic parsing with headers
+#   result = ZLight.parse("name,age\nAlice,30\nBob,25")
+#   # => [{:name=>"Alice", :age=>"30"}, {:name=>"Bob", :age=>"25"}]
+#
+# @example Parsing with numeric conversion
+#   result = ZLight.parse("name,age\nAlice,30", converters: :numeric)
+#   # => [{:name=>"Alice", :age=>30}]
+#
+# @example Parsing without headers
+#   result = ZLight.parse("Alice,30\nBob,25", headers: false)
+#   # => [["Alice", "30"], ["Bob", "25"]]
+#
+# @example Reading from a file
+#   result = ZLight.read("path/to/file.csv", headers: true)
+#
+# @example Streaming large files
+#   ZLight.stream_file("large.csv") do |reader|
+#     reader.each { |row| process(row) }
+#   end
+#
+# @example Lazy iteration with Enumerator
+#   reader = ZLight.stream_file("large.csv")
+#   reader.lazy.select { |row| row[:age] > 30 }.first(10)
+#   reader.close
+#
+# @see https://github.com/zaidanch/zlight
 module ZLight
+  # Base error class for all ZLight errors
   class Error < StandardError; end
+
+  # Raised when CSV parsing fails due to malformed data
   class ParseError < Error; end
+
+  # Raised when CSV contains invalid UTF-8 encoding
   class EncodingError < Error; end
 
+  # Raised when attempting to use a closed stream reader
+  class StreamClosedError < Error; end
+
+  # Parses a CSV string and returns an array of rows.
+  #
+  # This method is implemented as a native Rust extension for maximum performance.
+  #
+  # @param csv_string [String] The CSV data to parse
+  # @param headers [Boolean] Treat first row as headers (default: true)
+  # @param converters [Symbol, nil] Set to :numeric for auto-conversion of integers/floats
+  # @param col_sep [String] Column separator character (default: ",")
+  # @param quote_char [String] Quote character for escaping (default: '"')
+  # @param flexible [Boolean] Allow variable-length records (default: true)
+  #
+  # @return [Array<Hash>] When headers: true, returns array of Hashes with Symbol keys
+  # @return [Array<Array>] When headers: false, returns array of Arrays
+  #
+  # @raise [ArgumentError] If options are invalid
+  # @raise [ZLight::ParseError] If CSV data is malformed
+  # @raise [ZLight::EncodingError] If headers contain invalid UTF-8
+  #
+  # @example Parse with headers (default)
+  #   ZLight.parse("name,age\nAlice,30")
+  #   # => [{:name=>"Alice", :age=>"30"}]
+  #
+  # @example Parse without headers
+  #   ZLight.parse("Alice,30", headers: false)
+  #   # => [["Alice", "30"]]
+  #
+  # @example Parse with numeric conversion
+  #   ZLight.parse("name,age\nAlice,30", converters: :numeric)
+  #   # => [{:name=>"Alice", :age=>30}]
+  #
+  # @example Parse TSV (tab-separated values)
+  #   ZLight.parse("name\tage\nAlice\t30", col_sep: "\t")
+  #   # => [{:name=>"Alice", :age=>"30"}]
+  #
+  # @note The parse method is defined in the Rust native extension.
+  #   See ext/zlight_csv/src/lib.rs for implementation.
+
+  # StreamReader is defined in the Rust extension.
+  # It provides lazy/streaming CSV parsing for large files.
+  #
+  # @see ZLight.stream
+  # @see ZLight.stream_file
+
   class << self
-    # Parses a CSV file and returns an array of hashes or arrays.
+    # Reads and parses a CSV file from disk.
+    #
+    # Convenience method that reads the file contents and passes them to {.parse}.
+    # The file is read with UTF-8 encoding.
     #
     # @param path [String] Path to the CSV file
-    # @param options [Hash] Parsing options (same as .parse)
-    # @return [Array<Hash>, Array<Array>] Parsed CSV data
+    # @param headers [Boolean] Treat first row as headers (default: true)
+    # @param converters [Symbol, nil] Set to :numeric for auto-conversion
+    # @param col_sep [String] Column separator character (default: ",")
+    # @param quote_char [String] Quote character for escaping (default: '"')
+    # @param flexible [Boolean] Allow variable-length records (default: true)
+    #
+    # @return [Array<Hash>] When headers: true, returns array of Hashes with Symbol keys
+    # @return [Array<Array>] When headers: false, returns array of Arrays
+    #
+    # @raise [Errno::ENOENT] If the file does not exist
+    # @raise [ArgumentError] If options are invalid
+    # @raise [ZLight::ParseError] If CSV data is malformed
+    #
+    # @example Read a CSV file with headers
+    #   ZLight.read("users.csv")
+    #   # => [{:name=>"Alice", :age=>"30"}, ...]
+    #
+    # @example Read with numeric conversion
+    #   ZLight.read("users.csv", converters: :numeric)
+    #   # => [{:name=>"Alice", :age=>30}, ...]
+    #
+    # @example Read a TSV file
+    #   ZLight.read("data.tsv", col_sep: "\t")
+    #
+    # @see .parse
     def read(path, **options)
       parse(File.read(path, encoding: 'UTF-8'), **options)
     end
 
     # Iterates over each row in the CSV string.
     #
+    # When called with a block, yields each row and returns nil.
+    # When called without a block, returns an Enumerator for lazy iteration.
+    #
     # @param csv_string [String] The CSV data to parse
-    # @param options [Hash] Parsing options (same as .parse)
-    # @yield [row] Each row as a Hash or Array
-    # @return [Enumerator] If no block given
+    # @param headers [Boolean] Treat first row as headers (default: true)
+    # @param converters [Symbol, nil] Set to :numeric for auto-conversion
+    # @param col_sep [String] Column separator character (default: ",")
+    # @param quote_char [String] Quote character for escaping (default: '"')
+    # @param flexible [Boolean] Allow variable-length records (default: true)
+    #
+    # @yield [row] Yields each row to the block
+    # @yieldparam row [Hash, Array] A single row (Hash with headers, Array without)
+    #
+    # @return [nil] When a block is given
+    # @return [Enumerator] When no block is given, for lazy iteration
+    #
+    # @example Iterate with a block
+    #   ZLight.foreach("name,age\nAlice,30\nBob,25") do |row|
+    #     puts row[:name]
+    #   end
+    #   # Output:
+    #   # Alice
+    #   # Bob
+    #
+    # @example Use as Enumerator
+    #   names = ZLight.foreach("name,age\nAlice,30").map { |row| row[:name] }
+    #   # => ["Alice"]
+    #
+    # @example Chain with Enumerable methods
+    #   adults = ZLight.foreach(csv_data, converters: :numeric)
+    #              .select { |row| row[:age] >= 18 }
+    #              .map { |row| row[:name] }
+    #
+    # @see .parse
     def foreach(csv_string, **options, &block)
       return to_enum(:foreach, csv_string, **options) unless block_given?
 
       parse(csv_string, **options).each(&block)
     end
+
+    # Creates a streaming reader for a CSV file with automatic resource management.
+    #
+    # This is the most memory-efficient way to process large CSV files.
+    # Rows are read one at a time directly from disk.
+    #
+    # When called with a block, automatically closes the reader after
+    # the block completes (even if an exception is raised).
+    #
+    # @param path [String] Path to the CSV file
+    # @param headers [Boolean] Treat first row as headers (default: true)
+    # @param converters [Symbol, nil] Set to :numeric for auto-conversion
+    # @param col_sep [String] Column separator character (default: ",")
+    # @param quote_char [String] Quote character (default: '"')
+    # @param flexible [Boolean] Allow variable-length records (default: true)
+    #
+    # @yield [reader] If a block is given, yields the reader and auto-closes
+    # @yieldparam reader [ZLight::StreamReader] The streaming reader
+    #
+    # @return [ZLight::StreamReader] The streaming reader (if no block)
+    # @return [Object] The block's return value (if block given)
+    #
+    # @raise [Errno::ENOENT] If the file does not exist
+    # @raise [Errno::EACCES] If the file is not readable
+    #
+    # @example Process a large file row by row
+    #   ZLight.open("users.csv") do |reader|
+    #     reader.each do |row|
+    #       User.create!(name: row[:name], email: row[:email])
+    #     end
+    #   end
+    #
+    # @example Get first 100 matching rows lazily
+    #   ZLight.open("data.csv", converters: :numeric) do |reader|
+    #     reader.lazy
+    #           .select { |row| row[:score] > 90 }
+    #           .first(100)
+    #   end
+    #
+    # @example Manual resource management
+    #   reader = ZLight.open("large.csv")
+    #   begin
+    #     reader.each { |row| process(row) }
+    #   ensure
+    #     reader.close
+    #   end
+    #
+    # @see ZLight::StreamReader
+    def open(path, **options)
+      reader = stream_file(path, **options)
+
+      if block_given?
+        begin
+          yield reader
+        ensure
+          reader.close unless reader.closed?
+        end
+      else
+        reader
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zlight_csv
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: aarch64-linux
 authors:
 - Zaidan Chaudhary
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-05-21 00:00:00.000000000 Z
 dependencies: []
 description: |
   ZLight is a blazing-fast CSV parser that provides a drop-in replacement