NAME

PDF::Builder - Facilitates the creation and modification of PDF files

SYNOPSIS

use PDF::Builder;

# Create a blank PDF file
$pdf = PDF::Builder->new();

# Open an existing PDF file
$pdf = PDF::Builder->open('some.pdf');

# Add a blank page
$page = $pdf->page();

# Retrieve an existing page
$page = $pdf->openpage($page_number);

# Set the page size
$page->mediabox('Letter');

# Add a built-in font to the PDF
$font = $pdf->corefont('Helvetica-Bold');

# Add an external TTF font to the PDF
$font = $pdf->ttfont('/path/to/font.ttf');

# Add some text to the page
$text = $page->text();
$text->font($font, 20);
$text->translate(200, 700);
$text->text('Hello World!');

# Save the PDF
$pdf->saveas('/path/to/new.pdf');

A NOTE ON STRINGS (CHARACTER TEXT)

Perl, and hence PDF::Builder, use strings that support the full range of Unicode characters. When importing strings into a Perl program, for example by reading text from a file, you must be aware of what their character encoding is. Single-byte encodings (default is 'latin1'), represented as bytes of value 0x00 through 0xFF (0..255), will produce different results if you do something that depends on the encoding, such as sorting, searching, or comparing any two non-ASCII characters. This also applies to any characters (text) hard coded into the Perl program.

You can always decode the text from external encoding (ASCII, UTF-8, Latin-3, etc.) into the Perl (internal) UTF-8 multibyte encoding. This uses one to four bytes to represent each character. See pragma utf8 and module Encode for details about decoding text. Note that only TrueType fonts (ttfont) can make direct use of UTF-8-encoded text. Other font types (core, T1, etc.) can only use single-byte encoded text. If your text is ASCII, Latin-1, or CP-1252, you can just leave the Perl strings as the default single-byte encoding.

Then, there is the matter of encoding the output to match up with available font character sets. You're not actually translating the text on output, but are telling the output system (and Reader) what encoding the output byte stream represents, and what character glyphs they should generate.

If you confine your text to plain ASCII (0x00 .. 0x7F byte values) or even Latin-1 or CP-1252 (0x00 .. 0xFF byte values), you can use default (non-UTF-8) Perl strings and use the default output encoding (WinAnsiEncoding), which is more-or-less Windows CP-1252 (a superset in turn, of ISO-8859-1 Latin-1). If your text uses any other characters, you will need to be aware of what encoding your text strings are (in the Perl string and for declaring output glyph generation). See corefont, psfont, and ttfont in "FONT METHODS" for additional information.

Some Internal Details

Some of the following may be a bit scary or confusing to beginners, so don't be afraid to skip over it until you're ready for it...

Perl (and PDF::Builder) internally use strings which are either single-byte (ISO-8859-1/Latin-1) or multibyte UTF-8 encoded (there is an internal flag marking the string as UTF-8 or not). If you work strictly in ASCII or Latin-1 or CP-1252 (each a superset of the previous), you should be OK in not doing anything special about your string encoding. You can just use the default Perl single byte strings (internally marked as not UTF-8) and the default output encoding (WinAnsiEncoding).

If you intend to use input from a variety of sources, you should consider decoding (converting) your text to UTF-8, which will provide an internally consistent representation (and your Perl code itself should be saved in UTF-8, in case you want to use any hard coded non-ASCII characters). In any string, non-ASCII characters (0x80 or higher) would be converted to the Perl UTF-8 internal representation, via $string = Encode::decode(MY_ENCODING, $input);. MY_ENCODING would be a string like 'latin1', 'cp-1252', 'utf8', etc. Similar capabilities are available for declaring a file to be in a certain encoding.

Be aware that if you use UTF-8 encoding for your text, that only TrueType font output (ttfont) can handle it directly. Corefont and Type1 output will require that the text will have to be converted back into a single-byte encoding (using Encode::encode), which may need to be declared with -encode (for corefont or psfont). If you have any characters not found in the selected single-byte encoding (but are found in the font itself), you will need to use automap to break up the font glyphs into 256 character planes, map such characters to 0x00 .. 0xFF in the appropriate plane, and switch between font planes as necessary.

Core and Type1 fonts (output) use the byte values in the string (single-byte encoding only!) and provide a byte-to-glyph mapping record for each plane. TrueType outputs a group of four hexadecimal digits representing the "CId" (character ID) of each character. The CId does not correspond to either the single-byte or UTF-8 internal representations of the characters.

The bottom line is that you need to know what the internal representation of your text is, so that the output routines can tell the PDF reader about it (via the PDF file). The text will not be translated upon output, but the PDF reader needs to know what the encoding in use is, so it knows what glyph to associate with each byte (or byte sequence).

By the way, it is recommended that you be using at least Perl 5.10 if you are going to be using any non-ASCII characters. Perl 5.8 may be a little unpredictable in handling such text.

LICENSE

This is free software, licensed under:

The GNU Lesser General Public License (LGPL) Version 2.1, February 1999

(The master copy of this license lives on the GNU website.)

Please see the LICENSE file in the distribution root for full details.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License, as published by the Free Software Foundation, either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

HISTORY

PDF::API2 was originally written by Alfred Reibenschuh, derived from Martin Hosken's Text::PDF via the Text::PDF::API wrapper. In 2009, Otto Hirr started the PDF::API3 fork, but it never went anywhere. In 2011, maintenance was taken over by Steve Simms. In 2017, PDF::Builder was forked by Phil M. Perry, who desired a more aggressive schedule of new features and bug fixes than Simms was providing.

At Simms's request, the name of the new offering was changed from PDF::API4 to PDF::Builder, to reduce the chance of confusion due to parallel development. Perry's intent is to keep all internal methods as upwardly compatible with PDF::API2 as possible, although it is likely that there will be some drift (incompatibilities) over time. At least initially, any program written based on PDF::API2 should be convertable to PDF::Builder simply by changing "API2" anywhere it occurs to "Builder". See the KNOWN_INCOMP known incompatibilities file for further information.

GENERIC METHODS

$pdf = PDF::Builder->new(%options)

Creates a new PDF object. If you will be saving it as a file and already know the filename, you can give the '-file' option to minimize possible memory requirements later on. The '-compress' option can be given to specify stream compression: default is 'flate', 'none' is no compression.

Example:

$pdf = PDF::Builder->new();
...
print $pdf->stringify();

$pdf = PDF::Builder->new(-compress => 'none');
# equivalent to $pdf->{'forcecompress'} = 'none'; (or older, 0)

$pdf = PDF::Builder->new();
...
$pdf->saveas('our/new.pdf');

$pdf = PDF::Builder->new(-file => 'our/new.pdf');
...
$pdf->save();

$pdf = PDF::Builder->open($pdf_file, %options)

$pdf = PDF::Builder->open($pdf_file)

Opens an existing PDF file. See new() for options.

Example:

$pdf = PDF::Builder->open('our/old.pdf');
...
$pdf->saveas('our/new.pdf');

$pdf = PDF::Builder->open('our/to/be/updated.pdf');
...
$pdf->update();

$pdf = PDF::Builder->open_scalar($pdf_string, %options)

$pdf = PDF::Builder->open_scalar($pdf_string)

Opens a PDF contained in a string. See new() for options.

Example:

# Read a PDF into a string, for the purpose of demonstration
open $fh, 'our/old.pdf' or die $@;
undef $/;  # Read the whole file at once
$pdf_string = <$fh>;

$pdf = PDF::Builder->open_scalar($pdf_string);
...
$pdf->saveas('our/new.pdf');

Note: Old name openScalar is deprecated! Convert your code to use open_scalar instead.

$pdf->preferences(%options)

Controls viewing preferences for the PDF.

Page Mode Options:

-fullscreen: Full-screen mode, with no menu bar, window controls, or any other window visible.
-thumbs: Thumbnail images visible.
-outlines: Document outline visible.

Page Layout Options:

-singlepage: Display one page at a time.
-onecolumn: Display the pages in one column.
-twocolumnleft: Display the pages in two columns, with oddnumbered pages on the left.
-twocolumnright: Display the pages in two columns, with oddnumbered pages on the right.

Viewer Options:

-hidetoolbar: Specifying whether to hide tool bars.
-hidemenubar: Specifying whether to hide menu bars.
-hidewindowui: Specifying whether to hide user interface elements.
-fitwindow: Specifying whether to resize the document's window to the size of the displayed page.
-centerwindow: Specifying whether to position the document's window in the center of the screen.
-displaytitle: Specifying whether the window's title bar should display the document title taken from the Title entry of the document information dictionary.
-afterfullscreenthumbs: Thumbnail images visible after Full-screen mode.
-afterfullscreenoutlines: Document outline visible after Full-screen mode.
-printscalingnone: Set the default print setting for page scaling to none.
-simplex: Print single-sided by default.
-duplexflipshortedge: Print duplex by default and flip on the short edge of the sheet.
-duplexfliplongedge: Print duplex by default and flip on the long edge of the sheet.

Initial Page Options:

-firstpage => [ $page, %options ]

Specifying the page (either a page number or a page object) to be displayed, plus one of the following options:

-fit => 1: Display the page designated by page, with its contents magnified just enough to fit the entire page within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the page within the window in the other dimension.
-fith => $top: Display the page designated by page, with the vertical coordinate top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of the page within the window.
-fitv => $left: Display the page designated by page, with the horizontal coordinate left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of the page within the window.
-fitr => [ $left, $bottom, $right, $top ]: Display the page designated by page, with its contents magnified just enough to fit the rectangle specified by the coordinates left, bottom, right, and top entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the rectangle within the window in the other dimension.
-fitb => 1: Display the page designated by page, with its contents magnified just enough to fit its bounding box entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the bounding box within the window in the other dimension.
-fitbh => $top: Display the page designated by page, with the vertical coordinate top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of its bounding box within the window.
-fitbv => $left: Display the page designated by page, with the horizontal coordinate left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of its bounding box within the window.
-xyz => [ $left, $top, $zoom ]: Display the page designated by page, with the coordinates (left, top) positioned at the top-left corner of the window and the contents of the page magnified by the factor zoom. A zero (0) value for any of the parameters left, top, or zoom specifies that the current value of that parameter is to be retained unchanged.

Example:

$pdf->preferences(
    -fullscreen => 1,
    -onecolumn => 1,
    -afterfullscreenoutlines => 1,
    -firstpage => [$page, -fit => 1],
);

$val = $pdf->default($parameter)

$pdf->default($parameter, $value)

Gets/sets the default value for a behavior of PDF::Builder.

Supported Parameters:

nounrotate: prohibits Builder from rotating imported/opened page to re-create a default pdf-context.
pageencaps: enables that Builder will add save/restore commands upon importing/opening pages to preserve graphics-state for modification.
copyannots: enables importing of annotations (*EXPERIMENTAL*).

$version = $pdf->version($new_version)

$version = $pdf->version()

Get/set the PDF version (e.g. 1.4)

$bool = $pdf->isEncrypted()

Checks if the previously opened PDF is encrypted.

%infohash = $pdf->info(%infohash)

Gets/sets the info structure of the document.

Example:

%h = $pdf->info(
    'Author'       => "Alfred Reibenschuh",
    'CreationDate' => "D:20020911000000+01'00'",
    'ModDate'      => "D:YYYYMMDDhhmmssOHH'mm'",
    'Creator'      => "fredos-script.pl",
    'Producer'     => "PDF::Builder",
    'Title'        => "some Publication",
    'Subject'      => "perl ?",
    'Keywords'     => "all good things are pdf"
);
print "Author: $h{'Author'}\n";

@metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)

Gets/sets the supported info-structure tags.

Example:

@attributes = $pdf->infoMetaAttributes;
print "Supported Attributes: @attr\n";

@attributes = $pdf->infoMetaAttributes('CustomField1');
print "Supported Attributes: @attributes\n";

$xml = $pdf->xmpMetadata($xml)

Gets/sets the XMP XML data stream.

Example:

$xml = $pdf->xmpMetadata();
print "PDFs Metadata reads: $xml\n";
$xml=<<EOT;
<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?>
<?adobe-xap-filters esc="CRLF"?>
<x:xmpmeta
  xmlns:x='adobe:ns:meta/'
  x:xmptk='XMP toolkit 2.9.1-14, framework 1.6'>
    <rdf:RDF
      xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
      xmlns:iX='http://ns.adobe.com/iX/1.0/'>
        <rdf:Description
          rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
          xmlns:pdf='http://ns.adobe.com/pdf/1.3/'
          pdf:Producer='Acrobat Distiller 6.0.1 for Macintosh'></rdf:Description>
        <rdf:Description
          rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
          xmlns:xap='http://ns.adobe.com/xap/1.0/'
          xap:CreateDate='2004-11-14T08:41:16Z'
          xap:ModifyDate='2004-11-14T16:38:50-08:00'
          xap:CreatorTool='FrameMaker 7.0'
          xap:MetadataDate='2004-11-14T16:38:50-08:00'></rdf:Description>
        <rdf:Description
          rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
          xmlns:xapMM='http://ns.adobe.com/xap/1.0/mm/'
          xapMM:DocumentID='uuid:919b9378-369c-11d9-a2b5-000393c97fd8'/></rdf:Description>
        <rdf:Description
          rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
          xmlns:dc='http://purl.org/dc/elements/1.1/'
          dc:format='application/pdf'>
            <dc:description>
              <rdf:Alt>
                <rdf:li xml:lang='x-default'>Adobe Portable Document Format (PDF)</rdf:li>
              </rdf:Alt>
            </dc:description>
            <dc:creator>
              <rdf:Seq>
                <rdf:li>Adobe Systems Incorporated</rdf:li>
              </rdf:Seq>
            </dc:creator>
            <dc:title>
              <rdf:Alt>
                <rdf:li xml:lang='x-default'>PDF Reference, version 1.6</rdf:li>
              </rdf:Alt>
            </dc:title>
        </rdf:Description>
    </rdf:RDF>
</x:xmpmeta>
<?xpacket end='w'?>
EOT

$xml = $pdf->xmpMetadata($xml);
print "PDF metadata now reads: $xml\n";

$pdf->pageLabel($index, $options)

Sets page label options.

Supported Options:

-style: Roman, roman, decimal, Alpha or alpha.
-start: Restart numbering at given number.
-prefix: Text prefix for numbering.

Example:

# Start with Roman Numerals
$pdf->pageLabel(0, {
    -style => 'roman',
});

# Switch to Arabic
$pdf->pageLabel(4, {
    -style => 'decimal',
});

# Numbering for Appendix A
$pdf->pageLabel(32, {
    -start => 1,
    -prefix => 'A-'
});

# Numbering for Appendix B
$pdf->pageLabel( 36, {
    -start => 1,
    -prefix => 'B-'
});

# Numbering for the Index
$pdf->pageLabel(40, {
    -style => 'Roman'
    -start => 1,
    -prefix => 'Index '
});

$pdf->finishobjects(@objects)

Force objects to be written to file if possible.

Example:

$pdf = PDF::Builder->new(-file => 'our/new.pdf');
...
$pdf->finishobjects($page, $gfx, $txt);
...
$pdf->save();

$pdf->update()

Saves a previously opened document.

Example:

$pdf = PDF::Builder->open('our/to/be/updated.pdf');
...
$pdf->update();

$pdf->saveas($file)

Save the document to $file and remove the object structure from memory.

Example:

$pdf = PDF::Builder->new();
...
$pdf->saveas('our/new.pdf');

$string = $pdf->stringify()

Return the document as a string and remove the object structure from memory.

Example:

$pdf = PDF::Builder->new();
...
print $pdf->stringify();

$pdf->end()

Remove the object structure from memory. PDF::Builder contains circular references, so this call is necessary in long-running processes to keep from running out of memory.

This will be called automatically when you save or stringify a PDF. You should only need to call it explicitly if you are reading PDF files and not writing them.

PAGE METHODS

$page = $pdf->page()

$page = $pdf->page($page_number)

Returns a new page object. By default, the page is added to the end of the document. If you include an existing page number, the new page will be inserted in that position, pushing existing pages back.

If $page_number is -1, the new page is inserted as the second-last page; if $page_number is 0, the new page is inserted as the last page.

Example:

$pdf = PDF::Builder->new();

# Add a page.  This becomes page 1.
$page = $pdf->page();

# Add a new first page.  $page becomes page 2.
$another_page = $pdf->page(1);

$page = $pdf->openpage($page_number)

Returns the PDF::Builder::Page object of page $page_number.

If $page_number is 0 or -1, it will return the last page in the document.

Example:

$pdf = PDF::Builder->open('our/99page.pdf');
$page = $pdf->openpage(1);   # returns the first page
$page = $pdf->openpage(99);  # returns the last page
$page = $pdf->openpage(-1);  # returns the last page
$page = $pdf->openpage(999); # returns undef

$xoform = $pdf->importPageIntoForm($source_pdf, $source_page_number)

Returns a Form XObject created by extracting the specified page from $source_pdf.

This is useful if you want to transpose the imported page somewhat differently onto a page (e.g. two-up, four-up, etc.).

If $source_page_number is 0 or -1, it will return the last page in the document.

Example:

$pdf = PDF::Builder->new();
$old = PDF::Builder->open('our/old.pdf');
$page = $pdf->page();
$gfx = $page->gfx();

# Import Page 2 from the old PDF
$xo = $pdf->importPageIntoForm($old, 2);

# Add it to the new PDF's first page at 1/2 scale
$gfx->formimage($xo, 0, 0, 0.5);

$pdf->saveas('our/new.pdf');

Note: You can only import a page from an existing PDF file.

$page = $pdf->import_page($source_pdf, $source_page_number, $target_page_number)

Imports a page from $source_pdf and adds it to the specified position in $pdf.

If $source_page_number or $target_page_number is 0 (the default) or -1, the last page in the document is used.

Note: If you pass a page object instead of a page number for $target_page_number, the contents of the page will be merged into the existing page.

Example:

$pdf = PDF::Builder->new();
$old = PDF::Builder->open('our/old.pdf');

# Add page 2 from the old PDF as page 1 of the new PDF
$page = $pdf->import_page($old, 2);

$pdf->saveas('our/new.pdf');

Note: You can only import a page from an existing PDF file.

Note: Old name importpage is deprecated! Convert your code to use import_page instead.

$count = $pdf->pages()

Returns the number of pages in the document.

$pdf->mediabox($name)

$pdf->mediabox($w,$h)

$pdf->mediabox($llx,$lly, $urx,$ury)

Sets the global mediabox.

Example:

$pdf = PDF::Builder->new();
$pdf->mediabox('A4');
...
$pdf->saveas('our/new.pdf');

$pdf = PDF::Builder->new();
$pdf->mediabox(595, 842);
...
$pdf->saveas('our/new.pdf');

$pdf = PDF::Builder->new;
$pdf->mediabox(0, 0, 595, 842);
...
$pdf->saveas('our/new.pdf');

$pdf->cropbox($name)

$pdf->cropbox($w,$h)

$pdf->cropbox($llx,$lly, $urx,$ury)

Sets the global cropbox.

$pdf->bleedbox($name)

$pdf->bleedbox($w,$h)

$pdf->bleedbox($llx,$lly, $urx,$ury)

Sets the global bleedbox.

$pdf->trimbox($name)

$pdf->trimbox($w,$h)

$pdf->trimbox($llx,$lly, $urx,$ury)

Sets the global trimbox.

$pdf->artbox($name)

$pdf->artbox($w,$h)

$pdf->artbox($llx,$lly, $urx,$ury)

Sets the global artbox.

FONT METHODS

@directories = PDF::Builder::addFontDirs($dir1, $dir2, ...)

Adds one or more directories to the search path for finding font files.

Returns the list of searched directories.

$font = $pdf->corefont($fontname, %options)

$font = $pdf->corefont($fontname)

Returns a new Adobe core font object.

Core fonts are limited to single byte encodings. You cannot use UTF-8 or other multibyte encodings with core fonts. The default encoding for the core fonts is WinAnsiEncoding (roughly the CP-1252 superset of ISO-8859-1). See the -encode option below to change this encoding. See PDF::Builder::Resource::Font automap method for information on accessing more than 256 glyphs in a font, using planes, although there is no guarantee that future changes to font files will permit consistent results.

Note that core fonts use fixed lists of expected glyphs, along with metrics such as their widths. This may not exactly match up with whatever local font file is used by the PDF reader. It's usually pretty close, but many cases have been found where the list of glyphs is different between the core fonts and various local font files, so be aware of this.

To allow UTF-8 text and extended glyph counts, you should consider replacing your use of core fonts with TrueType (.ttf) and OpenType (.otf) fonts. There are tools, such as FontForge, which can do a fairly good (though, not perfect) job of converting a Type1 font library to OTF.

Examples:

$font1 = $pdf->corefont('Times-Roman', -encode => 'latin2');
$font2 = $pdf->corefont('Times-Bold');
$font3 = $pdf->corefont('Helvetica');
$font4 = $pdf->corefont('ZapfDingbats');

Valid %options are:

-encode: Changes the encoding of the font from its default. Notice that the encoding (not the entire font's glyph list) is shown in a PDF object (record), listing 256 glyphs associated with this encoding (and that are available in this font).
-dokern: Enables kerning if data is available.

Note: even though these are called "core" fonts, they are not shipped with PDF::Builder, but are expected to be found on the machine with the PDF reader. Most core fonts are installed with a PDF reader, and thus are not coordinated with PDF::Builder. PDF::Builder does ship with core font metrics files (width, glyph names, etc.), but these cannot be guaranteed to be in sync with what the PDF reader has installed!

$font = $pdf->psfont($ps_file, %options)

$font = $pdf->psfont($ps_file)

Returns a new Adobe Type1 ("PostScript") font object.

PS (T1) fonts are limited to single byte encodings. You cannot use UTF-8 or other multibyte encodings with T1 fonts. The default encoding for the T1 fonts is WinAnsiEncoding (roughly the CP-1252 superset of ISO-8859-1). See the -encode option below to change this encoding. See PDF::Builder::Resource::Font automap method for information on accessing more than 256 glyphs in a font, using planes, although there is no guarantee that future changes to font files will permit consistent results. Note: many Type1 fonts are limited to 256 glyphs, but some are available with more than 256 glyphs. Still, a maximum of 256 at a time are usable.

psfont accepts both ASCII (.pfa) and binary (.pfb) Type1 glyph files. Font metrics can be supplied in either ASCII (.afm) or binary (.pfm) format, as can be seen in the examples given below. It is possible to use .pfa with .pfm and .pfb with .afm if that's what's available. The ASCII and binary files have the same content, just in different formats.

To allow UTF-8 text and extended glyph counts in one font, you should consider replacing your use of Type1 fonts with TrueType (.ttf) and OpenType (.otf) fonts. There are tools, such as FontForge, which can do a fairly good (though, not perfect) job of converting your font library to OTF.

Examples:

$font1 = $pdf->psfont('Times-Book.pfa', -afmfile => 'Times-Book.afm');
$font2 = $pdf->psfont('/fonts/Synest-FB.pfb', -pfmfile => '/fonts/Synest-FB.pfm');

Valid %options are:

-encode: Changes the encoding of the font from its default. Notice that the encoding (not the entire font's glyph list) is shown in a PDF object (record), listing 256 glyphs associated with this encoding (and that are available in this font).
-afmfile: Specifies the location of the ASCII font metrics file (.afm). It may be used with either an ASCII (.pfa) or binary (.pfb) glyph file.
-pfmfile: Specifies the location of the binary font metrics file (.pfm). It may be used with either an ASCII (.pfa) or binary (.pfb) glyph file.
-dokern: Enables kerning if data is available.

Note: these T1 (Type1) fonts are not shipped with PDF::Builder, but are expected to be found on the machine with the PDF reader. Most PDF readers do not install T1 fonts, and it is up to the user of the PDF reader to install the needed fonts.

$font = $pdf->ttfont($ttf_file, %options)

$font = $pdf->ttfont($ttf_file)

Returns a new TrueType (or OpenType) font object.

Warning: BaseEncoding is not set by default for TrueType fonts, so text in the PDF isn't searchable (by the PDF reader) unless a ToUnicode CMap is included. A ToUnicode CMap is included by default (-unicodemap set to 1) by PDF::Builder, but allows it to be disabled (for performance and file size reasons) by setting -unicodemap to 0. This will produce non-searchable text, which, besides being annoying to users, may prevent screen readers and other aids to disabled users from working correctly!

Examples:

$font1 = $pdf->ttfont('Times.ttf');
$font2 = $pdf->ttfont('Georgia.otf');

Valid %options are:

-encode

Changes the encoding of the font from its default (WinAnsiEncoding).

Note that for a single byte encoding (e.g., 'latin1'), you are limited to 256 characters defined for that encoding. 'automap' does not work with TrueType. If you want more characters than that, use 'utf8' encoding with a UTF-8 encoded text string.

-isocmap

Use the ISO Unicode Map instead of the default MS Unicode Map.

-unicodemap

If 1 (default), output ToUnicode CMap to permit text searches and screen readers. Set to 0 to save space by not including the ToUnicode CMap, but text searching and screen reading will not be possible.

-dokern

Enables kerning if data is available.

-noembed

Disables embedding of the font file.

$font = $pdf->cjkfont($cjkname, %options)

$font = $pdf->cjkfont($cjkname)

Returns a new CJK font object.

Examples:

$font = $pdf->cjkfont('korean');
$font = $pdf->cjkfont('traditional');

Valid %options are:

-encode: Changes the encoding of the font from its default.

$font = $pdf->synfont($basefont, %options)

$font = $pdf->synfont($basefont)

Returns a new synthetic font object. These are modifications to a core font, where the font may be replaced by a Type1 or Type3 PostScript font.

Warning: BaseEncoding is not set by default for these fonts, so text in the PDF isn't searchable (by the PDF reader) unless a ToUnicode CMap is included. A ToUnicode CMap is included by default (-unicodemap set to 1) by PDF::Builder, but allows it to be disabled (for performance and file size reasons) by setting -unicodemap to 0. This will produce non-searchable text, which, besides being annoying to users, may prevent screen readers and other aids to disabled users from working correctly!

Examples:

$cf  = $pdf->corefont('Times-Roman', -encode => 'latin1');
$sf  = $pdf->synfont($cf, -slant => 0.85);  # compressed 85%
$sfb = $pdf->synfont($cf, -bold => 1);      # embolden by 10em
$sfi = $pdf->synfont($cf, -oblique => -12); # italic at -12 degrees

Valid %options are:

-slant: Slant/expansion factor (0.1-0.9 = slant, 1.1+ = expansion).
-oblique: Italic angle (+/-)
-bold: Emboldening factor (0.1+, bold = 1, heavy = 2, ...)
-space: Additional character spacing in ems (0-1000)
-caps: 0 for normal text, 1 for small caps. Note that not all lower case letters appear to have small caps equivalents defined for them. These include, but are not limited to, 'n U+0149, fi ligature U+FB01, fl ligature U+FB02, German eszet (sharp s) U+00DF, and doubtless others. In such cases, you may want to consider replacing these ligatures with separate characters: '+n, f+i, f+l, s+s, etc.

$font = $pdf->bdfont($bdf_file, @options)

$font = $pdf->bdfont($bdf_file)

Returns a new BDF (bitmapped distribution format) font object, based on the specified Adobe BDF file.

$font = $pdf->unifont(@fontspecs, %options)

$font = $pdf->unifont(@fontspecs)

Returns a new uni-font object, based on the specified fonts and options.

BEWARE: This is not a true PDF-object, but a virtual/abstract font definition!

Valid %options are:

-encode: Changes the encoding of the font from its default.

IMAGE METHODS

$jpeg = $pdf->image_jpeg($file)

Imports and returns a new JPEG image object. $file may be either a filename or a filehandle.

$tiff = $pdf->image_tiff($file, %opts)

$tiff = $pdf->image_tiff($file)

Imports and returns a new TIFF image object. $file may be either a filename or a filehandle.

Note that the Graphics::TIFF support library does not currently permit a filehandle for $file.

PDF::Builder will use the Graphics::TIFF support library for TIFF functions, if it is available, unless explicitly told not to. Your code can test whether Graphics::TIFF is available by examining $tiff->usesLib().

= -1: Graphics::TIFF is installed, but your code has specified -nouseGT, to not use it. The old, pure Perl, code (buggy!) will be used instead, as if Graphics::TIFF was not installed.
= 0: Graphics::TIFF is not installed. Not all systems are able to successfully install this package, as it requires libtiff.a.
= 1: Graphics::TIFF is installed and is being used.

Options:

-nouseGT => 1: Do not use the Graphics::TIFF library, even if it's available. Normally you would want to use this library, but there may be cases where you don't, such as when you want to use a file handle instead of a name.
-silent => 1: Do not give the message that Graphics::TIFF is not installed. This message will be given only once, but you may want to suppress it, such as during t-tests.

$pnm = $pdf->image_pnm($file)

Imports and returns a new PNM image object. $file may be either a filename or a filehandle.

$png = $pdf->image_png($file)

Imports and returns a new PNG image object. $file may be either a filename or a filehandle.

$gif = $pdf->image_gif($file)

Imports and returns a new GIF image object. $file may be either a filename or a filehandle.

$gdf = $pdf->image_gd($gd_object, %options)

$gdf = $pdf->image_gd($gd_object)

Imports and returns a new image object from Image::GD.

Valid %options are:

-lossless => 1: Use lossless compression.

COLORSPACE METHODS

$cs = $pdf->colorspace_act($file)

Returns a new colorspace object based on an Adobe Color Table file.

See PDF::Builder::Resource::ColorSpace::Indexed::ACTFile for a reference to the file format's specification.

$cs = $pdf->colorspace_web()

Returns a new colorspace-object based on the web color palette.

$cs = $pdf->colorspace_hue()

Returns a new colorspace-object based on the hue color palette.

See PDF::Builder::Resource::ColorSpace::Indexed::Hue for an explanation.

$cs = $pdf->colorspace_separation($tint, $color)

Returns a new separation colorspace object based on the parameters.

$tint can be any valid ink identifier, including but not limited to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or 'Orange'.

$color must be a valid color specification limited to: '#rrggbb', '!hhssvv', '%ccmmyykk' or a "named color" (rgb).

The colorspace model will automatically be chosen based on the specified color.

$cs = $pdf->colorspace_devicen(\@tintCSx, $samples)

$cs = $pdf->colorspace_devicen(\@tintCSx)

Returns a new DeviceN colorspace object based on the parameters.

Example:

$cy = $pdf->colorspace_separation('Cyan',    '%f000');
$ma = $pdf->colorspace_separation('Magenta', '%0f00');
$ye = $pdf->colorspace_separation('Yellow',  '%00f0');
$bk = $pdf->colorspace_separation('Black',   '%000f');

$pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');

$dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk, $pms023 ] );

The colorspace model will automatically be chosen based on the first colorspace specified.

BARCODE METHODS

These are glue routines to the actual barcode rendering routines found elsewhere.

$bc = $pdf->xo_codabar(%options)
$bc = $pdf->xo_code128(%options)
$bc = $pdf->xo_2of5int(%options)
$bc = $pdf->xo_3of9(%options)
$bc = $pdf->xo_ean13(%options): Creates the specified barcode object as a form XObject.

OTHER METHODS

$xo = $pdf->xo_form(): Returns a new form XObject.
$egs = $pdf->egstate(): Returns a new extended graphics state object.
$obj = $pdf->pattern(%options)
$obj = $pdf->pattern(): Returns a new pattern object.
$obj = $pdf->shading(%options)
$obj = $pdf->shading(): Returns a new shading object.
$otls = $pdf->outlines(): Returns a new or existing outlines object.
$ndest = $pdf->named_destination(): Returns a new or existing named destination object.

KNOWN ISSUES

This module does not work with perl's -l command-line switch.

AUTHOR

PDF::API2 was originally written by Alfred Reibenschuh. See the HISTORY section for more information.

It was maintained by Steve Simms.

PDF::Builder is currently being maintained by Phil M. Perry.

Full source is on https://github.com/PhilterPaper/Perl-PDF-Builder

Bug reports are on https://github.com/PhilterPaper/Perl-PDF-Builder/issues?q=is%3Aissue+sort%3Aupdated-desc and general discussions are on http://www.catskilltech.com/forum/pdf-builder-general-discussions/. Please do not use the RT.cpan system to report issues, as it is not regularly monitored.

Release distribution is on CPAN: https://metacpan.org/pod/PDF::Builder

To install PDF::Builder, copy and paste the appropriate command in to your terminal.

cpanm

cpanm PDF::Builder

CPAN shell

perl -MCPAN -e shell
install PDF::Builder

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

A NOTE ON STRINGS (CHARACTER TEXT)

Some Internal Details

LICENSE

HISTORY

GENERIC METHODS

PAGE METHODS

FONT METHODS

IMAGE METHODS

COLORSPACE METHODS

BARCODE METHODS

OTHER METHODS

KNOWN ISSUES

AUTHOR

Module Install Instructions