Saitec.PdfDsl 2.0.1.4

Saitec.PdfDsl

Saitec.PdfDsl is a lightweight, extensible domain-specific language (DSL) designed to generate PDF documents using simple text instructions.
It is built on top of PdfSharp, offering a clean abstraction between what is described (the DSL) and how it is rendered (PdfSharp drawing engine).

This library is ideal for creating printable documents such as:

• Invoices
• Manifests
• Packing lists
• Labels
• Logistics reports
• Operational forms
• Structured documents driven from templates, files, or databases

✨ Features

✔ DSL-based PDF generation

Describe PDFs using text commands like:

TXT:10,10,Hello
LINE:10,20,200,20
IMG:path,10,30,50,50
TBL-START:10,40,2,2;40,80,40
CELL:Product A
CELL:10
TBL-END

✔ Extensible command system

You can register new commands via:

PdfCommandFactory.Register("MYCMD", (args, cfg) => new MyCustomCommand(args));

✔ Tables with rich features

• Column widths
• Row height calculation
• Multi-line text wrapping
• Column spanning
• Cell padding & spacing
• Background colors
• Captions
• Repeating header rows on every new page

✔ Pagination

Automatic page breaks when content or table rows overflow the page.

✔ Footer rendering (replayed on every page)

Footers use the same DSL commands, including support for templates:

FOOTER-TEMPLATE:#TEMPLATE Page #PAGE-NUMBER# of #TOTAL-PAGES#

📜 DSL Examples

Basic Text and Lines

SETTING:PAGESIZE:21,29.7
SETTING:MARGIN-TOP:10
SETTING:MARGIN-BOTTOM:10

TXT 10,10,Hello World
LINE 10,20,200,20
RIGHTTXT 10,200,20,Aligned to the right

Images

IMG C:/logos/mylogo.png,10,30,50,30

Simple Table

TBL-START:10,50,2,2;30,100,50

CELL:ID
CELL:Name
CELL:Qty

CELL:1
CELL:Product A
CELL:10

CELL:2
CELL:Product B
CELL:25

TBL-END

Table With Header Row (Repeated on Each Page)

TBL-START:10,50,2,2;40,80,40

TBL-HEADER-START
CELL:START:1:RGB:220,220,220;ID
CELL:CENTER:1:RGB:220,220,220;Description
CELL:END:1:RGB:220,220,220;Qty
TBL-HEADER-END

CELL:1
CELL:Product A
CELL:10

CELL:2
CELL:Product B
CELL:25

CELL:3
CELL:Product C
CELL:18

TBL-END

Footer Example

FOOTER-TEMPLATE:#TEMPLATE Page #PAGE-NUMBER# of #TOTAL-PAGES#
FOOTER-TEMPLATE:TXT:10,BOTTOM-10,Generated by Saitec.PdfDsl

📦 Installation

Install via NuGet:

dotnet add package Saitec.PdfDsl

Or NuGet Package Manager:

Install-Package Saitec.PdfDsl

🧩 Basic C# Usage

var basePath = Path.Combine(AppContext.BaseDirectory, "pdf-output");
var generator = new PdfFileGenerator(basePath);

var dslLines = new List<string> {
    "SETTING:PAGESIZE:21,29.7",
    "TXT 10,10,Hello from Saitec.PdfDsl",
    "LINE 10,20,200,20",
    "TBL-START:10,30,2,2;40,80,40",
    "TBL-HEADER-START",
    "CELL:START:1:RGB:220,220,220;ID",
    "CELL:START:2:RGB:220,220,220;Description",
    "TBL-HEADER-END",
    "CELL:1",
    "CELL:Item A",
    "CELL:10",
    "TBL-END"
};

var filePath = generator.GeneratePdf(dslLines);
Console.WriteLine($"PDF generated at: {filePath}");

🔧 Extending PdfDsl

To add a new command:

1. Create a class implementing IPdfCommand
2. Register it in PdfCommandFactory

Example:

public sealed class HelloCommand : IPdfCommand {
    public void Execute(PdfRenderContext ctx) {
        ctx.DrawString(20, 20, "Hello!", ctx.DefaultFont);
    }
}

// Registration
PdfCommandFactory.Register("HELLO", (args, cfg) => new HelloCommand());

Now DSL users can write:

HELLO

🧪 Testing

The DSL engine is fully testable:

✔ Parser tests

Verify that DSL lines produce correct IPdfCommand objects.

✔ Rendering tests

Use a mock/fake PdfRenderContext to verify:

• Coordinates
• Page creation
• Table splitting
• Header repetition
• Footer replaying

✔ Integration tests

Render real PDFs and compare:

• Page count
• Bounding boxes
• Table heights
• Line counts

🚀 Use Cases

• Logistics & warehouse documents
• Invoicing systems
• Government forms
• Label printers
• Multi-page reports
• Email-generated PDFs
• Custom templating engines

📘 License (MIT)

MIT License

Copyright (c) 2025 Saitec Ingeniería S.A.S., Colombia

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights  
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell     
copies of the Software, and to permit persons to whom the Software is        
furnished to do so, subject to the following conditions:                      

The above copyright notice and this permission notice shall be included in    
all copies or substantial portions of the Software.                           

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR   
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,      
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE   
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER        
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING       
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER          
DEALINGS IN THE SOFTWARE.                                                     

❤️ Contributing

Contributions are welcome!

You can:

• Submit pull requests
• Propose new DSL commands
• Improve documentation
• Create examples and templates
• Suggest improvements

⭐ Support

If you find Saitec.PdfDsl useful, please star the repository — it helps others discover the project!