PDF::API2

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

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

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

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

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

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

$pdf->preferences(%options)

Controls viewing preferences for the PDF.

Page Mode Options:

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

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

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

$page_number can also have one of the following values:

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

$pdf->mediabox($name)

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

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

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

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

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

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

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

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

Returns a new CJK font object.

Examples:

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

Valid %options are:

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

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

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

Imports and returns a new JPEG image object.

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

Imports and returns a new TIFF image object.

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

Imports and returns a new PNM image object.

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

Imports and returns a new PNG image object.

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

Imports and returns a new GIF image object.

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

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

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

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

$pdf->resource($type, $key, $obj, $force)

Adds a resource to the global PDF tree.

Example:

    $pdf->resource('Font', $fontkey, $fontobj);
    $pdf->resource('XObject', $imagekey, $imageobj);
    $pdf->resource('Shading', $shadekey, $shadeobj);
    $pdf->resource('ColorSpace', $spacekey, $speceobj);
    

Note: You only have to add the required resources if they are NOT handled by the font, image, shade or space methods.

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

PDFs using cross-reference streams instead of cross-reference tables are not yet supported. Cross-reference streams were added as an option in version 1.5 of the PDF spec, but were only used infrequently until Adobe Acrobat 9 started using them by default. A patch would be welcome -- see the PDF 1.7 specification, sections 7.5.4 and 7.5.8 for implementation details.

PDF::API2 was originally written by Alfred Reibenschuh.

It is currently being maintained by Steve Simms.