Skip to content
Message from the Author

Welcome to sheets.

Lua is powerful, lightweight, and fast—but its ecosystem still lags behind modern developer needs. This project is my first contribution toward changing that. I’m here to build serious tools that push Lua beyond scripting into real engineering.

— Shivam Sharma

sheets

Fast, Production-Ready CSV Processing for Lua

sheets is a high-performance, memory-efficient CSV and tabular data toolkit designed for production workloads. Built on top of the battle-tested libcsv C library, it combines native performance with an intuitive Python-inspired API.

Whether you're building data pipelines, ETL systems, analytics platforms, or processing large datasets in Lua, sheets provides a robust, efficient solution for structured tabular data.

Why sheets?

The Lua ecosystem has several CSV libraries, but most fall into one of three categories:

Limited features, simple implementations, but lacking essential functionality for production systems

Flexible and easy to modify, but significantly slower when processing large datasets

Missing modern data processing APIs or lacking consistent, intuitive interfaces

sheets solves all of these problems by combining:

  • Native C performance via libcsv for parsing and writing
  • Pythonic API inspired by Python's standard csv module
  • Complete feature set for real-world data workflows
  • Production-ready reliability and comprehensive testing

Key Features

  • High Performance — Parse and write CSV files with C-level speed...
  • Memory Efficient — Streaming architecture and optimized buffering...
  • Pythonic API — Familiar interfaces like Reader, Writer...
  • Flexible Dialects — Support for different CSV formats...
  • Cross-Platform — Works seamlessly on Linux, macOS, and Windows...
  • Production-Ready — Battle-tested on large datasets...

Quick Comparison

Feature sheets Python csv Pure Lua Libs
Parse Speed Native C Native C Script
Memory Usage 644 MB (1M rows) 1261 MB (1M rows) Variable
Python-style API Yes Yes Partial
DictReader/DictWriter Yes Yes Limited
Dialect Support Auto-detect Auto-detect No
Production Ready Yes Yes Limited

Use Cases

sheets is ideal for:

ETL workflows that require fast, reliable CSV ingestion and transformation

Processing large datasets for real-time or batch analytics

CSV handling in web applications, APIs, and data services

Preparing datasets for machine learning pipelines

Generating and parsing CSV reports at scale

Getting Started

1. Installation

1
luarocks install sheets

Or build from source. See Installation for detailed instructions.

2. Basic Reading

1
2
3
4
5
6
local csv = require("csv")

-- Simple row iteration
for row in csv.reader(io.open("data.csv")) do
    print(row[1], row[2], row[3])
end

3. Basic Writing

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
local csv = require("csv")

local f = io.open("output.csv", "w")
local writer = csv.writer(f)

writer:writerow({"name", "age", "city"})
writer:writerow({"Alice", 28, "New York"})
writer:writerow({"Bob", 35, "San Francisco"})

f:close()

4. Dictionary-Based Access

1
2
3
4
-- Access rows as dictionaries with header mapping
for record in csv.DictReader(io.open("data.csv")) do
    print(record.name, record.age)
end

Performance at Scale

Tested on a 1 million row, 20 column CSV file with mixed data types:

Metric sheets Python csv Ratio
Parse Time 9.2s 6.7s 1.4×
Memory Usage 644 MB 1261 MB 0.51×
Write Time 0.17s 0.59s 3.5×

Key Takeaways:

  • 2× better memory efficiency than Python
  • 3.5× faster writing performance
  • Competitive parsing with full C implementation backend
  • Scales efficiently to multi-million row

See Benchmarks for detailed performance analysis and additional test cases.

Architecture Overview

sheets uses a hybrid Lua + C architecture for optimal performance and usability:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
┌─────────────────────────────────────┐
│   Lua Layer (High-Level API)        │
│  Reader, Writer, DictReader, etc.   │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   C Layer (Libcsv Bindings)         │
│  Fast parsing, writing, buffering   │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   libcsv Backend                    │
│  Battle-tested, standards-compliant │
└─────────────────────────────────────┘

This design ensures:

  • Lua flexibility for API design and ease of use
  • C performance for I/O-bound operations
  • Modularity for easy extension and maintenance

See Design_Overview for deep technical details.

Core API Overview

1
2
3
4
5
6
local csv = require("csv")

-- Stream rows as arrays
for row in csv.reader(file) do
    print(#row, row[1])
end

1
2
3
4
5
local csv = require("csv")

local writer = csv.writer(file)
writer:writerow({"col1", "col2"})
writer:writerows({{1, 2}, {3, 4}})

1
2
3
4
5
6
local csv = require("csv")

-- Maps rows to dictionaries with headers
for record in csv.DictReader(file) do
    print(record.email, record.name)
end

1
2
3
4
5
local csv = require("csv")

local writer = csv.DictWriter(file, {"name", "age"})
writer:writeheader()
writer:writerow({name="Alice", age=28})

See api_red for complete documentation of all functions and parameters.

Documentation Structure

This documentation is organized into several sections:

📖 Documentation Guide

  • Installation — Setup, build from source, platform-specific notes

  • Quickstart — Hands-on tutorial with common patterns and examples

  • api_ref — Complete API documentation with parameters, return values, and examples

  • Architecture — Internal design, internals, and contribution guidelines

  • Benchmarks — Performance data, comparison with other libraries, profiling results

Project Philosophy

sheets is built on three core principles:

Performance

Native C implementation for I/O-bound operations. Stream processing architecture to minimize memory footprint.

Usability

Pythonic API familiar to developers across ecosystems. Clear, predictable behavior with sensible defaults.

Reliability

Production-tested on large real-world datasets. Comprehensive error handling and consistent cross-platform behavior.

Version & License

sheets v2.0.0

Licensed under the MIT License. See LICENSE file for details.

Get Started Now

Ready to start? Head over to the Installation guide to get sheets set up.

Already familiar with CSV libraries? Jump straight to the api_ref for complete documentation.

Have questions? Check out the Quickstart for common patterns and best practices.