pdf

Kind	ffi-c
Capabilities	ffi
Categories	document-processing ffi
Keywords	pdf document pdfio report

PDF reading and writing library for Kit using pdfio

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`c/kit_pdf.c`	C FFI wrapper
`c/kit_pdf.h`	C header for FFI wrapper
`examples/basic.kit`	Basic usage example
`kit.toml`	Package manifest with metadata and dependencies
`src/pdf.kit`	Kit PDF - PDF reading and writing library
`tests/pdf.test.kit`	Tests for pdf

Dependencies

No Kit package dependencies.

Installation

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

System Requirements

Platform	Command
macOS	`brew install pdfio`
Ubuntu	Build from source: https://github.com/michaelrsweet/pdfio
Fedora	Build from source: https://github.com/michaelrsweet/pdfio

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

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 kit dev

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

kit dev

This will:

Format and check source files in src/
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.

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 -> NonEmptyString -> NonEmptyString -> 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