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 "Software Development Kit" in PDF::Builder::Docs for suggestions.

OPTIONAL LIBRARIES

PDF::Builder can make use of some optional libraries, which are not required for a successful installation, but improve speed and capabilities. See "Optional Libraries" in PDF::Builder::Docs for more information.

STRINGS (CHARACTER TEXT)

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

RENDERING ORDER

Invoking "text" and "graphics" methods can lead to unexpected results (a different ordering of output than intended). See "Rendering Order" in PDF::Builder::Docs for more information.

PDF VERSIONS SUPPORTED

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

SUPPORTED PERL VERSIONS (BACKWARDS COMPATIBILITY GOALS)

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.

Anticipated Support Cutoff Dates

Note that these are not hard and fast dates. In particular, we develop on Strawberry Perl, which sometimes falls a little behind the official Perl release!

• 5.28 current minimum supported version, until next PDF::Builder release after 22 May, 2025. This is currently the minimum tested version.
• 5.30 future minimum supported version, until next PDF::Builder release after 20 June, 2026
• 5.32 future minimum supported version, until next PDF::Builder release after 20 May, 2027. This is currently our primary development version.
• 5.34 future minimum supported version, until next PDF::Builder release after 28 May, 2028
• 5.36 future minimum supported version, until next PDF::Builder release after 02 Jul, 2029
• 5.38 future minimum supported version, until next PDF::Builder release some time after 02 Jul, 2029. This is currently the maximum tested version.

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.

On the other hand, any feature in PDF::Builder should continue to work unchanged for the life of most long-term-stable (LTS) server distributions. Their lifetime is usually about six (6) years. Note that this does not constitute a statement of warranty, but that we intend to try to keep any particular release of PDF::Builder working for a period of years. Of course, it helps if you periodically update your Perl installation to something released in the recent past.

KNOWN ISSUES

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

There is a file INFO/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 INFO/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 "History" in PDF::Builder::Docs section.

AUTHOR

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

It was maintained by Steve Simms, who is still contributing new code to it (which often ends up in PDF::Builder).

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

SUPPORT

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

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

A formatted copy of the documentation (POD) may be found online, for your convenience, at https://www.catskilltech.com/Documentation/PDF/Builder.html.

Copies of most of the output of "examples/" sample programs may be found online at https://www.catskilltech.com/Examples/PDF/Builder.html.

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.

Do not under any circumstances open a PR (Pull Request) to report a bug. That's not what a PR is for, and is a waste of both your and our time and effort. Open a regular ticket (issue), and attach a Perl (.pl) program illustrating the problem, if possible. If you believe that you have a program patch, and offer to share it as a PR, we may give the go-ahead. Unsolicited PRs may be closed without further action.

LICENSE

This software is Copyright (c) 2017-2025 by Phil M. Perry.

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.)
  (A copy is provided in the INFO/LICENSE file for your convenience.)

This section of Builder.pm is intended only as a very brief summary of the license; please consider INFO/LICENSE to be the controlling version, if there is any conflict or ambiguity between the two.

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 of this license.

NOTE: there are several files in this distribution which were incorporated from outside sources and carry different licenses. If a file states that it is under a license different than LGPL 2.1, that license and its terms will apply to that file, and not LGPL 2.1.

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.

new

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

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 (the file is opened immediately for writing, rather than waiting until the "save"). The "file" may also be a filehandle.

compress

The 'compress' option can be given to specify stream compression: default is 'flate', 'none' (or 0) 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.

diaglevel

The 'diaglevel' option can be given to specify the level of diagnostics given by IntegrityCheck(). The default is level 2 (errors and warnings). See "IntegrityCheck" in PDF::Builder::Docs for more information.

Example:

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

default_page_size

    $pdf->default_page_size($size); # Set
    @rectangle = $pdf->default_page_size() # Get

default_page_boundaries

    $pdf->default_page_boundaries('media' => [xmin, ymin, xmax, ymax]); 
         # Set the media box
    %boundaries = $pdf->default_page_boundaries(); # Get (all five)
    @media_rect = @{ $boundaries{'media'} }; # show 'media' box

open

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

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

from_string, open_scalar, openScalar

    $pdf = PDF::Builder->from_string($pdf_string, %opts)

diags => 1

Display warnings when non-conforming PDF structure is found, and fix up where possible. See PDF::Builder::Basic::PDF::File for more information.

Example:

    # Read a PDF into a string, for the purpose of demonstration
    open $fh, 'our/old.pdf' or croak $@;
    undef $/;  # Read the whole file at once
    $pdf_string = <$fh>;
    $pdf = PDF::Builder->from_string($pdf_string);
    ...
    $pdf->saveas('our/new.pdf');

to_string, stringify

    $string = $pdf->to_string()

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

finishobjects

    $pdf->finishobjects(@objects)

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

update

    $pdf->update()

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

saveas

    $pdf->saveas($file)

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

save

    $pdf->save()
    $pdf->save(filename)

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

close, release, end

    $pdf->close();

end

    $pdf->end()

METADATA METHODS

title

    $title = $pdf->title();
    $pdf = $pdf->title($title);

author

    $author = $pdf->author();
    $pdf = $pdf->author($author);

subject

    $subject = $pdf->subject();
    $pdf = $pdf->subject($subject);

keywords

    $keywords = $pdf->keywords();
    $pdf = $pdf->keywords($keywords);

creator

    $creator = $pdf->creator();
    $pdf = $pdf->creator($creator);

producer

    $producer = $pdf->producer();
    $pdf = $pdf->producer($producer);

created

    $date = $pdf->created();
    $pdf = $pdf->created($date);

modified

    $date = $pdf->modified();
    $pdf = $pdf->modified($date);

info_metadata

    %info = $pdf->info_metadata(); # Get all keys and values
    $value = $pdf->info_metadata($key); # Get the value of one key
    $pdf = $pdf->info_metadata($key, $value); # Set the value of one key

info

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

infoMetaAttributes

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

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

xml_metadata

    $xml = $pdf->xml_metadata();
    $pdf = $pdf->xml_metadata($xml);

xmpMetadata

    $xml = $pdf->xmpMetadata()  # Get
    $xml = $pdf->xmpMetadata($xml)  # Set (also returns $xml value)

default

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

nounrotate

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

pageencaps

enables Builder's adding save/restore commands upon importing/opening pages to preserve graphics-state for modification.

copyannots

enables importing of annotations (*EXPERIMENTAL*).

version

    $version = $pdf->pdf_version() # Get
    $version = $pdf->pdf_version($version) # Set (also returns newly set version)

is_encrypted, isEncrypted

    $bool = $pdf->is_encrypted()

outline, outlines

    $otls = $pdf->outline()

page_layout

    $layout = $pdf->page_layout();
    $pdf = $pdf->page_layout($layout);

single_page (or undef)

Display one page at a time.

one_column

Display the pages in one column (a.k.a. continuous).

two_column_left

Display the pages in two columns, with odd-numbered pages on the left.

two_column_right

Display the pages in two columns, with odd-numbered pages on the right.

two_page_left

Display two pages at a time, with odd-numbered pages on the left.

two_page_right

Display two pages at a time, with odd-numbered pages on the right.

page_mode

    $mode = $pdf->page_mode(); # Get
    $pdf = $pdf->page_mode($mode); # Set

none (or undef)

Neither outlines nor thumbnails should be displayed.

outlines

Show the document outline.

thumbnails

Show the page thumbnails.

full_screen

Open in full-screen mode, with no menu bar, window controls, or any other window visible.

optional_content

Show the optional content group panel.

attachments

Show the attachments panel.

viewer_preferences

    %preferences = $pdf->viewer_preferences(); # Get
    $pdf = $pdf->viewer_preferences(%preferences); # Set

preferences

    $pdf->preferences(%opts)

page

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

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

open_page, openpage

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

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

import_page, importpage

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

    my $pdf = PDF::Builder->new();
    my $source = PDF::Builder->open('source.pdf');
    # Add page 2 from the old PDF as page 1 of the new PDF
    my $page = $pdf->import_page($source, 2);
    $pdf->saveas('sample.pdf');

embed_page, importPageIntoForm

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

    # take page 2 of source.pdf and add to empty doc sample.pdf at half size
    # note that sample.pdf could be an existing document!
    #
    my $pdf = PDF::Builder->new();                      # so far, empty document
    my $source = PDF::Builder->open('source.pdf');        # content to copy over
    my $page = $pdf->page();                      # place to be actually updated
    # Import Page 2 from the source PDF
    my $xo = $pdf->embed_page($source, 2);
    # Add it to the new PDF's first page at 1/2 scale
    my ($x, $y) = (0, 0);
    $page->object($xo, $x, $y, 0.5);
    $pdf->save('sample.pdf');

page_count, pages

    $count = $pdf->page_count()

page_labels, pageLabel

    $pdf->page_labels($page_number, %opts)

1.

The given page index started at 0 for the old method (pageLabel()), which is the internal PDF array index, while for the new method (page_labels()) it starts with 1, the visible page number! Don't get confused.

2.

Options for the old method ("pageLabel") were a hashref, while for the new method ("page_labels") it is a hash. This permits pageLabel() to accept multiple page number schemes in one call, rather than one per call as per page_labels().

3.

Many PDF readers do not support page labels; they simply (at most) label the sliding thumb with the physical page number. Adobe Acrobat Reader (free version) appears to have a bug in some versions, where if the only page label is 'decimal' (the default), it labels the thumb as though no page labels were defined ("Page m of n"). You can get around this problem by using an explicit start option value, e.g., "'start' => 1". However, for your convenience, the start option now defaults to 1.

    # Generate a 30-page PDF
    my $pdf = PDF::Builder->new();
    $pdf->page() for 1..30;
    # Number pages i to v, 1 to 20, and A-1 to A-5, respectively
    $pdf->page_labels(1, 'style' => 'roman');
    $pdf->page_labels(6, 'style' => 'decimal');
    $pdf->page_labels(26, 'style' => 'decimal', 'prefix' => 'A-');
    or...
    $pdf->pageLabel(0,  { style => 'roman' },
                    5,  { style => 'decimal' },
                    25, { style => 'decimal', prefix => 'A-' });
    $pdf->save('sample.pdf');

Supported Options:

style

Roman (I,II,III,...), roman (i,ii,iii,...), decimal (1,2,3,...), Alpha (A,B,C,...), alpha (a,b,c,...), or nocounter. This is the styling of the counter part of the label (unless "nocounter", in which case there is no counter output).

start

(Re)start numbering the counter at given page number (this is a decimal integer, not the styled counter). By default it starts at 1, and resets to 1 at each call to page_labels()! You need to explicitly give "start" if you want to continue counting at the current page number when you call page_labels(), whether or not you are changing the format.

Also note that the counter starts at physical page 1, while the page $index number in the page_labels() call (as well as the PDF PageLabels dictionary) starts at logical page (index) 0.

prefix

Text prefix for numbering, such as an Appendix letter B-. If "style" is nocounter, just this text is used, otherwise a styled counter will be appended. If "style" is omitted, remember that it will default to a decimal number, which will be appended to the prefix.

According to the Adobe/ISO PDF specification, a prefix of 'Content' has a special meaning, in that any /S counter is ignored and only that text is used. However, this appears to be ignored (use a style of nocounter to suppress the counter).

    # Start with lowercase Roman Numerals at the 1st page, starting with i (1)
    $pdf->page_labels(1, 
        'style' => 'roman',
    );
    or,
    $pdf->pageLabel(0, 
        { 'style' => 'roman' },
    );
    # Switch to Arabic (decimal) at the 5th page, starting with 1
    $pdf->page_labels(5, 
        'style' => 'decimal',
    );
    or, 
    $pdf->pageLabel(4, 
        { 'style' => 'decimal' },
    );
    # invalid style at the 25th page, should just continue 
    # with decimal at the current counter
    $pdf->page_labels(25, 
        'style' => 'raman_noodles',  # fail over to decimal
           # note that older versions of PDF::API2 may see the 'r' and 
           #   treat it as 'roman'
        'start' => 25,  # necessary, otherwise would restart at 1
    );
    # No page label at the 31st and 32nd pages. Note that this could be
    # confusing to the person viewing the PDF, but may be appropriate if
    # the page itself has no numbering.
    $pdf->page_labels(31, 
        'style' => 'nocounter',
    );
    # Numbering for Appendix A at the 33rd page, A-1, A-2,...
    $pdf->page_labels(33, 
        'start' => 1,  # unnecessary
        'prefix' => 'A-'
    );
    # Numbering for Appendix B at the 37th page, B-1, B-2,...
    $pdf->page_labels(37, 
        'prefix' => 'B-'
    );
    # Numbering for the Index at the 41st page, Index I, Index II,...
    $pdf->page_labels(41, 
        'style' => 'Roman',
        'start' => 1,  # unnecessary
        'prefix' => 'Index '  # note trailing space
    );
    # Unnumbered 'Index' at the 45th page, Index, Index,...
    $pdf->page_labels(45, 
        'style' => 'nocounter',
        'prefix' => 'Index '
    );

userunit

    $pdf->userunit($value)

mediabox

    $pdf->mediabox($name)
    $pdf->mediabox($name, 'orient' => 'orientation')
    $pdf->mediabox($w,$h)
    $pdf->mediabox($llx,$lly, $urx,$ury)
    ($llx,$lly, $urx,$ury) = $pdf->mediabox()

cropbox

    $pdf->cropbox($name)
    $pdf->cropbox($name, 'orient' => 'orientation')
    $pdf->cropbox($w,$h)
    $pdf->cropbox($llx,$lly, $urx,$ury)
    ($llx,$lly, $urx,$ury) = $pdf->cropbox()

bleedbox

    $pdf->bleedbox($name)
    $pdf->bleedbox($name, 'orient' => 'orientation')
    $pdf->bleedbox($w,$h)
    $pdf->bleedbox($llx,$lly, $urx,$ury)
    ($llx,$lly, $urx,$ury) = $pdf->bleedbox()

trimbox

    $pdf->trimbox($name)
    $pdf->trimbox($name, 'orient' => 'orientation')
    $pdf->trimbox($w,$h)
    $pdf->trimbox($llx,$lly, $urx,$ury)
    ($llx,$lly, $urx,$ury) = $pdf->trimbox()

artbox

    $pdf->artbox($name)
    $pdf->artbox($name, 'orient' => 'orientation')
    $pdf->artbox($w,$h)
    $pdf->artbox($llx,$lly, $urx,$ury)
    ($llx,$lly, $urx,$ury) = $pdf->artbox()

Embedding of Fonts

CAUTION: Some font routines (currently only ttfont()) automatically embed font definitions for the purpose of improving portability of PDF files. Note that font copyright and licensing terms vary by font provider, and some may prohibit embedding of their fonts, either entirely, or allowing only the subset of glyphs actually used in the document. You should be aware of the terms, and use the "noembed" or "nosubset" flags as appropriate. The PDF::Builder font routines currently have no means to automatically detect any embedding limitations for a given font, and cannot default their behavior accordingly!

Font-related Methods

corefont

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

psfont

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

ttfont

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

bdfont

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

cjkfont

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

font

    $font = $pdf->font($name, %opts)

    my $pdf = PDF::Builder->new();
    my $font1 = $pdf->font('Helvetica-Bold');
    my $font2 = $pdf->font('/path/to/ComicSans.ttf');
    my $page = $pdf->page();
    my $content = $page->text();
    $content->position(1 * 72, 9 * 72);
    $content->font($font1, 24);
    $content->text('Hello, World!');
    $content->position(0, -36);
    $content->font($font2, 12);
    $content->text('This is some sample text.');
    $pdf->saveas('sample.pdf');

The following options (%opts) are available:

format

The font format is normally detected automatically based on the file's extension (if one is given, as in non-core fonts). If you're using a font with an atypical extension, you can set "format" to one of "truetype" (TrueType or OpenType), "type1" (PostScript Type 1), or "bitmap" (Adobe Bitmap). There is no "format" entry for Core fonts, as the name must be an exact match.

(other options)

The %opts entries are passed on to the appropriate font format routine (corefont(), ttfont(), etc.), so they can be used here. These include 'encode', 'pdfname', 'pfmfile', 'dokern', etc. See the appropriate font routine for a full list of the supported options.

font_path

    @directories = PDF::Builder->font_path()

add_to_font_path, addFontDirs

    @directories = PDF::Builder::add_to_font_path('/my/fonts', '/path/to/fonts', ...)

set_font_path

    @directories = PDF::Builder->set_font_path('/my/fonts', '/path/to/fonts');

synfont, synthetic_font

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

unifont

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

Font Manager methods

The Font Manager is automatically initialized.

font_settings

    @list = $pdf->font_settings()  # Get
    $pdf->font_settings(%info)  # Set

add_font_path

    $rc = $pdf->add_font_path("a directory path", %opts)

add_font

    $rc = $pdf->add_font(%info)

get_font

    @current = $pdf->get_font()  # Get
    $font = $pdf->get_font(%info)  # Set

dump_font_tables

    $pdf->dump_font_tables()

image

    $object = $pdf->image($file, %opts);

    my $pdf = PDF::Builder->new();
    my $page = $pdf->page();
    my $image = $pdf->image('/path/to/image.jpg');
    $page->object($image, 100, 100);
    $pdf->save('sample.pdf');

image_jpeg

    $jpeg = $pdf->image_jpeg($file, %opts)

image_tiff

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

LA_GT

    $rc = $pdf->LA_GT()

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

image_pnm

    $pnm = $pdf->image_pnm($file, %opts)

image_png

    $png = $pdf->image_png($file, %opts)

LA_IPL

    $rc = $pdf->LA_IPL()

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

image_gif

    $gif = $pdf->image_gif($file, %opts)

image_svg

    $pnm = $pdf->image_svg($file, %opts)

LA_SVG

    $rc = $pdf->LA_SVG()

    if ($pdf->LA_SVG() {
        # is installed and usable
    } else {
        # not available. can't use image_svg or any other SVG function
    }

image_gd

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

colorspace

    $colorspace = $pdf->colorspace($type, @arguments)

    my $pdf = PDF::Builder->new();
    my $page = $pdf->page();
    my $content = $page->graphics();
    # Add colorspaces for a spot color and the web-safe color palette
    my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
    my $web = $pdf->colorspace('web');
    # Fill using the spot color with 100% coverage
    $content->fill_color($spot, 1.0);
    # Stroke using the first color of the web-safe palette
    $content->stroke_color($web, 0);
    # Add a rectangle to the page
    $content->rectangle(100, 100, 200, 200);
    $content->paint();
    $pdf->save('sample.pdf');

spot

Spot colors are used to instruct a device (usually a printer) to use or emulate a particular ink color ($tint) for parts of the document. An $alt_color is provided for devices (e.g. PDF viewers) that don't know how to produce the named color. It can either be an approximation of the color in RGB, CMYK, or HSV formats, or a wildly different color (e.g. 100% magenta, %0F00) to make it clear if the spot color isn't being used as expected.

    my $spot = $pdf->colorspace('spot', $tint, $alt_color);

web

The web-safe color palette is a historical collection of colors that was used when many display devices only supported 256 colors.

    my $web = $pdf->colorspace('web');

act

An Adobe Color Table (ACT) file provides a custom palette of colors that can be referenced by PDF graphics and text drawing commands.

    my $act = $pdf->colorspace('act', $filename);

device

A device-specific colorspace allows for precise color output on a given device (typically a printing press), bypassing the normal color interpretation performed by raster image processors (RIPs).

    my $devicen = $pdf->colorspace('device', @colorspaces);

    my $pdf = PDF::Builder->new();
    my $page = $pdf->page();
    my $content = $page->graphics();
    # Create a two-color device colorspace
    my $yellow = $pdf->colorspace('spot', 'Yellow', '%00F0');
    my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
    my $device = $pdf->colorspace('device', $yellow, $spot);
    # Fill using a blend of 25% yellow and 75% spot color
    $content->fill_color($device, 0.25, 0.75);
    # Stroke using 100% spot color
    $content->stroke_color($device, 0, 1);
    # Add a rectangle to the page
    $content->rectangle(100, 100, 200, 200);
    $content->paint();
    $pdf->save('sample.pdf');

colorspace_act

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

colorspace_web

    $cs = $pdf->colorspace_web()

colorspace_hue

    $cs = $pdf->colorspace_hue()

colorspace_separation

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

colorspace_devicen

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

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

xo_* Bar Code routines

    $bc = $pdf->xo_codabar(%opts)
    $bc = $pdf->xo_code128(%opts)
    $bc = $pdf->xo_2of5int(%opts)
    $bc = $pdf->xo_3of9(%opts)
    $bc = $pdf->xo_ean13(%opts)

xo_form

    $xo = $pdf->xo_form()

egstate

    $egs = $pdf->egstate()

pattern

    $obj = $pdf->pattern(%opts)

shading

    $obj = $pdf->shading(%opts)

named_destination

    $ndest = $pdf->named_destination()