reugenio/zcatpdf
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
zcatpdf/CLAUDE.md
reugenio 59c155331f docs: Update CLAUDE.md with complete project documentation 
- Full API documentation with examples
- Roadmap phases 1-5
- Architecture details
- Zig 0.15 compatibility notes
- Related projects table
- Next session tasks

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-08 17:36:13 +01:00

358 lines
8.9 KiB
Markdown
Raw Blame History

# zpdf - Generador PDF para Zig
> **Ultima actualizacion**: 2025-12-08
> **Lenguaje**: Zig 0.15.2
> **Estado**: v0.1 - Core funcional, en desarrollo activo
> **Inspiracion**: gofpdf (Go), fpdf (PHP)
## Descripcion del Proyecto
**zpdf** es una libreria pura Zig para generacion de documentos PDF. Sin dependencias externas, compila a un binario unico.
**Filosofia**:
- Zero dependencias (100% Zig puro)
- API simple y directa
- Enfocado en generacion de facturas/documentos comerciales
- Soporte para texto, tablas, imagenes y formas basicas
- Calidad open source (doc comments, codigo claro)
**Objetivo**: Ser el pilar para generar PDFs en Zig con codigo 100% propio, replicando funcionalidad de librerias maduras como gofpdf.
---
## Estado Actual del Proyecto
### Implementacion v0.1 (Core Funcional)
| Componente | Estado | Archivo |
|------------|--------|---------|
| **Document** | | |
| Document init/deinit | ✅ | `src/root.zig` |
| addPage (standard sizes) | ✅ | `src/root.zig` |
| addPageCustom | ✅ | `src/root.zig` |
| render() to buffer | ✅ | `src/root.zig` |
| saveToFile() | ✅ | `src/root.zig` |
| **Page** | | |
| Page init/deinit | ✅ | `src/root.zig` |
| setFont | ✅ | `src/root.zig` |
| drawText | ✅ | `src/root.zig` |
| setFillColor | ✅ | `src/root.zig` |
| setStrokeColor | ✅ | `src/root.zig` |
| setLineWidth | ✅ | `src/root.zig` |
| drawLine | ✅ | `src/root.zig` |
| drawRect | ✅ | `src/root.zig` |
| fillRect | ✅ | `src/root.zig` |
| drawFilledRect | ✅ | `src/root.zig` |
| **Types** | | |
| PageSize enum (A4, Letter, etc.) | ✅ | `src/root.zig` |
| Font enum (14 Type1 fonts) | ✅ | `src/root.zig` |
| Color struct (RGB) | ✅ | `src/root.zig` |
### Tests
| Categoria | Tests | Estado |
|-----------|-------|--------|
| Create empty document | 1 | ✅ |
| Add page | 1 | ✅ |
| Render minimal document | 1 | ✅ |
| Font names | 1 | ✅ |
| Color conversion | 1 | ✅ |
| Graphics operations | 1 | ✅ |
| **Total** | **6** | ✅ |
### Ejemplos
| Ejemplo | Descripcion | Estado |
|---------|-------------|--------|
| hello.zig | PDF minimo con texto y formas | ✅ |
| invoice.zig | Factura completa realista | ✅ |
---
## Roadmap
### Fase 1 - Core (COMPLETADO)
- [x] Estructura documento PDF 1.4
- [x] Paginas (A4, Letter, A3, A5, Legal, custom)
- [x] Texto basico (14 fuentes Type1 built-in)
- [x] Lineas y rectangulos
- [x] Colores RGB
- [x] Serializacion correcta
### Fase 2 - Texto Avanzado (PENDIENTE)
- [ ] Multiples fuentes en mismo documento
- [ ] Alineacion (izquierda, centro, derecha)
- [ ] Word wrap automatico
- [ ] Interlineado configurable
- [ ] Texto multilinea
### Fase 3 - Imagenes (PENDIENTE)
- [ ] JPEG embebido
- [ ] PNG embebido (con alpha)
- [ ] Escalado y posicionamiento
- [ ] Aspect ratio preservation
### Fase 4 - Utilidades (PENDIENTE)
- [ ] Helper para tablas
- [ ] Numeracion de paginas
- [ ] Headers/footers automaticos
- [ ] Margenes de pagina
- [ ] Links/URLs
### Fase 5 - Avanzado (FUTURO)
- [ ] Fuentes TTF embebidas
- [ ] Compresion de streams
- [ ] Metadatos documento (autor, titulo)
- [ ] Bookmarks/outline
- [ ] Forms (campos rellenables)
---
## Arquitectura
### Estructura de Archivos
```
zpdf/
├── CLAUDE.md # Este archivo - estado del proyecto
├── build.zig # Sistema de build
├── src/
│ └── root.zig # Libreria principal (todo en uno por ahora)
└── examples/
├── hello.zig # Ejemplo basico
└── invoice.zig # Factura ejemplo
```
### Formato PDF
Generamos PDF 1.4 (compatible con todos los lectores):
```
%PDF-1.4
%[binary marker]
1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj
2 0 obj << /Type /Pages /Kids [...] /Count N >> endobj
3 0 obj << /Type /Page ... >> endobj
4 0 obj << /Length ... >> stream ... endstream endobj
xref
0 N
trailer << /Size N /Root 1 0 R >>
startxref
...
%%EOF
```
### Fuentes Type1 Built-in
PDF incluye 14 fuentes estandar que no necesitan embeber:
- **Helvetica**: helvetica, helvetica_bold, helvetica_oblique, helvetica_bold_oblique
- **Times**: times_roman, times_bold, times_italic, times_bold_italic
- **Courier**: courier, courier_bold, courier_oblique, courier_bold_oblique
- **Otros**: symbol, zapf_dingbats
### Tamanos de Pagina
| Nombre | Puntos | Milimetros |
|--------|--------|------------|
| A4 | 595 x 842 | 210 x 297 |
| A3 | 842 x 1191 | 297 x 420 |
| A5 | 420 x 595 | 148 x 210 |
| Letter | 612 x 792 | 216 x 279 |
| Legal | 612 x 1008 | 216 x 356 |
---
## API Actual
### Crear Documento
```zig
const pdf = @import("zpdf");
var doc = pdf.Document.init(allocator);
defer doc.deinit();
```
### Agregar Paginas
```zig
// Tamano estandar
var page = try doc.addPage(.a4);
// Tamano personalizado (en puntos, 1pt = 1/72 inch)
var page = try doc.addPageCustom(500, 700);
```
### Texto
```zig
try page.setFont(.helvetica_bold, 24);
page.setFillColor(pdf.Color{ .r = 0, .g = 0, .b = 255 });
try page.drawText(50, 750, "Titulo");
try page.setFont(.times_roman, 12);
page.setFillColor(pdf.Color.black);
try page.drawText(50, 700, "Texto normal");
```
### Graficos
```zig
// Linea
try page.setLineWidth(1);
page.setStrokeColor(pdf.Color.gray);
try page.drawLine(50, 600, 500, 600);
// Rectangulo solo borde
try page.drawRect(50, 500, 200, 100);
// Rectangulo relleno
page.setFillColor(pdf.Color.light_gray);
try page.fillRect(50, 400, 200, 100);
// Rectangulo con borde y relleno
page.setFillColor(pdf.Color{ .r = 200, .g = 220, .b = 255 });
page.setStrokeColor(pdf.Color.blue);
try page.drawFilledRect(50, 300, 200, 100);
```
### Guardar
```zig
// A archivo
try doc.saveToFile("documento.pdf");
// A buffer (para enviar por red, etc.)
const data = try doc.render(allocator);
defer allocator.free(data);
```
### Colores Predefinidos
```zig
pdf.Color.black // (0, 0, 0)
pdf.Color.white // (255, 255, 255)
pdf.Color.red // (255, 0, 0)
pdf.Color.green // (0, 255, 0)
pdf.Color.blue // (0, 0, 255)
pdf.Color.gray // (128, 128, 128)
pdf.Color.light_gray // (200, 200, 200)
```
---
## Comandos
```bash
# Zig path
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
# Compilar
$ZIG build
# Tests
$ZIG build test
# Ejecutar ejemplos
$ZIG build hello && ./zig-out/bin/hello
$ZIG build invoice && ./zig-out/bin/invoice
```
---
## Equipo y Metodologia
### Normas de Trabajo Centralizadas
**IMPORTANTE**: Todas las normas de trabajo estan en:
```
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/
```
**Archivos clave a leer**:
- `LAST_UPDATE.md` - **LEER PRIMERO** - Cambios recientes en normas
- `NORMAS_TRABAJO_CONSENSUADAS.md` - Metodologia fundamental
- `QUICK_REFERENCE.md` - Cheat sheet rapido
### Estandares Zig Open Source (Seccion #24)
- **Claridad**: Codigo autoexplicativo, nombres descriptivos
- **Doc comments**: `///` en todas las funciones publicas
- **Idiomatico**: snake_case, error handling explicito
- **Sin magia**: Preferir codigo explicito sobre abstracciones complejas
### Control de Versiones
```bash
# Remote
git remote: git@git.reugenio.com:reugenio/zpdf.git
# Branches
main # Codigo estable
```
---
## Referencias
### gofpdf (Referencia principal)
- Repo: https://github.com/go-pdf/fpdf
- Objetivo: Replicar funcionalidad core en Zig
### PDF Reference
- PDF 1.4 Spec: https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.4.pdf
### Otros (Referencia)
- pdf-nano (Zig): https://github.com/GregorBudweiser/pdf-nano
---
## Historial de Desarrollo
### 2025-12-08 - v0.1 (Core Funcional)
- Estructura inicial del proyecto
- Document, Page, Color, Font, PageSize types
- Texto con 14 fuentes Type1 standard
- Graficos: lineas, rectangulos (stroke, fill, both)
- Colores RGB
- Serializacion PDF 1.4 correcta
- 6 tests unitarios pasando
- Ejemplos: hello.zig, invoice.zig funcionales
---
## Notas de Desarrollo
### Proxima Sesion
1. Implementar word wrap automatico para texto largo
2. Agregar helper para tablas (simplificar invoice.zig)
3. Soporte para imagenes JPEG
4. Alineacion de texto (center, right)
### Lecciones Aprendidas
- PDF es formato relativamente simple para generacion basica
- Content streams usan operadores PostScript-like
- Coordenadas PDF son desde bottom-left (Y aumenta hacia arriba)
- Las 14 fuentes Type1 estan garantizadas en todos los lectores PDF
### Zig 0.15 Notas
- `std.ArrayList` cambio a `std.ArrayListUnmanaged` con allocator explicito
- `writer()` ahora requiere allocator como parametro
- `toOwnedSlice()` requiere allocator
- `deinit()` requiere allocator
---
## Proyectos Relacionados
| Proyecto | Descripcion | Repo |
|----------|-------------|------|
| **zcatui** | TUI library (ratatui-style) | git.reugenio.com/reugenio/zcatui |
| **zsqlite** | SQLite wrapper | git.reugenio.com/reugenio/zsqlite |
| **zpdf** | PDF generator (este) | git.reugenio.com/reugenio/zpdf |
| **service-monitor** | Monitor de servicios | git.reugenio.com/reugenio/service-monitor |
---
**© zpdf - Generador PDF para Zig**
*2025-12-08 - En desarrollo activo*
Reference in a new issue View git blame Copy permalink