zlight_csv 0.5.1 → 0.6.0

data/ext/zlight_csv/src/writer.rs

@@ -1,268 +0,0 @@
-//! 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())
-    }
-}