pdf

PDF reading and writing library for Kit using pdfio

Files

Dependencies

No Kit package dependencies.

This package requires the native pdfio library at build and runtime. The Kit wrapper library is built as libkit_pdf.dylib on macOS or libkit_pdf.so on Linux.

Installation

kit add gitlab.com/kit-lang/packages/kit-pdf.git

System Requirements

On macOS:

brew install pkg-config libpng
tmpdir=$(mktemp -d)
git clone --recursive https://github.com/michaelrsweet/pdfio.git "$tmpdir/pdfio"
cd "$tmpdir/pdfio"
./configure --prefix=$(brew --prefix) --enable-shared CFLAGS="-arch $(uname -m)"
make
make install

If you already cloned PDFio without submodules, initialize them before rebuilding:

git -C pdfio submodule update --init --recursive
cd pdfio
./configure --prefix=$(brew --prefix) --enable-shared CFLAGS="-arch $(uname -m)"
make
make install

Usage

import Kit.PDF as Pdf

main = fn =>
  # Create a PDF
  match Pdf.create "/tmp/report.pdf" "Monthly Report" "Kit User"
    | Ok pdf ->
      match Pdf.add-page pdf Pdf.letter-width Pdf.letter-height
        | Ok page ->
          Pdf.add-text pdf page "Monthly Report" 72 720 24
          Pdf.add-text pdf page "Generated with kit-pdf" 72 690 12
        | Err e -> println ("Page error: " ++ e)
      Pdf.finalize pdf
      println "PDF created"
    | Err e -> println ("Error: " ++ e)

  # Read a PDF
  match Pdf.open "/tmp/report.pdf"
    | Ok pdf ->
      println ("Pages: " ++ (show (Pdf.page-count pdf)))

      match Pdf.get-title pdf
        | Some title -> println ("Title: " ++ title)
        | None -> println "No title"

      match Pdf.get-author pdf
        | Some author -> println ("Author: " ++ author)
        | None -> println "No author"

      Pdf.close pdf
    | Err e -> println ("Error: " ++ e)

main

Development

Local Native Build

Build and install the package wrapper locally:

kit install

This installs the package to ~/.kit/packages/@kit/pdf/ and builds the native wrapper library there.

The package manifest links both pdfio and kit_pdf. The kit install native build skips self-linking kit_pdf, while downstream Kit builds use it to resolve the wrapper symbols from libkit_pdf.

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running Parity

Run interpreter/compiler parity checks for the examples:

kit parity --no-spinner --failures-only

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/pdf/, making it available for import as Kit.PDF in other projects.

Troubleshooting

If kit install reports that pdfio is missing, verify that pkg-config can find it:

pkg-config --exists pdfio && pkg-config --libs pdfio

On macOS, PDFio must be installed into the same prefix used by the compiler and pkg-config, usually $(brew --prefix).

License

This package is released under the MIT License - see LICENSE for details.

PDFio is released under the Apache License 2.0.

Exported Functions & Types

open

Open a PDF file for reading.

Parameters:

Returns:

NonEmptyString -> Result Ptr String

match open "report.pdf"
  | Ok pdf ->
    println ("Pages: " ++ (show (page-count pdf)))
    close pdf
  | Err e -> println "Error: ${e}"

close

Close a PDF file and release resources.

Parameters:

Ptr -> Unit

close pdf

page-count

Get the number of pages in a PDF.

Parameters:

Returns:

Ptr -> Int

pages = page-count pdf
println ("Document has " ++ (show pages) ++ " pages")

get-title

Get the title from PDF metadata.

Parameters:

Returns:

Ptr -> Option String

match get-title pdf
  | Some t -> println ("Title: " ++ t)
  | None -> println "No title set"

get-author

Get the author from PDF metadata.

Parameters:

Returns:

Ptr -> Option String

match get-author pdf
  | Some a -> println ("Author: " ++ a)
  | None -> println "No author set"

get-version

Get the PDF version string.

Parameters:

Returns:

Ptr -> String

create

Create a new PDF file for writing.

Parameters:

Returns:

NonEmptyString -> String -> String -> Result Ptr String

match create "output.pdf" "My Report" "Kit User"
  | Ok pdf ->
    # ... add pages and content ...
    finalize pdf
  | Err e -> println "Error: ${e}"

add-page

Add a new page to a PDF being written.

Use letter-width/letter-height or a4-width/a4-height for standard page sizes. Dimensions are in points (72 points = 1 inch).

Parameters:

Returns:

Ptr -> PositiveInt -> PositiveInt -> Result Ptr String

match add-page pdf letter-width letter-height
  | Ok page -> add-text pdf page "Hello!" 72 720 12
  | Err e -> println "Error: ${e}"

add-text

Add text to a page at the given position.

Coordinates are measured from the bottom-left corner of the page in points (72 points = 1 inch).

Parameters:

Returns:

Ptr -> Ptr -> String -> Int -> Int -> PositiveInt -> Result Unit String

add-text pdf page "Hello, PDF!" 72 720 14

finalize

Finalize and close a PDF being written.

Must be called after all pages and content have been added.

Parameters:

Ptr -> Unit

finalize pdf

letter-width

US Letter page width in points (8.5 inches).

Int

letter-height

US Letter page height in points (11 inches).

Int

a4-width

A4 page width in points (210mm).

Int

a4-height

A4 page height in points (297mm).

Int