zcatpdf/CLAUDE.md

zpdf - Generador PDF para Zig

Fecha creación: 2025-12-08 Versión Zig: 0.15.2 Estado: En desarrollo inicial

Descripción del Proyecto

Librería pura Zig para generación de documentos PDF. Sin dependencias externas, compila a un binario único.

Filosofía:

• Zero dependencias (100% Zig)
• API simple y directa
• Enfocado en generación de facturas/documentos comerciales
• Soporte para texto, tablas, imágenes y formas básicas

Arquitectura

zpdf/
├── CLAUDE.md           # Este archivo
├── build.zig           # Sistema de build
├── src/
│   ├── root.zig        # Exports públicos
│   ├── document.zig    # Documento PDF principal
│   ├── page.zig        # Páginas
│   ├── stream.zig      # Content streams
│   ├── text.zig        # Renderizado de texto
│   ├── graphics.zig    # Líneas, rectángulos, etc.
│   ├── image.zig       # Imágenes embebidas
│   ├── fonts.zig       # Fuentes Type1 básicas
│   └── writer.zig      # Serialización PDF
└── examples/
    ├── hello.zig       # PDF mínimo
    └── invoice.zig     # Factura ejemplo

Formato PDF

Usamos PDF 1.4 (compatible con todos los lectores). Estructura básica:

%PDF-1.4
1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj
2 0 obj << /Type /Pages /Kids [3 0 R] /Count 1 >> endobj
3 0 obj << /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R >> endobj
4 0 obj << /Length ... >> stream ... endstream endobj
xref
0 5
0000000000 65535 f
...
trailer << /Size 5 /Root 1 0 R >>
startxref
...
%%EOF

API Objetivo

const std = @import("std");
const pdf = @import("zpdf");

pub fn main() !void {
    var allocator = std.heap.page_allocator;

    var doc = pdf.Document.init(allocator);
    defer doc.deinit();

    var page = try doc.addPage(.a4);

    // Texto
    try page.setFont(.helvetica_bold, 24);
    try page.drawText(50, 750, "Factura #001");

    try page.setFont(.helvetica, 12);
    try page.drawText(50, 700, "Cliente: Empresa S.L.");

    // Línea
    try page.setLineWidth(0.5);
    try page.drawLine(50, 690, 550, 690);

    // Rectángulo
    try page.setFillColor(.{ .r = 240, .g = 240, .b = 240 });
    try page.fillRect(50, 600, 500, 20);

    // Tabla (helper)
    try page.drawTable(.{
        .x = 50,
        .y = 580,
        .columns = &.{ 200, 100, 100, 100 },
        .headers = &.{ "Descripción", "Cantidad", "Precio", "Total" },
        .rows = &.{
            &.{ "Producto A", "2", "10.00", "20.00" },
            &.{ "Producto B", "1", "25.00", "25.00" },
        },
    });

    // Guardar
    try doc.save("factura.pdf");
}

Funcionalidades Planificadas

Fase 1 - Core (Actual)

• Estructura documento PDF 1.4
• Páginas (A4, Letter, custom)
• Texto básico (fuentes Type1 built-in)
• Líneas y rectángulos
• Serialización correcta

Fase 2 - Texto Avanzado

• Múltiples fuentes en mismo documento
• Colores (RGB, CMYK, grayscale)
• Alineación (izquierda, centro, derecha)
• Word wrap automático

Fase 3 - Imágenes

• JPEG embebido
• PNG embebido (con alpha)
• Escalado y posicionamiento

Fase 4 - Utilidades

• Helper para tablas
• Numeración de páginas
• Headers/footers

Fuentes Type1 Built-in

PDF incluye 14 fuentes estándar que no necesitan embeber:

• Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique
• Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
• Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique
• Symbol, ZapfDingbats

Tamaños de Página

pub const PageSize = enum {
    a4,      // 595 x 842 points (210 x 297 mm)
    letter,  // 612 x 792 points (8.5 x 11 inches)
    legal,   // 612 x 1008 points
    a3,      // 842 x 1191 points
    a5,      // 420 x 595 points
};

Referencias

• PDF Reference 1.4
• pdf-nano (Zig) - Referencia minimalista

---

Equipo y Metodología

Normas de Trabajo

IMPORTANTE: Todas las normas de trabajo están en:

/mnt/cello2/arno/re/recode/TEAM_STANDARDS/

Control de Versiones

# Remote
git remote: git@git.reugenio.com:reugenio/zpdf.git

# Branches
main        # Código estable
develop     # Desarrollo activo

Zig Path

ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig

---

Notas de Desarrollo

Se irán añadiendo conforme avance el proyecto