NAME
PDF::Data - Manipulate PDF files and objects as data structures
VERSION
version v1.2.0
SYNOPSIS
use PDF::Data;DESCRIPTION
This module can read and write PDF files, and represents PDF objects as data structures that can be readily manipulated.
METHODS
new
my $pdf = PDF::Data->new(-compress => 1, -minify => 1);Constructor to create an empty PDF::Data object instance. Any arguments passed to the constructor are treated as key/value pairs, and included in the $pdf hash object returned from the constructor. When the PDF file data is generated, this hash is written to the PDF file as the trailer dictionary. However, hash keys starting with "-" are ignored when writing the PDF file, as they are considered to be flags or metadata.
For example, $pdf->{-compress} is a flag which controls whether or not streams will be compressed when generating PDF file data. This flag can be set in the constructor (as shown above), or set directly on the object.
The $pdf->{-minify} flag controls whether or not to save space in the generated PDF file data by removing comments and extra whitespace from content streams. This flag can be used along with $pdf->{-compress} to make the generated PDF file data even smaller, but this transformation is not reversible.
clone
my $pdf_clone = $pdf->clone;Deep copy the entire PDF::Data object itself.
new_page
my $page = $pdf->new_page;
my $page = $pdf->new_page('LETTER');
my $page = $pdf->new_page(8.5, 11);Create a new page object with the specified size (in inches). Alternatively, certain page sizes may be specified using one of the known keywords: "LETTER" for U.S. Letter size (8.5" x 11"), "LEGAL" for U.S. Legal size (8.5" x 14"), or "A0" through "A8" for ISO A-series paper sizes. The default page size is U.S. Letter size (8.5" x 11").
copy_page
my $copied_page = $pdf->copy_page($page);Deep copy a single page object.
append_page
$page = $pdf->append_page($page);Append the specified page object to the end of the PDF page tree.
read_pdf
my $pdf = PDF::Data->read_pdf($file, %args);Read a PDF file and parse it with $pdf->parse_pdf(), returning a new object instance. Any streams compressed with the /FlateDecode filter will be automatically decompressed. Unless the $pdf->{-decompress} flag is set, the same streams will also be automatically recompressed again when generating PDF file data.
parse_pdf
my $pdf = PDF::Data->parse_pdf($data, %args);Used by $pdf->read_pdf() to parse the raw PDF file data and create a new object instance. This method can also be called directly instead of calling $pdf->read_pdf() if the PDF file data comes another source instead of a regular file.
write_pdf
$pdf->write_pdf($file, $time);Generate and write a new PDF file from the current state of the PDF::Data object.
The $time parameter is optional; if not defined, it defaults to the current time. If $time is defined but false (zero or empty string), no timestamp will be set.
The optional $time parameter may be used to specify the modification timestamp to save in the PDF metadata and to set the file modification timestamp of the output file. If not specified, it defaults to the current time. If a false value is specified, this method will skip setting the modification time in the PDF metadata, and skip setting the timestamp on the output file.
pdf_file_data
my $pdf_file_data = $document->pdf_file_data($time);Generate PDF file data from the current state of the PDF data structure, suitable for writing to an output PDF file. This method is used by the $pdf->write_pdf() method to generate the raw string of bytes to be written to the output PDF file. This data can be directly used (e.g. as a MIME attachment) without the need to actually write a PDF file to disk.
The optional $time parameter may be used to specify the modification timestamp to save in the PDF metadata. If not specified, it defaults to the current time. If a false value is specified, this method will skip setting the modification time in the PDF metadata.
dump_pdf
$pdf->dump_pdf($file, $mode);Dump the PDF internal structure and data for debugging. If the $mode parameter is "outline", dump only the PDF internal structure without the data.
dump_outline
$pdf->dump_outline($file);Dump an outline of the PDF internal structure for debugging. (This method simply calls the $pdf->dump_pdf() method with the $mode parameter specified as "outline".)
merge_content_streams
my $stream = $pdf->merge_content_streams($array_of_streams);Merge multiple content streams into a single content stream.
find_bbox
$pdf->find_bbox($content_stream, $new);Analyze a content stream to determine the correct bounding box for the content stream. The current implementation was purpose-built for a specific use case and should not be expected to work correctly for most content streams.
The $content_stream parameter may be a stream object or a string containing the raw content stream data.
The current algorithm breaks the content stream into lines, skips over various "neutral" lines and examines the coordinates specified for certain PDF drawing operators: "m" (moveto), "l" (lineto), "v" (curveto, initial point replicated), "y" (curveto, final point replicated), and "c" (curveto, all points specified).
The minimum and maximum X and Y coordinates seen for these drawing operators are used to determine the bounding box (left, bottom, right, top) for the content stream. The bounding box and equivalent rectangle (left, bottom, width, height) are printed.
If the $new boolean parameter is set, an updated content stream is generated with the coordinates adjusted to move the lower left corner of the bounding box to (0, 0). This would be better done by translating the transformation matrix.
new_bbox
$new_content = $pdf->new_bbox($content_stream);This method simply calls the $pdf->find_bbox() method above with $new set to 1.
timestamp
my $timestamp = $pdf->timestamp($time);
my $now = $pdf->timestamp;Generate timestamp in PDF internal format.
UTILITY METHODS
round
my @numbers = $pdf->round(@numbers);Round numeric values to 12 significant digits to avoid floating-point rounding error and remove trailing zeroes.
concat_matrix
my $matrix = $pdf->concat_matrix($transformation_matrix, $original_matrix);Concatenate a transformation matrix with an original matrix, returning a new matrix. This is for arrays of 6 elements representing standard 3x3 transformation matrices as used by PostScript and PDF.
invert_matrix
my $inverse = $pdf->invert_matrix($matrix);Calculate the inverse of a matrix, if possible. Returns undef if the matrix is not invertible.
translate
my $matrix = $pdf->translate($x, $y);Returns a 6-element transformation matrix representing translation of the origin to the specified coordinates.
scale
my $matrix = $pdf->scale($x, $y);Returns a 6-element transformation matrix representing scaling of the coordinate space by the specified horizontal and vertical scaling factors.
rotate
my $matrix = $pdf->rotate($angle);Returns a 6-element transformation matrix representing counterclockwise rotation of the coordinate system by the specified angle (in degrees).
INTERNAL METHODS
validate
$pdf->validate;Used by $pdf->new(), $pdf->parse_pdf() and $pdf->write_pdf() to validate some parts of the PDF structure. Currently, $pdf->validate() uses $pdf->validate_key() to verify that the document catalog and page tree root node exist and have the correct type, and that the page tree root node has no parent node. Then it calls $pdf->validate_page_tree() to validate the entire page tree.
By default, if a validation error occurs, it will be output as warnings, but the $pdf->{-validate} flag can be set to make the errors fatal.
validate_page_tree
my $count = $pdf->validate_page_tree($path, $page_tree_node);Used by $pdf->validate(), and called by itself recursively, to validate the PDF page tree and its subtrees. The $path parameter specifies the logical path from the root of the PDF::Data object to the page subtree, and the $page_tree_node parameter specifies the actual page tree node data structure represented by that logical path. $pdf->validate() initially calls $pdf->validate_page_tree() with "Root/Pages" for $path and $pdf->{Root}{Pages} for $page_tree_node.
Each child of the page tree node (in $page_tree_node->{Kids}) should be another page tree node for a subtree or a single page node. In either case, the parameters used for the next method call will be "$path\[$i]" for $path (e.g. "Root/Pages[0][1]") and $page_tree_node->{Kids}[$i] for $page_tree_node (e.g. $pdf->{Root}{Pages}{Kids}[0]{Kids}[1]). These parameters are passed to either $pdf->validate_page_tree() recursively (if the child is a page tree node) or to $pdf->validate_page() (if the child is a page node).
After validating the page tree, $pdf->validate_resources() will be called to validate the page tree's resources, if any.
If the count of pages in the page tree is incorrect, it will be fixed. This method returns the total number of pages in the specified page tree.
validate_page
$pdf->validate_page($path, $page);Used by $pdf->validate_page_tree() to validate a single page of the PDF. The $path parameter specifies the logical path from the root of the PDF::Data object to the page, and the $page parameter specifies the actual page data structure represented by that logical path.
This method will call $pdf->merge_content_streams() to merge the content streams into a single content stream (if $page->{Contents} is an array), then it will call $pdf->validate_content_stream() to validate the page's content stream.
After validating the page, $pdf->validate_resources() will be called to validate the page's resources, if any.
validate_resources
$pdf->validate_resources($path, $resources);Used by $pdf->validate_page_tree(), $pdf->validate_page() and $pdf->validate_xobject() to validate associated resources. The $path parameter specifies the logical path from the root of the PDF::Data object to the resources, and the $resources parameter specifies the actual resources data structure represented by that logical path.
This method will call validate_xobjects for $resources->{XObject}, if set.
validate_xobjects
$pdf->validate_xobjects($path, $xobjects);Used by $pdf->validate_resources() to validate form XObjects in the resources. The $path parameter specifies the logical path from the root of the PDF::Data object to the hash of form XObjects, and the $xobjects parameter specifies the actual hash of form XObjects represented by that logical path.
This method simply loops across all the form XObjects in $xobjects and calls $pdf->validate_xobject() for each of them.
validate_xobject
$pdf->validate_xobject($path, $xobject);Used by $pdf->validate_xobjects() to validate a form XObject. The $path parameter specifies the logical path from the root of the PDF::Data object to the form XObject, and the $xobject parameter specifies the actual form XObject represented by that logical path.
This method verifies that $xobject is a stream and $xobject->{Subtype} is "/Form", then calls $pdf->validate_content_stream() with $xobject to validate the form XObject content stream, then calls $pdf->validate_resources() to validate the form XObject's resources, if any.
validate_content_stream
$pdf->validate_content_stream($path, $stream);Used by $pdf->validate_page() and $pdf->validate_xobject() to validate a content stream. The $path parameter specifies the logical path from the root of the PDF::Data object to the content stream, and the $stream parameter specifies the actual content stream represented by that logical path.
This method calls $pdf->parse_objects() to make sure that the content stream can be parsed. If the $pdf->{-minify} flag is set, $pdf->minify_content_stream() will be called with the array of parsed objects to minify the content stream.
minify_content_stream
$pdf->minify_content_stream($stream, $objects);Used by $pdf->validate_content_stream() to minify a content stream. The $stream parameter specifies the content stream to be modified, and the optional $objects parameter specifies a reference to an array of parsed objects as returned by $pdf->parse_objects().
This method calls $pdf->parse_objects() to populate the $objects parameter if unspecified, then it calls $pdf->generate_content_stream() to generate a minimal content stream for the array of objects, with no comments and only the minimum amount of whitespace necessary to parse the content stream correctly. (Obviously, this means that this transformation is not reversible.)
Currently, this method also performs a sanity check by running the replacement content stream through $pdf->parse_objects() and comparing the entire list of objects returned against the original list of objects to ensure that the replacement content stream is equivalent to the original content stream.
generate_content_stream
my $data = $pdf->generate_content_stream($objects);Used by $pdf->minify_content_stream() to generate a minimal content stream to replace the original content stream. The $objects parameter specifies a reference to an array of parsed objects as returned by $pdf->parse_objects(). These objects will be used to generate the new content stream.
For each object in the array, this method will call an appropriate serialization method: $pdf->serialize_dictionary() for dictionary objects, $pdf->serialize_array() for array objects, or $pdf->serialize_object() for other objects. After serializing all the objects, the newly-generated content stream data is returned.
serialize_dictionary
$pdf->serialize_dictionary($stream, $hash);Used by $pdf->generate_content_stream(), $pdf->serialize_dictionary() (recursively) and $pdf->serialize_array() to serialize a hash as a dictionary object. The $stream parameter specifies a reference to a string containing the data for the new content stream being generated, and the $hash parameter specifies the hash reference to be serialized.
This method will serialize all the key-value pairs of $hash, prefixing each key in the hash with "/" to serialize the key as a name object, and calling an appropriate serialization routine for each value in the hash: $pdf->serialize_dictionary() for dictionary objects (recursive call), $pdf->serialize_array() for array objects, or $pdf->serialize_object() for other objects.
serialize_array
$pdf->serialize_array($stream, $array);Used by $pdf->generate_content_stream(), $pdf->serialize_dictionary() and $pdf->serialize_array() (recursively) to serialize an array. The $stream parameter specifies a reference to a string containing the data for the new content stream being generated, and the $array parameter specifies the array reference to be serialized.
This method will serialize all the array elements of $array, calling an appropriate serialization routine for each element of the array: $pdf->serialize_dictionary() for dictionary objects, $pdf->serialize_array() for array objects (recursive call), or $pdf->serialize_object() for other objects.
serialize_object
$pdf->serialize_object($stream, $object);Used by $pdf->generate_content_stream(), $pdf->serialize_dictionary() and $pdf->serialize_array() to serialize a simple object. The $stream parameter specifies a reference to a string containing the data for the new content stream being generated, and the $object parameter specifies the pre-serialized object to be serialized to the specified content stream data.
This method will strip leading and trailing whitespace from the pre-serialized object if the $pdf->{-minify} flag is set, then append a newline to ${$stream} if appending the pre-serialized object would exceed 255 characters for the last line, then append a space to ${$stream} if necessary to parse the object correctly, then append the pre-serialized object to ${$stream}.
validate_key
$pdf->validate_key($hash, $key, $value, $label);Used by $pdf->validate() to validate specific hash key values.
get_hash_node
my $hash = $pdf->get_hash_node($path);Used by $pdf->validate_key() to get a hash node from the PDF structure by path.
parse_objects
my @objects = $pdf->parse_objects($objects, $data, $offset);Used by $pdf->parse_pdf() to parse PDF objects into Perl representations.
parse_data
my @objects = $pdf->parse_data($data);Uses $pdf->parse_objects() to parse PDF objects from standalone PDF data.
filter_stream
$pdf->filter_stream($stream);Used by $pdf->parse_objects() to inflate compressed streams.
compress_stream
$new_stream = $pdf->compress_stream($stream);Used by $pdf->write_object() to compress streams if enabled. This is controlled by the $pdf->{-compress} flag, which is set automatically when reading a PDF file with compressed streams, but must be set manually for PDF files created from scratch, either in the constructor arguments or after the fact.
resolve_references
$object = $pdf->resolve_references($objects, $object);Used by $pdf->parse_pdf() to replace parsed indirect object references with direct references to the objects in question.
write_indirect_objects
my $xrefs = $pdf->write_indirect_objects($pdf_file_data, $objects, $seen);Used by $pdf->write_pdf() to write all indirect objects to a string of new PDF file data.
enumerate_indirect_objects
$pdf->enumerate_indirect_objects($objects);Used by $pdf->write_indirect_objects() to identify which objects in the PDF data structure need to be indirect objects.
enumerate_shared_objects
$pdf->enumerate_shared_objects($objects, $seen, $ancestors, $object);Used by $pdf->enumerate_indirect_objects() to find objects which are already shared (referenced from multiple objects in the PDF data structure).
add_indirect_objects
$pdf->add_indirect_objects($objects, @objects);Used by $pdf->enumerate_indirect_objects() and $pdf->enumerate_shared_objects() to add objects to the list of indirect objects to be written out.
write_object
$pdf->write_object($pdf_file_data, $objects, $seen, $object, $indent);Used by $pdf->write_indirect_objects(), and called by itself recursively, to write direct objects out to the string of new PDF file data.
dump_object
my $output = $pdf->dump_object($object, $label, $seen, $indent, $mode);Used by $pdf->dump_pdf(), and called by itself recursively, to dump (or outline) the specified PDF object.