zigtable

A fast, flexible table formatting library for Zig.

Features

• Multiple border styles: Unicode, ASCII, Markdown, Minimal, None
• Column alignment: Left, Center, Right
• Zero dependencies
• Direct rendering to output writer
• Simple API

Quick Start

const std = @import("std");
const zigtable = @import("zigtable");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    const columns = [_]zigtable.Column{
        .{ .name = "Name" },
        .{ .name = "Age" },
        .{ .name = "City" },
    };

    var table = zigtable.Table.init(allocator, &columns);
    defer table.deinit();

    try table.addRow(&[_][]const u8{ "Alice", "30", "NYC" });
    try table.addRow(&[_][]const u8{ "Bob", "25", "LA" });

    try table.render(std.io.getStdOut().writer());
}

Output:

┌───────┬─────┬──────┐
│ Name  │ Age │ City │
├───────┼─────┼──────┤
│ Alice │ 30  │ NYC  │
│ Bob   │ 25  │ LA   │
└───────┴─────┴──────┘

Examples

Border Styles

table.border_style = .unicode;  // ┌─┬─┐ (default)
table.border_style = .ascii;    // +-+-+
table.border_style = .markdown; // | - |
table.border_style = .minimal;  // just horizontal lines
table.border_style = .none;     // no borders

Column Alignment

const columns = [_]zigtable.Column{
    .{ .name = "Left", .alignment = .left },
    .{ .name = "Center", .alignment = .center },
    .{ .name = "Right", .alignment = .right },
};

Markdown Tables

var table = zigtable.Table.init(allocator, &columns);
table.border_style = .markdown;
// Perfect for README generation!

API Reference

Column

pub const Column = struct {
    name: []const u8,
    alignment: Alignment = .left,
    max_width: ?usize = null,
};

Table

pub fn init(allocator: Allocator, columns: []const Column) Table
pub fn deinit(self: *Table) void
pub fn addRow(self: *Table, row: []const []const u8) !void
pub fn render(self: *Table, writer: anytype) !void

Configuration

• border_style: BorderStyle - Visual style of table borders
• show_header: bool - Show/hide header row (default: true)
• padding: usize - Cell padding (default: 1)

Use Cases

• SQL Query Results: Display database query results in your CLI tool
• CLI Tables: Any tabular data in command-line applications
• Documentation: Generate Markdown tables programmatically
• Logs & Reports: Structured output for logging and reporting

Building & Testing

# Run tests
zig build test

# Run example
zig build run-example

# Run benchmark
zig build run-bench

Release & usage guidance

If you want to use zigtable from other repositories (for example zigcsv), you can publish it to GitHub and consume it in a few ways. Zig currently does not have a centralized package manager, so the recommended approaches are:

• Vendor or add as a Git submodule in the consuming repo:
  • git submodule add https://github.com/melihbirim/zigtable.git zigtable
  • Then import in your code as @import("zigtable/src/zigtable.zig").
• Use the Zig include path option when running/building:
  • zig run -I /path/to/repo-root zigcsv/examples/csv2table.zig -- zigcsv/examples/data/simple.csv (this will place zigtable under the module search path so imports like zigtable/src/... resolve).

Steps for releasing a GitHub tag:

1. Ensure tests pass: zig test.
2. Update CHANGELOG.md and version in docs or README.
3. Create a signed tag and push it: git tag -a v0.1.0 -m "Release v0.1.0" && git push origin v0.1.0.
4. Create a GitHub release for the tag and publish release notes.

If you'd like I can prepare a build.zig for the examples (or the top-level repo) that includes zigtable as a local include root to make running examples straightforward in CI or local dev.

Use as a submodule (example):

cd path/to/consuming/repo
git submodule add https://github.com/melihbirim/zigtable.git zigtable
git submodule update --init --recursive
zig run -I . other-project/examples/... -- args

Performance

On a typical modern machine (M1/M2 or recent x86_64):

• Small tables (3x3): ~2-3µs
• Medium tables (10x10): ~10-15µs
• Large tables (100x5): ~100-150µs

Minimal allocations during rendering - temporary buffers for column widths and headers, then direct writes to output.

Roadmap

• Column width calculation optimization
• Color support (ANSI codes)
• Row styling (bold, dim, etc.)
• Cell wrapping for long content
• CSV export
• Streaming mode for very large tables

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Author

Built for the sieswi project and the Zig community.