reugenio/zcatpdf
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
zcatpdf/CLAUDE.md

236 lines
7.3 KiB
Markdown
Raw Blame History

# zcatpdf - Generador PDF para Zig
> **VCS:** jj (no git). Ver `/mnt/cello2/arno/re/recode/teamdocs/NORMAS_ESENCIALES.md`
> **Version**: v1.0 - RELEASE (FEATURE COMPLETE)
> **Ultima actualizacion**: 2025-12-09
> **Lenguaje**: Zig 0.15.2
> **Repositorio**: ssh://git@git.reugenio.com:2222/reugenio/zcatpdf.git
> **Forgejo Web**: https://git.reugenio.com/reugenio/zcatpdf
---
## Informacion para Nueva Conversacion
### Que es zcatpdf?
Libreria pura Zig para generacion de documentos PDF. Parte de la familia "zcat*" (zcatui, zcatgui, zcatpdf).
### Documentacion Disponible
| Archivo | Contenido |
|---------|-----------|
| `CLAUDE.md` | Este archivo - contexto del proyecto |
| `README.md` | **Manual de referencia completo** - API, ejemplos de codigo, tipos, archivos |
| `FUTURE_IMPROVEMENTS.md` | **Mejoras futuras detalladas** - TTF embedding, encryption integration, forms output, SVG avanzado |
| `docs/ARQUITECTURA_FPDF2.md` | Analisis de fpdf2 (Python) - arquitectura de referencia |
| `docs/ARQUITECTURA_ZPDF.md` | Diseno inicial del proyecto (historico) |
| `docs/PLAN_MAESTRO_ZPDF.md` | Plan original de implementacion (completado) |
### Normas del Equipo (teamdocs)
**Ubicacion**: `/mnt/cello2/arno/re/recode/teamdocs/`
Documentacion centralizada para todos los proyectos:
- `INFRASTRUCTURE/FORGEJO_GIT_SERVER.md` - Servidor git, tokens, API
- `INTEGRATION_GUIDE.md` - Guia de integracion de proyectos
- `NORMAS_PATRONES_DESARROLLO.md` - Patrones y normas de desarrollo
### Comandos Esenciales
```bash
# Zig path
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
# Compilar y testear
$ZIG build
$ZIG build test
# Ejecutar ejemplos
./zig-out/bin/hello
./zig-out/bin/invoice
./zig-out/bin/barcode_demo
# etc. (16 ejemplos en total)
```
### Reglas Clave para Este Proyecto
- Nombres en minusculas: `zcatpdf` (no ZcatPDF, no zCatPdf)
- Import: `@import("zcatpdf")`
- Doc comments (`///`) en funciones publicas
- Codigo idiomatico Zig (snake_case, error handling explicito)
---
## Estado del Proyecto
### FEATURE COMPLETE - v1.0
La libreria esta completa para uso en produccion. Todas las funcionalidades planificadas estan implementadas:
| Categoria | Funcionalidades |
|-----------|-----------------|
| **Documento** | PDF 1.4, metadatos, multiples paginas, compresion FlateDecode |
| **Texto** | drawText, cell, multiCell, word wrap, 14 fuentes Type1 |
| **Graficos** | Lineas, rectangulos, curvas Bezier, circulos, elipses, arcos |
| **Colores** | RGB, CMYK, Grayscale, colores predefinidos |
| **Imagenes** | JPEG, PNG (con alpha/transparencia) |
| **Tablas** | Table helper con headers, rows, footers |
| **Links** | URLs clickeables, links internos entre paginas |
| **Bookmarks** | Navegacion en sidebar del lector PDF |
| **Transformaciones** | Rotacion, escala, traslacion, skew |
| **Transparencia** | Fill y stroke opacity (0.0-1.0) |
| **Gradientes** | Lineales y radiales |
| **Barcodes** | Code128 (1D), QR Code (2D) |
| **TTF Fonts** | Parsing de TrueType (metricas, anchos de glyph) |
| **Security** | RC4 encryption module (40/128-bit) |
| **Forms** | TextField, CheckBox (structs, no output aun) |
| **SVG** | Import basico (shapes, paths) |
| **Templates** | Layouts reutilizables (invoice, letter) |
| **Markdown** | Texto con estilos (bold, italic, links, headings, lists) |
### Tests y Ejemplos
- **125+ tests** unitarios
- **16 ejemplos** funcionales en `examples/`
---
## Arquitectura de Archivos
```
zcatpdf/
├── CLAUDE.md # Este archivo
├── README.md # Manual de referencia completo
├── FUTURE_IMPROVEMENTS.md # Mejoras futuras detalladas
├── build.zig # Sistema de build
├── build.zig.zon # Dependencias (libdeflate)
├── src/
│ ├── root.zig # Exports publicos (@import("zcatpdf"))
│ ├── pdf.zig # Pdf struct - API principal
│ ├── page.zig # Page - dibujo, texto, transformaciones
│ ├── content_stream.zig # Operadores PDF de bajo nivel
│ ├── table.zig # Table helper
│ ├── pagination.zig # Numeros de pagina, headers, footers
│ ├── links.zig # Link types
│ ├── outline.zig # Bookmarks
│ ├── fonts/ # Type1 + TrueType
│ ├── graphics/ # Color, ExtGState, Gradient
│ ├── images/ # JPEG, PNG parsers
│ ├── barcodes/ # Code128, QR
│ ├── compression/ # libdeflate wrapper
│ ├── security/ # RC4, Encryption
│ ├── forms/ # TextField, CheckBox
│ ├── svg/ # SVG parser
│ ├── template/ # Template system
│ ├── markdown/ # Markdown renderer
│ ├── objects/ # PageSize, Orientation
│ └── output/ # PDF serialization
└── examples/ # 16 demos ejecutables
```
---
## Uso Rapido
```zig
const zcatpdf = @import("zcatpdf");
pub fn main() !void {
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer _ = gpa.deinit();
const allocator = gpa.allocator();
var pdf = zcatpdf.Pdf.init(allocator, .{});
defer pdf.deinit();
pdf.setTitle("Mi Documento");
var page = try pdf.addPage(.{});
try page.setFont(.helvetica_bold, 24);
try page.drawText(50, 750, "Hello, PDF!");
try pdf.save("output.pdf");
}
```
---
## Mejoras Futuras (No Criticas)
Ver `FUTURE_IMPROVEMENTS.md` para detalles completos:
1. **TTF Font Embedding** - Embeber TTF para renderizar texto (CIDFont Type 2)
2. **PDF Encryption Integration** - Integrar RC4 con OutputProducer
3. **AcroForms Output** - Generar campos de formulario en PDF final
4. **SVG Avanzado** - text, transforms, gradients en SVG
5. **Markdown Avanzado** - code blocks, tables, images
---
## Git
```bash
# Remote
origin: ssh://git@git.reugenio.com:2222/reugenio/zcatpdf.git
# Branch principal
main
# Comandos comunes
git status
git add -A && git commit -m "mensaje"
git push
```
**Nota**: El proyecto fue renombrado de `zpdf` a `zcatpdf` el 2025-12-09.
El repositorio en Forgejo y el remote local ya estan actualizados.
---
## Familia zcat*
| Proyecto | Descripcion |
|----------|-------------|
| **zcatui** | TUI library (terminal UI, como ratatui) |
| **zcatgui** | GUI library (immediate mode, SDL2 backend) |
| **zcatpdf** | PDF generation library |
Todos siguen las mismas convenciones:
- 100% Zig
- Minimas dependencias
- Nombres en minusculas
- Open source ready
---
## Referencias Externas
- [PDF Reference 1.4](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.4.pdf)
- [fpdf2 (Python)](https://github.com/py-pdf/fpdf2) - Inspiracion de la API
- [Zig Documentation](https://ziglang.org/documentation/master/)
---
**zcatpdf v1.0** - Generador PDF para Zig
*Feature Complete - 2025-12-09*
---
## CLAUDE CODE + ZLS (LSP)
Claude Code tiene integración LSP con zls (Zig Language Server).
**Plugin:** `$HOME/.claude/plugins/zls-lsp/`
**Operaciones disponibles:**
| Operación | Uso |
|-----------|-----|
| `goToDefinition` | Navegar a definición de símbolo |
| `findReferences` | Encontrar todas las referencias |
| `hover` | Info de tipo y documentación |
| `documentSymbol` | Símbolos del archivo actual |
| `incomingCalls` | Qué funciones llaman a ésta |
**Documentación:** `teamdocs/INFRASTRUCTURE/ZLS_LSP_CLAUDE_CODE.md`
Reference in a new issue View git blame Copy permalink