PDF::API2(3p)

NAME
PDF::API2 - Facilitates the creation and modification of PDF files

SYNOPSIS
    use PDF::API2;

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

    # Open an existing PDF file
    $pdf = PDF::API2->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');

GENERIC METHODS

$pdf = PDF::API2->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.

    Example:

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

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

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

    To turn off automatic compression of PDF contents, include option "-compress" with a false value. This is generally only useful for debugging.

$pdf = PDF::API2->open($pdf_file, %options)
    Opens an existing PDF file.

    Example:

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

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

    To turn off automatic compression of PDF contents, include option "-compress" with a false value. This is generally only useful for debugging.

$pdf = PDF::API2->open_scalar($pdf_string, %options)
    Opens a PDF contained in a string.

    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::API2->open_scalar($pdf_string);
        ...
        $pdf->saveas('our/new.pdf');

    To turn off automatic compression of PDF contents, include option "-compress" with a false value. This is generally only useful for debugging.

$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 behaviour of PDF::API2.

    Supported Parameters:

    nounrotate
        prohibits API2 from rotating imported/opened page to re-create a default pdf-context.

    pageencaps
        enables than API2 will add save/restore commands upon imported/opened pages to preserve graphics-state for modification.

    copyannots
        enables importing of annotations (*EXPERIMENTAL*).

$version = $pdf->version([$new_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::API2",
            '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::API2->new(-file => 'our/new.pdf');
        ...
        $pdf->finishobjects($page, $gfx, $txt);
        ...
        $pdf->save();

$pdf->update()
    Saves a previously opened document.

    Example:

        $pdf = PDF::API2->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::API2->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::API2->new();
        ...
        print $pdf->stringify();

$pdf->end()
    Remove the object structure from memory. PDF::API2 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::API2->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::API2::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::API2->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::API2->new();
        $old = PDF::API2->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 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::API2->new();
        $old = PDF::API2->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.

$count = $pdf->pages()
    Returns the number of pages in the document.

($llx, $lly, $urx, $ury) = $pdf->mediabox()
$pdf->mediabox($name)
$pdf->mediabox($w, $h)
$pdf->mediabox($llx, $lly, $urx, $ury)
    Get or set the global mediabox.

    Example:

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

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

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

($llx, $lly, $urx, $ury) = $pdf->cropbox()
$pdf->cropbox($name)
$pdf->cropbox($w, $h)
$pdf->cropbox($llx, $lly, $urx, $ury)
    Get or set the global cropbox.

    The cropbox defaults to the mediabox.

($llx, $lly, $urx, $ury) = $pdf->bleedbox()
$pdf->bleedbox($name)
$pdf->bleedbox($w, $h)
$pdf->bleedbox($llx, $lly, $urx, $ury)
    Get or set the global bleedbox.

    The bleedbox defaults to the cropbox.

($llx, $lly, $urx, $ury) = $pdf->trimbox()
$pdf->trimbox($name)
$pdf->trimbox($w, $h)
$pdf->trimbox($llx, $lly, $urx, $ury)
    Get or set the global trimbox.

    The trimbox defaults to the cropbox.

($llx, $lly, $urx, $ury) = $pdf->artbox()
$pdf->artbox($name)
$pdf->artbox($w, $h)
$pdf->artbox($llx, $lly, $urx, $ury)
    Get or sets the global artbox.

    The artbox defaults to the cropbox.

FONT METHODS

@directories = PDF::API2::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])
    Returns a new Adobe core font object.

    Examples:

        $font = $pdf->corefont('Times-Roman');
        $font = $pdf->corefont('Times-Bold');
        $font = $pdf->corefont('Helvetica');
        $font = $pdf->corefont('ZapfDingbats');

    Valid %options are:

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

    -dokern
        Enables kerning if data is available.

    See Also: PDF::API2::Resource::Font::CoreFont.

$font = $pdf->psfont($ps_file, [%options])
    Returns a new Adobe Type1 font object.

    Examples:

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

    Valid %options are:

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

    -afmfile
        Specifies the location of the font metrics file.

    -pfmfile
        Specifies the location of the printer font metrics file. This option overrides the -encode option.

    -dokern
        Enables kerning if data is available.

$font = $pdf->ttfont($ttf_file, [%options])
    Returns a new TrueType or OpenType font object.

    Examples:

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

    Valid %options are:

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

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

    -dokern
        Enables kerning if data is available.

    -noembed
        Disables embedding of the font file.

$font = $pdf->cjkfont($cjkname, [%options])
    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.

    See Also: PDF::API2::Resource::CIDFont::CJKFont

$font = $pdf->synfont($basefont, [%options])
    Returns a new synthetic font object.

    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)

    See Also: PDF::API2::Resource::Font::SynFont

$font = $pdf->bdfont($bdf_file)
    Returns a new BDF font object, based on the specified Adobe BDF file.

    See Also: PDF::API2::Resource::Font::BdFont

$font = $pdf->unifont(@fontspecs, %options)
    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!

    See Also: PDF::API2::Resource::UniFont.

    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)
    Imports and returns a new TIFF image object. $file may be either a filename or a filehandle.

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

    Note: PNG files that include an alpha (transparency) channel go through a relatively slow process of separating the transparency channel into a PDF SMask object. Install PDF::API2::XS or Image::PNG::Libpng to speed this up by an order of magnitude.

$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)
    Imports and returns a new image object from GD::Image.

    Options: The only option currently supported is "-lossless => 1".

COLORSPACE METHODS

$cs = $pdf->colorspace_act($file)
    Returns a new colorspace object based on an Adobe Color Table file.

    See PDF::API2::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::API2::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])
    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

$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()
    Returns a new pattern object.

$obj = $pdf->shading()
    Returns a new shading object.

$otls = $pdf->outlines()
    Returns a new or existing outlines object.

SUPPORTED PERL VERSIONS
PDF::API2 will aim 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.

For example, a version of PDF::API2 released on 2018-01-01 would support the last major version of Perl released before 2012-01-01, which happens to be 5.14.

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.

AUTHOR
PDF::API2 was originally written by Alfred Reibenschuh, extending code written by Martin Hosken.

It is currently being maintained and developed by Steve Simms.

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