PdfScriptCompiler 2.1.0

PdfScript— Plain-text → PDF Compiler (C#)

Zero-dependency C# PDF preprocessor. Write plain markup, get a real PDF binary. No Word, no LaTeX, no external packages — just .NET 8 and the PDF spec.

Installation

dotnet add package PdfScriptCompiler

Or via the NuGet Package Manager:

<PackageReference Include="PdfScriptCompiler" Version="2.1.0" />

What's new in v2

Quick start

dotnet run                            # writes demo.pdf
dotnet run -- example.pdfs            # compile a file
dotnet run -- --landscape report.pdfs # force landscape
dotnet run -- --userpwd open --readonly sensitive.pdfs
dotnet run -- -o out.pdf input.pdfs

PDFScript language

Document directives

@page        a4 | letter | a5 | legal | a3
@orientation landscape | portrait
@margin      top right bottom left   (or single value)
@title       "My Document"
@author      "Name"
@subject     "Topic"
@keywords    "pdf c# generator"
@encrypt     userpwd="open" ownerpwd="admin" permissions=all|readonly|none

Text

# H1   ## H2   ### H3   #### H4

Plain paragraph. Supports **bold**, *italic*, ***bold-italic***, `mono`,
and [color=#hex]colored[/color] inline spans.

->Centered<-          center-aligned paragraph
->Right aligned       right-aligned paragraph

---                   horizontal rule
<<<                   page break
.spacer 20            vertical gap in points
// comment line       ignored

Tables

.table [cols="spec"] [rowh=22] [fontsize=9] [padding=5]
       [headerbg=#hex] [headerfg=#hex] [evenbg=#hex] [bordercol=#hex]
| Header A | Header B | Header C |
| data     | data     | data     |
.end

Column spec syntax (space-separated):

Cell alignment — colon prefix/suffix:

| Left | :Center: | Right: |

Boxes

.box [bg=#eef3ff] [border=#aabbcc] [pad=10]
Any block content here — headings, paragraphs, rules.
.end

Raw PDF escape

.raw
BT /F1 12 Tf 50 700 Td (Hello from raw ops) Tj ET
.end

Encryption

@encrypt userpwd="open" ownerpwd="admin" permissions=all

Uses RC4-128 / Standard Security Rev 3 — compatible with Acrobat 5+ and all modern readers (Adobe, Foxit, Chrome PDF viewer, etc.).

Using as a library

Option A — NuGet (recommended)

dotnet add package PdfScriptCompiler

Option B — Project reference (monorepo / solution)

<ProjectReference Include="..\PdfScript\PdfScript.csproj" />

Compile from source text

using PdfScript;

byte[] pdf = PdfScriptCompiler.Compile(sourceString);
File.WriteAllBytes("output.pdf", pdf);

Compile a file

PdfScriptCompiler.CompileFile("report.pdfs");                   // → report.pdf
PdfScriptCompiler.CompileFile("report.pdfs", "/tmp/out.pdf");   // custom output

Write to a stream (ASP.NET Core, etc.)

Response.ContentType = "application/pdf";
PdfScriptCompiler.CompileToStream(source, Response.Body);

Fluent builder API

using PdfScript;
using PdfScript.Core;

byte[] pdf = new PdfDocumentBuilder()
    .SetTitle("Sales Report")
    .SetAuthor("Finance")
    .SetLandscape(true)
    .SetEncryption(EncryptionSettings.PasswordProtect("open123"))
    .AddHeading("Q1 2026 Sales", 1)
    .AddParagraph("Revenue grew by **42%** year-on-year.")
    .AddSpacer(10)
    .AddTable(t => t
        .AddColumn(ColSpec.Fixed(150))
        .AddColumn(ColSpec.Star())
        .AddColumn(ColSpec.Fixed(80))
        .SetHeader("Product", "Description", "Revenue")
        .AddRow("PDF Builder", "Annual license", "49,999")
        .AddRow("Support", "Priority SLA", "19,999")
    )
    .AddBox(
        inner => inner.AddParagraph("**Note:** Prices exclude GST."),
        background: PdfColor.FromHex("#fff8e0"),
        border:     PdfColor.FromHex("#f0c060")
    )
    .Build();

Architecture

Source text (.pdfs)
      │
      ▼  Core/Parser.cs
   DocumentNode tree
      │
      ▼  Emit/LayoutEngine.cs
   List<Page> of DrawCmd
      │
      ▼  Emit/PdfEmitter.cs  ←── Security/PdfEncryption.cs
   byte[] (valid PDF binary)

• Parser — text → IR (DocumentNode tree)
• LayoutEngine — IR → draw commands, auto page-break, column width resolution, cell wrapping
• PdfEmitter — draw commands → raw PDF binary (objects, xref, trailer)
• PdfEncryption — RC4-128 key derivation, /O, /U, /P computation, per-object stream encryption

Each pass is a separate stateless class. Easy to test and extend.

Extending

To add a new block type:

1. Add a record to Core/Nodes.cs
2. Parse it in Core/Parser.cs
3. Handle MeasureBlockList + ProcessNode in Emit/LayoutEngine.cs
4. Emit operators in Emit/PdfEmitter.cs → EmitCmd()
5. Add a builder method to PdfDocumentBuilder in Program.cs

Roadmap

• JPEG/PNG image embedding (XObject /Image)
• Multi-column layout
• Page numbers (@pagenumber token in header/footer)
• Headers and footers (repeated content per page)
• TTF/OTF font subsetting (non-Latin scripts)
• Hyperlinks (/URI annotation objects)
• AES-128 upgrade (PDF 1.6, requires AES-CBC)
• Proper Helvetica character width table (replace approximation)