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');

SOME SPECIAL NOTES

SOFTWARE DEVELOPMENT KIT

There are four levels of involvement with PDF::Builder. Depending on what you want to do, different kinds of installs are recommended. See PDF::Builder::Docs section Software Development Kit for suggestions.

STRINGS (CHARACTER TEXT)

There are some things you should know about character encoding (for text), before you dive in to coding. Please go to PDF::Builder::Docs Strings and have a read.

PDF VERSIONS SUPPORTED

PDF::Builder is mostly PDF 1.4-compliant, but there are complications you should be aware of. Please read PDF::Builder::Docs section PDF Versions Supported for details.

SUPPORTED PERL VERSIONS

PDF::Builder intends to support all major Perl versions that were released in the past six years, plus one, in order to continue working for the life of most long-term-stable (LTS) server distributions. See the https://www.cpan.org/src/ table First release in each branch of Perl x.xxxx0 "Major" release dates.

For example, a version of PDF::Builder released on 2018-06-05 would support the last major version of Perl released on or after 2012-06-05 (5.18), and then one before that, which would be 5.16. Alternatively, the last major version of Perl released before 2012-06-05 is 5.16.

The intent is to avoid expending unnecessary effort in supporting very old (obsolete) versions of Perl. If you need to use this module on a server with an extremely out-of-date version of Perl, consider using either plenv or Perlbrew to run a newer version of Perl without needing admin privileges.

KNOWN ISSUES

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

There is a file KNOWN_INCOMP which lists known incompatibilities with PDF::API2, in case you're thinking of porting over something from that world, or have experience there and want to try PDF::Builder. There is also a file DEPRECATED which lists things which are planned to be removed at some point.

HISTORY

The history of PDF::Builder is a complex and exciting saga... OK, it may be mildly interesting. Have a look at PDF::Builder::Docs History section.

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.

SUPPORT

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 (with "bug" label), feature requests have an "enhancement" label, and general discussions (architecture, roadmap, etc.) have a "general discussion" label. 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

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.

GENERIC METHODS

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

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

Creates a new PDF object.

Options

-file: 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.
-compress: The '-compress' option can be given to specify stream compression: default is 'flate', 'none' is no compression. No other compression methods are currently supported.
-outver: The '-outver' option defaults to 1.4 as the output PDF version and the highest allowed feature version (attempts to use anything higher will give a warning). If an existing PDF with a higher version is read in, -outver will be increased to that version, with a warning.
-msgver: The '-msgver' option value of 1 (default) gives a warning message if the '-outver' PDF level has to be bumped up due to either a higher PDF level file being read in, or a higher level feature was requested. A value of 0 suppresses the warning message.

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, including the Page Mode, Page Layout, Viewer, and Initial Page Options. See PDF::Builder::Docs section Preferences for details on all these option groups.

$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).

For compatibility with earlier releases, if no decimal point is given, assume "1." precedes the number given.

A warning message is given if you attempt to decrease the PDF version, as you might have already read in a higher level file, or used a higher level feature.

$bool = $pdf->isEncrypted()

Checks if the previously opened PDF is encrypted.

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

Gets/sets the info structure of the document.

See PDF::Builder::Docs info Example section for an example of the use of this method.

@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.

See PDF::Builder::Docs XMP XML example section for an example of the use of this method.

$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');

$pdf->save()

Save the document to an already-defined file (or filename) and remove the object structure from memory.

Example:

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

$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. This defines the width and height (or corner coordinates, or by standard name) of the output page itself, such as the physical paper size.

Note that many printers can not print all the way to the physical edge of the paper, so you should plan to leave some blank margin, even outside of any crop marks and bleeds. Printers and on-screen readers are free to discard any content found outside the MediaBox, and printers may discard some material just inside the MediaBox.

It is required; if not given, the displayed media size is unpredictable. A global setting can be inherited by each page, or can be overridden.

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. This will define the media size to which the output will later be cropped (trimmed) or clipped. Note that this does not itself output any crop marks to guide cutting of the paper! PDF Readers should consider this to be the visible portion of the page, and anything found outside it may be clipped (invisible). By default, it is equal to the MediaBox. A global setting can be inherited by each page, or can be overridden.

$pdf->bleedbox($name)

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

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

Sets the global BleedBox. This is another form of CropBox, typically used in printing on paper where you want color (such as thumb tabs) to be printed a bit beyond the final paper size, to ensure that the cut goes through the ink, rather than accidentally leaving some white paper visible outside. The default value is equal to the CropBox.

$pdf->trimbox($name)

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

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

Sets the global TrimBox. Another form of CropBox, it is supposed to be the actual dimensions of the finished page (after trimming of the paper). In some production environments, it is useful to have printer's instructions, cut marks, and so on outside of the trim box. The default value is equal to CropBox.

$pdf->artbox($name)

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

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

Sets the global ArtBox. Another form of CropBox, this is supposed to define "the extent of the page's meaningful content (including [margins])". It might exclude some content, such as Headlines or headings. Any binding or punched-holes margin would typically be outside of the ArtBox. The default value is equal to the CropBox.

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. For details, see PDF::Builder::Docs section Core Fonts.

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

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

Returns a new Adobe Type1 ("PostScript") font object. For details, see PDF::Builder::Docs section PS Fonts.

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

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

Returns a new TrueType (or OpenType) font object. For details, see PDF::Builder::Docs section TrueType Fonts.

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

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

Returns a new CJK font object. These are TrueType-like fonts for East Asian languages (Chinese, Japanese, Korean). For details, see PDF::Builder::Docs section CJK Fonts.

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

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

Returns a new synthetic font object. These are modifications to a core font (technically, variants supplied by the font creator, not on-the-fly changes), where the font may be replaced by a Type1 or Type3 PostScript font. For details, see PDF::Builder::Docs section Synthetic Fonts.

$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. For details, see PDF::Builder::Docs section TIFF Images.

$rc = $pdf->LA_GT()

Returns 1 if the library name (package) Graphics::TIFF is installed, and 0 otherwise. For this optional library, this call can be used to know if it is safe to use certain functions. For example:

    if ($pdf->LA_GT() {
        # is installed and usable
    } else {
        # not available. you will be running the old, pure PERL code
    }

$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, %options)

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

Imports and returns a new PNG image object. $file may be either a filename or a filehandle. For details, see PDF::Builder::Docs section PNG Images.

$rc = $pdf->LA_IPL()

Returns 1 if the library name (package) Image::PNG::Libpng is installed, and 0 otherwise. For this optional library, this call can be used to know if it is safe to use certain functions. For example:

    if ($pdf->LA_IPL() {
        # is installed and usable
    } else {
        # not available. don't use 16bps or interlaced PNG image files
    }

$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-safe" 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.

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

SOME SPECIAL NOTES

SOFTWARE DEVELOPMENT KIT

STRINGS (CHARACTER TEXT)

PDF VERSIONS SUPPORTED

SUPPORTED PERL VERSIONS

KNOWN ISSUES

HISTORY

AUTHOR

SUPPORT

LICENSE

GENERIC METHODS

PAGE METHODS

FONT METHODS

IMAGE METHODS

COLORSPACE METHODS

BARCODE METHODS

OTHER METHODS

Module Install Instructions