zlight_csv 0.4.0-aarch64-linux → 0.6.0-aarch64-linux

data/lib/zlight_csv/native.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ZLight
+  # Loads the compiled extension.
+  #
+  # A precompiled gem ships one shared library per Ruby minor version, laid out
+  # as lib/zlight_csv/<major.minor>/zlight_csv.<so|bundle|dll>, because a C
+  # extension built against one Ruby's ABI cannot be loaded by another. A gem
+  # built from source has a single library at lib/zlight_csv instead, so try
+  # the versioned path first and fall back.
+  module Native
+    def self.load!
+      require_relative "#{RUBY_VERSION[/\d+\.\d+/]}/zlight_csv"
+    rescue LoadError
+      require_relative 'zlight_csv'
+    end
+  end
+end
+
+ZLight::Native.load!

data/lib/zlight_csv.rb

@@ -1,304 +1,183 @@
 # frozen_string_literal: true
 
 require_relative 'zlight_csv/version'
+require_relative 'zlight_csv/errors'
+require_relative 'zlight_csv/native'
 
-# Load the prebuilt native extension for this Ruby version
-begin
-  ruby_version = RUBY_VERSION.match(/(\d+\.\d+)/)[1]
-  require_relative "zlight_csv/#{ruby_version}/zlight_csv"
-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"}]
+# ZLight is a CSV parser and writer for Ruby, implemented in Rust.
 #
-# @example Parsing with numeric conversion
-#   result = ZLight.parse("name,age\nAlice,30", converters: :numeric)
-#   # => [{:name=>"Alice", :age=>30}]
+# The public API is deliberately small. Four of the methods below are defined
+# in the native extension and four are defined here in Ruby as conveniences on
+# top of them; which is which is noted on each.
 #
-# @example Parsing without headers
-#   result = ZLight.parse("Alice,30\nBob,25", headers: false)
-#   # => [["Alice", "30"], ["Bob", "25"]]
+# @example Parse a string
+#   ZLight.parse("name,age\nAlice,30")        # => [{name: "Alice", age: "30"}]
 #
-# @example Reading from a file
-#   result = ZLight.read("path/to/file.csv", headers: true)
+# @example Parse a file, converting numbers
+#   ZLight.read("users.csv", converters: :numeric)
 #
-# @example Streaming large files
-#   ZLight.stream_file("large.csv") do |reader|
-#     reader.each { |row| process(row) }
-#   end
+# @example Stream a large file in constant memory
+#   ZLight.open("huge.csv") { |reader| reader.each { |row| process(row) } }
 #
-# @example Lazy iteration with Enumerator
-#   reader = ZLight.stream_file("large.csv")
-#   reader.lazy.select { |row| row[:age] > 30 }.first(10)
-#   reader.close
+# @example Write a file
+#   ZLight.write("out.csv", [{ name: "Alice", age: 30 }])
 #
-# @see https://github.com/zaidanch/zlight
+# @see https://github.com/codebyisaad/zlight
+# @see file:README.md#differences-from-stdlib-csv Differences from stdlib CSV
 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.
-
-  # Generates a CSV string from an array of rows.
-  #
-  # This method is implemented as a native Rust extension for maximum performance.
-  #
-  # @param rows [Array<Hash>, Array<Array>] The data to convert to CSV
-  # @param headers [Boolean] Write header row for hash input (default: true)
-  # @param col_sep [String] Column separator character (default: ",")
-  # @param quote_char [String] Quote character for escaping (default: '"')
-  # @param force_quotes [Boolean] Force quoting all fields (default: false)
-  #
-  # @return [String] The generated CSV string
-  #
-  # @raise [ArgumentError] If options are invalid or rows format is mixed
-  #
-  # @example Generate CSV from array of hashes
-  #   ZLight.generate([{name: "Alice", age: 30}, {name: "Bob", age: 25}])
-  #   # => "name,age\nAlice,30\nBob,25\n"
-  #
-  # @example Generate CSV from array of arrays (no headers)
-  #   ZLight.generate([["Alice", 30], ["Bob", 25]])
-  #   # => "Alice,30\nBob,25\n"
-  #
-  # @example Generate without headers
-  #   ZLight.generate([{name: "Alice"}], headers: false)
-  #   # => "Alice\n"
-  #
-  # @example Generate TSV
-  #   ZLight.generate([{a: 1, b: 2}], col_sep: "\t")
-  #   # => "a\tb\n1\t2\n"
-  #
-  # @note The generate method is defined in the Rust native extension.
-  #   See ext/zlight_csv/src/writer.rs for implementation.
+  class << self
+    # @!method parse(csv_string, headers: true, converters: nil, col_sep: ",", quote_char: "\"", flexible: true)
+    #   Parses a CSV string into an Array of rows.
+    #
+    #   Defined in the native extension; see ext/zlight_csv/src/read/eager.rs.
+    #   Reads Ruby's string buffer directly without copying it.
+    #
+    #   @param csv_string [String] the CSV data
+    #   @param headers [Boolean] treat the first row as headers, returning
+    #     Hashes with Symbol keys; when false, rows are Arrays
+    #   @param converters [Symbol, nil] `:numeric` converts integers and floats
+    #   @param col_sep [String] single-byte column separator
+    #   @param quote_char [String] single-byte quote character
+    #   @param flexible [Boolean] allow rows with differing field counts
+    #   @return [Array<Hash>, Array<Array>] one element per row
+    #   @raise [ZLight::ParseError] if the CSV is malformed
+    #   @raise [ZLight::EncodingError] if a header is not valid UTF-8
+    #   @raise [ArgumentError] if an option is invalid
 
-  # StreamReader is defined in the Rust extension.
-  # It provides lazy/streaming CSV parsing for large files.
-  #
-  # @see ZLight.stream
-  # @see ZLight.stream_file
+    # @!method generate(rows, headers: true, col_sep: ",", quote_char: "\"", force_quotes: false)
+    #   Builds a CSV string from an Array of rows.
+    #
+    #   Defined in the native extension; see ext/zlight_csv/src/write/mod.rs.
+    #   Accepts an Array of Hashes or an Array of Arrays, not a mix of both.
+    #   For Hashes the column order comes from the keys of the first one.
+    #
+    #   @param rows [Array<Hash>, Array<Array>] the rows to write
+    #   @param headers [Boolean] emit a header row (Hash input only)
+    #   @param col_sep [String] single-byte column separator
+    #   @param quote_char [String] single-byte quote character
+    #   @param force_quotes [Boolean] quote every field, not only those needing it
+    #   @return [String] the generated CSV
+    #   @raise [ArgumentError] if an option is invalid or the row types are mixed
 
-  class << self
-    # Reads and parses a CSV file from disk.
+    # @!method stream(csv_string, **options)
+    #   Returns a {ZLight::StreamReader} over a CSV string.
     #
-    # Convenience method that reads the file contents and passes them to {.parse}.
-    # The file is read with UTF-8 encoding.
+    #   Defined in the native extension; see ext/zlight_csv/src/read/stream.rs.
+    #   Takes the same options as {.parse}.
     #
-    # @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 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
+    #   @return [ZLight::StreamReader] a single-pass reader
+
+    # @!method stream_file(path, **options)
+    #   Returns a {ZLight::StreamReader} over a file.
     #
-    # @example Read a CSV file with headers
-    #   ZLight.read("users.csv")
-    #   # => [{:name=>"Alice", :age=>"30"}, ...]
+    #   Defined in the native extension. The file is opened immediately, so a
+    #   missing or unreadable path raises here rather than on the first read.
+    #   Prefer {.open}, which closes the reader for you.
     #
-    # @example Read with numeric conversion
-    #   ZLight.read("users.csv", converters: :numeric)
-    #   # => [{:name=>"Alice", :age=>30}, ...]
+    #   @return [ZLight::StreamReader] a single-pass reader
+    #   @raise [IOError] if the file does not exist or cannot be read
+
+    # Reads and parses a CSV file.
     #
-    # @example Read a TSV file
-    #   ZLight.read("data.tsv", col_sep: "\t")
+    # Convenience wrapper: reads the file as UTF-8 and hands it to {.parse},
+    # so the whole file is held in memory. Use {.open} for large files.
     #
+    # @param path [String] path to the CSV file
+    # @param options [Hash] any option accepted by {.parse}
+    # @return [Array<Hash>, Array<Array>] one element per row
+    # @raise [Errno::ENOENT] if the file does not exist
     # @see .parse
     def read(path, **options)
       parse(File.read(path, encoding: 'UTF-8'), **options)
     end
 
-    # Writes CSV data to a file.
-    #
-    # Convenience method that generates CSV and writes to disk.
-    # The file is written with UTF-8 encoding.
-    #
-    # @param path [String] Path to the output CSV file
-    # @param rows [Array<Hash>, Array<Array>] The data to write
-    # @param headers [Boolean] Write header row for hash input (default: true)
-    # @param col_sep [String] Column separator character (default: ",")
-    # @param quote_char [String] Quote character for escaping (default: '"')
-    # @param force_quotes [Boolean] Force quoting all fields (default: false)
-    #
-    # @return [Integer] Number of bytes written
-    #
-    # @raise [Errno::ENOENT] If the directory does not exist
-    # @raise [Errno::EACCES] If the file is not writable
-    # @raise [ArgumentError] If options are invalid
+    # Writes rows to a CSV file.
     #
-    # @example Write hashes to CSV
-    #   ZLight.write("users.csv", [{name: "Alice", age: 30}])
-    #
-    # @example Write arrays to CSV
-    #   ZLight.write("data.csv", [["a", "b"], [1, 2]])
-    #
-    # @example Write TSV
-    #   ZLight.write("data.tsv", rows, col_sep: "\t")
+    # Convenience wrapper around {.generate}. The CSV is built in memory before
+    # being written, so this is not suited to output larger than RAM.
     #
+    # @param path [String] path to write to
+    # @param rows [Array<Hash>, Array<Array>] the rows to write
+    # @param options [Hash] any option accepted by {.generate}
+    # @return [Integer] bytes written
+    # @raise [Errno::ENOENT] if the directory does not exist
     # @see .generate
     def write(path, rows, **options)
       File.write(path, generate(rows, **options), encoding: 'UTF-8')
     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 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)
+    # Iterates over the rows of a CSV string.
     #
-    # @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] }
+    # Note that unlike `CSV.foreach`, this takes a **string, not a path**, and
+    # parses the whole input before yielding. For lazy iteration use {.open}.
     #
+    # @param csv_string [String] the CSV data
+    # @param options [Hash] any option accepted by {.parse}
+    # @yieldparam row [Hash, Array] each row in turn
+    # @return [nil, Enumerator] an Enumerator when no block is given
     # @see .parse
-    def foreach(csv_string, **options, &block)
+    def foreach(csv_string, **options, &)
       return to_enum(:foreach, csv_string, **options) unless block_given?
 
-      parse(csv_string, **options).each(&block)
+      parse(csv_string, **options).each(&)
     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
+    # Streams a CSV file, closing the reader afterwards.
+    #
+    # The memory-efficient way to process a large file: rows are read one at a
+    # time rather than materialised up front. With a block the reader is closed
+    # when the block exits, including on an exception.
+    #
+    # @param path [String] path to the CSV file
+    # @param options [Hash] any option accepted by {.parse}
+    # @yieldparam reader [ZLight::StreamReader] the reader
+    # @return [Object, ZLight::StreamReader] the block's value, or the reader
+    #   itself when no block is given, in which case you must close it
+    # @raise [IOError] if the file does not exist or cannot be read
+    #
+    # @example Stop early without reading the rest of the file
+    #   ZLight.open("huge.csv", converters: :numeric) do |reader|
+    #     reader.lazy.select { |row| row[:score] > 90 }.first(100)
     #   end
     #
     # @see ZLight::StreamReader
     def open(path, **options)
       reader = stream_file(path, **options)
+      return reader unless block_given?
 
-      if block_given?
-        begin
-          yield reader
-        ensure
-          reader.close unless reader.closed?
-        end
-      else
-        reader
+      begin
+        yield reader
+      ensure
+        reader.close unless reader.closed?
       end
     end
   end
+
+  # A single-pass reader over a CSV source, yielding one row at a time.
+  #
+  # Defined in the native extension; see ext/zlight_csv/src/read/stream.rs.
+  # Obtained from {ZLight.stream}, {ZLight.stream_file} or {ZLight.open}.
+  #
+  # Includes `Enumerable`, so `map`, `select`, `find` and `lazy` all work — but
+  # the reader is **single-pass**: each row is consumed as it is read, so a
+  # second enumeration yields nothing and there is no rewind.
+  #
+  # @!method next_row
+  #   @return [Hash, Array, nil] the next row, or nil once exhausted
+  #   @raise [ZLight::StreamClosedError] if the reader has been closed
+  # @!method each
+  #   @yieldparam row [Hash, Array] each row in turn
+  #   @return [self, Enumerator] an Enumerator when no block is given
+  # @!method headers
+  #   @return [Array<Symbol>, nil] the header symbols, or nil without headers
+  # @!method close
+  #   Releases the underlying file or buffer. Idempotent.
+  #   @return [nil]
+  # @!method closed?
+  #   @return [Boolean]
+  # @!method eof?
+  #   @return [Boolean] true once exhausted or closed
+  # Reopened solely to attach the documentation above; the class itself and
+  # all of its methods come from the extension.
+  class StreamReader; end # rubocop:disable Lint/EmptyClass
 end

metadata

@@ -1,18 +1,33 @@
 --- !ruby/object:Gem::Specification
 name: zlight_csv
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: aarch64-linux
 authors:
 - Zaidan Chaudhary
+- Saad Chaudhary
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-06 00:00:00.000000000 Z
-dependencies: []
+date: 2026-09-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: |
   ZLight brings the speed of Rust to Ruby's CSV parsing. Built as a native
-  extension, it delivers up to 30x faster performance than Ruby's standard
+  extension, it delivers up to 40x faster performance than Ruby's standard
   CSV library while maintaining full API compatibility. Whether you're parsing
   small configuration files or processing millions of rows, ZLight handles it
   efficiently. The streaming API enables memory-efficient processing of large
@@ -24,22 +39,36 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ARCHITECTURE.md
 - CHANGELOG.md
 - LICENSE
 - README.md
 - VERSION
+- ext/zlight_csv/Cargo.toml
+- ext/zlight_csv/extconf.rb
+- ext/zlight_csv/src/convert.rs
+- ext/zlight_csv/src/error.rs
+- ext/zlight_csv/src/lib.rs
+- ext/zlight_csv/src/options.rs
+- ext/zlight_csv/src/reader.rs
+- ext/zlight_csv/src/row.rs
 - lib/zlight_csv.rb
-- lib/zlight_csv/3.0/zlight_csv.so
 - lib/zlight_csv/3.1/zlight_csv.so
 - lib/zlight_csv/3.2/zlight_csv.so
 - lib/zlight_csv/3.3/zlight_csv.so
+- lib/zlight_csv/3.4/zlight_csv.so
+- lib/zlight_csv/4.0/zlight_csv.so
+- lib/zlight_csv/errors.rb
+- lib/zlight_csv/native.rb
 - lib/zlight_csv/version.rb
-homepage: https://rubygems.org/gems/zlight_csv
+homepage: https://github.com/codebyisaad/zlight
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://rubygems.org/gems/zlight_csv
-  documentation_uri: https://zaidanch.github.io/zlight-docs/
+  source_code_uri: https://github.com/codebyisaad/zlight
+  changelog_uri: https://github.com/codebyisaad/zlight/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/codebyisaad/zlight/issues
+  documentation_uri: https://codebyisaad.github.io/zlight-docs/
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
@@ -49,10 +78,10 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
   - - "<"
     - !ruby/object:Gem::Version
-      version: 3.4.dev
+      version: 4.1.dev
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="