# FPDF for Rust
## What is it?
A PDF document generator with high level support for text, drawing and
images. It is written in _safe_ Rust.
> [!IMPORTANT]
> This project is in its very early development state and is thus
> prone to API changes. It is not recommended to build a product
> around this crate for the time being.
>
> If you encounter any issue or crashes using this crate, please open
> an issue and post a reproducible setup.
>
> If you have any wishes as to how the API can be improved and be made
> more "Rust"-idiomatic, please open an issue with that request.
## Features
- UTF-8 support
- Page format and margins
- Page header and footer management
- Automatic page break, line breaks and text justification
- Including of JPEG, PNG, GIF, TIFF and basic path-only SVG images
- Colors, gradients and alpha channel transparency
- Outline bookmarks
- Internal and external links
- TrueType, Type1 and encoding support
- Page compression
- Lines, Bézier curves, arcs, and ellipses
- Rotation, scaling, skewing, translation, and mirroring
- Clipping
- Document protection (RC4 is cryptographically broken)
- Layers
- Templates
- File attachements
- Embedded XML
- Embedded JavaScript
- No unsafe Rust in the entire code
The `fpdf` crate has its use of dependencies minimized. This avoids
compilation bloat for any project and its target binary size and
performance is more predictable.
`fpdf` explicitly supports UTF-8 TrueType fonts and "right-to-left"
languages.
Additional Features:
- Very basic HTML support (using html5gum)
## Installation
To use `fpdf` in your Rust project, just run the following command in your project directory:
```bash
$ cargo add fpdf
```
## Basic Example
Here is an example code shown for a very quick introduction into the
FPDF API. Take a look at the `examples/` folder for more examples.
### Hello World
```rust
use fpdf::{Fpdf, Pdf, Unit};
fn main() {
// Create a new Fpdf object instance
let mut pdf = Fpdf::default();
// Set the font to PDF's internal "Arial". Other alternatives would be:
// "Helvetica", "Times", "Symbol" or "Zapfdingbats"
pdf.set_font("Arial", "", Unit::pt(16.0));
// Add a new page to the PDF document (mandatory)
pdf.add_page();
// Print "Hello World!" message in an "imaginary" box of 100mm width
// and 10mm height. Draw no border, align the text to the left "L" and
// don't fill the background
pdf.multi_cell(Unit::mm(100.0), Unit::mm(10.0), "Hello World!", "", "L", false);
// Output the PDF file as "hello_world.pdf" onto the file system
pdf.output_file_and_close("hello_world.pdf").unwrap();
}
```
## Roadmap
The `fpdf` crate's goal is to become an established, general-use PDF
library, such as the original [FPDF for PHP](https://www.fpdf.org/).
The F stands for Free and thus this project is free to use any modify
however you like. A copyleft license is implemented to forbide the
commercial usage of this package for user's in need, like the inspired
[Golang FDPF](https://codeberg.org/go-pdf/fpdf) library has
experienced.
## Alternatives
If you want finer and more granular control over how your PDF file is
produced, consider using one of the alternative Rust crate's for
generating PDF files:
- [printpdf](https://github.com/fschutt/printpdf)
- [libharu_ng](https://github.com/bastibense/libharu_ng) (Requires
runtime dependencies)
## Errors
To ease the creation of PDF documents, the API mostly panics in case
of errors, to avoid unwrap calls in user's code. The error can be read
by the user directly to indicate its type. Methods are provided to
easily check if the current PDF instance has encountered an error, if
the user decides, they want this feature implemented.
## License
The `fpdf` crate is released under GPLv3 license. It is copyrighted by
Maik Steiger.