zlight_csv 0.1.0-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28a222377d00d9171e164df6c26f803ea6a13d319e90241cfefdadd726e4956c
+  data.tar.gz: e4af61736b17e550530aaf6808bc7bb033cdc59ab5d4868af494c9432aae4a89
+SHA512:
+  metadata.gz: 1d5e17f76cf164e89c24430cc33d7f8033f91e5ecf3d6b441c9841212c903de1c3033d2917e7377eebfc0057f8b4a429523a2b66429b8d0bab8c53618e3d9dcf
+  data.tar.gz: 5ffc39f9298d092d8de77aff18978668c32c5bd1de4b5f12461ebc25bc333ebdafcabbcd4cd12abeb31d393c21b2d7dae67f98d20a7a568c5f7a7245beeea811

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-XX-XX
+
+### Added
+
+- Initial release
+- `Zlight::Csv.parse` - Parse CSV strings with optional headers and numeric conversion
+- `Zlight::Csv.read` - Read and parse CSV files
+- `Zlight::Csv.foreach` - Iterate over CSV rows
+- `Zlight.parse` and `Zlight.read` convenience methods
+- Support for custom delimiters (`col_sep`)
+- Support for custom quote characters (`quote_char`)
+- Flexible record length support
+- Enum-based error handling with descriptive messages
+- Cross-platform native gem builds
+
+### Performance
+
+- Up to 10x faster than Ruby's standard CSV library
+- Efficient memory usage through Rust's zero-copy parsing

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Zaidan Chaudhary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,345 @@
+# ZLight
+
+[![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.
+
+## Features
+
+- **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
+
+## Benchmarks
+
+Parsing 100,000 rows with headers and numeric conversion:
+
+```
+                           user     system      total        real
+Ruby StdLib CSV:       1.49s
+ZLight (Rust):         0.05s
+```
+
+**~30x faster** than Ruby's standard CSV library!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'zlight_csv'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install 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)
+
+## 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 with headers (returns array of hashes with symbol keys)
+result = ZLight.parse(csv_data, headers: true)
+# => [{:name=>"Alice", :age=>"30", :city=>"New York"}, ...]
+
+# 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"}, ...]
+```
+
+### 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|
+  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
+
+### Prerequisites
+
+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
+
+# Run benchmarks
+bundle exec rake benchmark
+
+# Clean build artifacts
+bundle exec rake clean
+```
+
+## Publishing to RubyGems
+
+### Automated Release (Recommended)
+
+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 lib/zlight_csv/version.rb
+
+# 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
+```
+
+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
+```
+
+### Manual Release (Local Build)
+
+Build locally with Docker:
+
+```bash
+# Install cross-compilation tools
+gem install rake-compiler-dock
+
+# Build for a single platform (requires Docker on the host)
+rake dock:arm64-darwin
+
+# Build for ALL platforms
+rake dock:all
+
+# 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
+
+```
+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        # Version constant
+├── spec/                     # RSpec tests
+├── benchmark/                # Performance benchmarks
+├── Gemfile                   # Ruby dependencies
+├── Rakefile                  # Build tasks
+├── zlight_csv.gemspec        # Gem specification
+└── README.md
+```
+
+## API Compatibility with Ruby CSV
+
+| 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 | ❌ |
+
+## Error Handling
+
+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
+
+## 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
+```
+
+## 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

data/lib/zlight_csv/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ZLight
+  VERSION = '0.1.0'
+end

data/lib/zlight_csv.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'zlight_csv/version'
+
+# 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
+
+module ZLight
+  class Error < StandardError; end
+  class ParseError < Error; end
+  class EncodingError < Error; end
+
+  class << self
+    # Parses a CSV file and returns an array of hashes or arrays.
+    #
+    # @param path [String] Path to the CSV file
+    # @param options [Hash] Parsing options (same as .parse)
+    # @return [Array<Hash>, Array<Array>] Parsed CSV data
+    def read(path, **options)
+      parse(File.read(path, encoding: 'UTF-8'), **options)
+    end
+
+    # Iterates over each row in the CSV string.
+    #
+    # @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
+    def foreach(csv_string, **options, &block)
+      return to_enum(:foreach, csv_string, **options) unless block_given?
+
+      parse(csv_string, **options).each(&block)
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: zlight_csv
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux-musl
+authors:
+- Zaidan Chaudhary
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-17 00:00:00.000000000 Z
+dependencies: []
+description: |
+  ZLight is a blazing-fast CSV parser that provides a drop-in replacement
+  for Ruby's standard CSV library. Built with Rust for maximum performance,
+  it can parse CSV files up to 30x faster than the standard library while
+  maintaining full compatibility with common CSV.parse options.
+email:
+- zaidan@arxiron.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- 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/version.rb
+homepage: https://arxiron.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://arxiron.com
+  source_code_uri: https://arxiron.com
+  changelog_uri: https://arxiron.com/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.4.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.22
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: High-performance CSV parser for Ruby, powered by Rust
+test_files: []