zlight_csv 0.3.0-aarch64-linux → 0.5.1-aarch64-linux

data/ext/zlight_csv/src/writer.rs

@@ -0,0 +1,268 @@
+//! CSV writer: converts Ruby data structures into CSV strings.
+//!
+//! Mirrors the reader's option/error patterns. The heavy lifting is done by
+//! `csv::Writer`, with field values converted from Ruby objects following the
+//! same semantics as Ruby's stdlib `CSV` (i.e. `nil` becomes an empty field and
+//! every other value is stringified with `#to_s`).
+
+use csv::{QuoteStyle, WriterBuilder};
+use magnus::{
+    prelude::*,
+    scan_args::{get_kwargs, scan_args},
+    Error as MagnusError, RArray, RHash, RString, Ruby, Value,
+};
+
+use crate::error::ZlightError;
+use crate::options::single_byte;
+
+/// A CSV writer backed by an in-memory byte buffer.
+type ByteWriter = csv::Writer<Vec<u8>>;
+
+/// Configuration options for CSV writing.
+#[derive(Debug, Clone, Copy)]
+pub struct WriteOptions {
+    /// Whether to write a header row (only applicable for hash input).
+    pub write_headers: bool,
+    /// Field delimiter byte (defaults to comma).
+    pub delimiter: u8,
+    /// Quote byte (defaults to double quote).
+    pub quote: u8,
+    /// Whether to force quoting of every field.
+    pub force_quotes: bool,
+}
+
+impl Default for WriteOptions {
+    #[inline]
+    fn default() -> Self {
+        Self {
+            write_headers: true,
+            delimiter: b',',
+            quote: b'"',
+            force_quotes: false,
+        }
+    }
+}
+
+impl WriteOptions {
+    /// Extracts the `rows` argument and write options from Ruby arguments.
+    fn from_ruby_args(args: &[Value]) -> Result<(RArray, Self), ZlightError> {
+        let parsed = scan_args::<(RArray,), (), (), (), RHash, ()>(args)
+            .map_err(|_| ZlightError::MissingArgument("rows (expected an Array)"))?;
+
+        let (rows,) = parsed.required;
+
+        let kw = get_kwargs::<
+            _,
+            (),
+            (Option<bool>, Option<RString>, Option<RString>, Option<bool>),
+            (),
+        >(
+            parsed.keywords,
+            &[],
+            &["headers", "col_sep", "quote_char", "force_quotes"],
+        )
+        .map_err(|e| ZlightError::InvalidOption {
+            key: "keywords",
+            expected: "valid keyword arguments",
+            actual: e.to_string(),
+        })?;
+
+        let (headers_opt, col_sep_opt, quote_opt, force_quotes_opt) = kw.optional;
+
+        let delimiter = single_byte(col_sep_opt, "col_sep")?.unwrap_or(b',');
+        let quote = single_byte(quote_opt, "quote_char")?.unwrap_or(b'"');
+
+        Ok((
+            rows,
+            WriteOptions {
+                write_headers: headers_opt.unwrap_or(true),
+                delimiter,
+                quote,
+                force_quotes: force_quotes_opt.unwrap_or(false),
+            },
+        ))
+    }
+}
+
+/// Builds a CSV writer with the given options.
+#[inline]
+fn build_writer(options: &WriteOptions) -> ByteWriter {
+    let mut builder = WriterBuilder::new();
+    builder
+        .delimiter(options.delimiter)
+        .quote(options.quote)
+        // Rows may legitimately have differing field counts (e.g. hashes with
+        // missing keys, or jagged arrays), so never enforce a uniform width.
+        .flexible(true);
+
+    if options.force_quotes {
+        builder.quote_style(QuoteStyle::Always);
+    }
+
+    builder.from_writer(Vec::new())
+}
+
+/// Converts a csv error into a Ruby exception.
+#[inline]
+fn csv_err(e: csv::Error) -> MagnusError {
+    ZlightError::from(e).into()
+}
+
+/// Returns a UTF-8 encoded Ruby string for an arbitrary field value.
+///
+/// Semantics mirror Ruby's stdlib CSV writer:
+/// * `nil` becomes an empty field.
+/// * Strings are used as-is (transcoded to UTF-8 when needed).
+/// * Everything else is stringified via `#to_s`.
+#[inline]
+fn field_string(ruby: &Ruby, value: Value) -> Result<RString, MagnusError> {
+    if value.is_nil() {
+        return Ok(ruby.str_new(""));
+    }
+
+    let string = match RString::from_value(value) {
+        Some(s) => s,
+        None => value.funcall("to_s", ())?,
+    };
+
+    if string.is_utf8_compatible_encoding() {
+        Ok(string)
+    } else {
+        // Transcode foreign encodings (e.g. ISO-8859-1, Shift_JIS) so the
+        // resulting buffer is always valid UTF-8.
+        string.conv_enc(ruby.utf8_encoding())
+    }
+}
+
+/// Writes a single field value to the writer.
+#[inline]
+fn write_field(ruby: &Ruby, writer: &mut ByteWriter, value: Value) -> Result<(), MagnusError> {
+    let string = field_string(ruby, value)?;
+    // SAFETY: `string` is held on the stack and no Ruby allocation happens between
+    // taking the slice and handing it to the writer, so it cannot be collected.
+    let bytes = unsafe { string.as_slice() };
+    writer.write_field(bytes).map_err(csv_err)
+}
+
+/// Terminates the current record (row).
+#[inline]
+fn end_record(writer: &mut ByteWriter) -> Result<(), MagnusError> {
+    writer.write_record(None::<&[u8]>).map_err(csv_err)
+}
+
+/// Finalizes the writer and returns the buffer as a UTF-8 Ruby string.
+#[inline]
+fn finish(ruby: &Ruby, writer: ByteWriter) -> Result<RString, MagnusError> {
+    let data = writer
+        .into_inner()
+        .map_err(|e| MagnusError::from(ZlightError::Io(e.into_error())))?;
+    Ok(ruby.enc_str_new(&data, ruby.utf8_encoding()))
+}
+
+/// Coerces a row value into an `RArray`, raising a clear error otherwise.
+#[inline]
+fn expect_array(value: Value) -> Result<RArray, MagnusError> {
+    RArray::from_value(value).ok_or_else(|| {
+        MagnusError::from(ZlightError::InvalidOption {
+            key: "rows",
+            expected: "an Array of Arrays",
+            actual: format!("element of type {}", value.class()),
+        })
+    })
+}
+
+/// Coerces a row value into an `RHash`, raising a clear error otherwise.
+#[inline]
+fn expect_hash(value: Value) -> Result<RHash, MagnusError> {
+    RHash::from_value(value).ok_or_else(|| {
+        MagnusError::from(ZlightError::InvalidOption {
+            key: "rows",
+            expected: "an Array of Hashes",
+            actual: format!("element of type {}", value.class()),
+        })
+    })
+}
+
+/// Generates CSV from an array of arrays (positional fields, no header row).
+fn generate_from_arrays(
+    ruby: &Ruby,
+    rows: RArray,
+    options: &WriteOptions,
+) -> Result<RString, MagnusError> {
+    let mut writer = build_writer(options);
+
+    for i in 0..rows.len() {
+        let row = expect_array(rows.entry(i as isize)?)?;
+        for j in 0..row.len() {
+            write_field(ruby, &mut writer, row.entry(j as isize)?)?;
+        }
+        end_record(&mut writer)?;
+    }
+
+    finish(ruby, writer)
+}
+
+/// Generates CSV from an array of hashes, using the first hash's keys as the
+/// column order. Missing keys in later rows are written as empty fields.
+fn generate_from_hashes(
+    ruby: &Ruby,
+    rows: RArray,
+    options: &WriteOptions,
+) -> Result<RString, MagnusError> {
+    let mut writer = build_writer(options);
+
+    // Column order is defined by the keys of the first hash.
+    let first_hash = expect_hash(rows.entry(0)?)?;
+    let keys: RArray = first_hash.funcall("keys", ())?;
+    let key_count = keys.len();
+    let header_keys: Vec<Value> = (0..key_count)
+        .map(|i| keys.entry(i as isize))
+        .collect::<Result<_, _>>()?;
+
+    // Emit the header row from the keys (skipped for keyless/empty hashes).
+    if options.write_headers && !header_keys.is_empty() {
+        for &key in &header_keys {
+            write_field(ruby, &mut writer, key)?;
+        }
+        end_record(&mut writer)?;
+    }
+
+    for i in 0..rows.len() {
+        let hash = expect_hash(rows.entry(i as isize)?)?;
+        for &key in &header_keys {
+            let value = hash.get(key).unwrap_or_else(|| ruby.qnil().as_value());
+            write_field(ruby, &mut writer, value)?;
+        }
+        end_record(&mut writer)?;
+    }
+
+    finish(ruby, writer)
+}
+
+/// Ruby: `ZLight.generate(rows, **options) -> String`.
+///
+/// Dispatches on the type of the first row: an array of hashes produces a CSV
+/// with a header row (unless `headers: false`); an array of arrays produces a
+/// headerless CSV.
+pub fn generate(ruby: &Ruby, args: &[Value]) -> Result<RString, MagnusError> {
+    let (rows, options) = WriteOptions::from_ruby_args(args)?;
+
+    if rows.is_empty() {
+        return Ok(ruby.str_new(""));
+    }
+
+    let first = rows.entry(0)?;
+
+    if RHash::from_value(first).is_some() {
+        generate_from_hashes(ruby, rows, &options)
+    } else if RArray::from_value(first).is_some() {
+        generate_from_arrays(ruby, rows, &options)
+    } else {
+        Err(ZlightError::InvalidOption {
+            key: "rows",
+            expected: "an Array of Arrays or an Array of Hashes",
+            actual: format!("an Array whose first element is {}", first.class()),
+        }
+        .into())
+    }
+}

data/lib/zlight_csv.rb

@@ -13,7 +13,7 @@ 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.
+# up to 40x faster than the standard library.
 #
 # @example Basic parsing with headers
 #   result = ZLight.parse("name,age\nAlice,30\nBob,25")
@@ -40,7 +40,7 @@ end
 #   reader.lazy.select { |row| row[:age] > 30 }.first(10)
 #   reader.close
 #
-# @see https://github.com/zaidanch/zlight
+# @see https://github.com/codebyisaad/zlight
 module ZLight
   # Base error class for all ZLight errors
   class Error < StandardError; end
@@ -91,6 +91,39 @@ module ZLight
   # @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.
+
   # StreamReader is defined in the Rust extension.
   # It provides lazy/streaming CSV parsing for large files.
   #
@@ -133,6 +166,38 @@ module ZLight
       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
+    #
+    # @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")
+    #
+    # @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.
@@ -169,10 +234,10 @@ module ZLight
     #              .map { |row| row[:name] }
     #
     # @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.
@@ -196,8 +261,9 @@ module ZLight
     # @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
+    # @raise [IOError] If the file does not exist or cannot be read
+    # @raise [ZLight::StreamClosedError] If a row is read after the reader
+    #   has been closed
     #
     # @example Process a large file row by row
     #   ZLight.open("users.csv") do |reader|

metadata

@@ -1,18 +1,33 @@
 --- !ruby/object:Gem::Specification
 name: zlight_csv
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.1
 platform: aarch64-linux
 authors:
 - Zaidan Chaudhary
+- Saad Chaudhary
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-21 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
@@ -28,18 +43,30 @@ files:
 - LICENSE
 - README.md
 - VERSION
+- ext/zlight_csv/Cargo.toml
+- ext/zlight_csv/extconf.rb
+- ext/zlight_csv/src/converter.rs
+- ext/zlight_csv/src/error.rs
+- ext/zlight_csv/src/lib.rs
+- ext/zlight_csv/src/options.rs
+- ext/zlight_csv/src/parser.rs
+- ext/zlight_csv/src/stream.rs
+- ext/zlight_csv/src/writer.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/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 +76,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:
   - - ">="