PDF::Bu...F::File(3)

📦
version 3.028 · 11 versions
, in fedora 44

PDF::Builder::Basic::PDF::File 💖

okay bestie, welcome to the User Contributed Perl Documentation corner of the internet, because this page is literally about holding the trailers and cross-reference tables for a PDF file and it's giving main character energy 🎀

✨ NAME ✨

PDF::Builder::Basic::PDF::File — Holds the trailers and cross-reference tables for a PDF file 🦋

🌸 SYNOPSIS 🌸

$p = PDF::Builder::Basic::PDF::File->open("filename.pdf", 1);
$p->new_obj($obj_ref);
$p->free_obj($obj_ref);
$p->append_file();
$p->close_file();
$p->release();       # IMPORTANT!
not me putting $p->release() last with a whole # IMPORTANT! comment — that's the original being dramatic, and honestly? valid. do not skip her. 💅

💜 DESCRIPTION 💜

So this class is the one keeping track of all the directory aspects of a PDF file. And ngl, the directory has two parts:

  1. the main directory object, which is the parent to every other object in the file 👑
  2. a chain of cross-reference tables plus their corresponding trailer dictionaries, and that chain starts with the main directory object

periodt. that's the whole structure. 🌈

🎀 INSTANCE VARIABLES 🎀

Okay so here's the vibe: inside this class hierarchy, instead of making everything visible through methods (which would be so much work, exhausting, no thanks 💀), there are a bunch of instance variables you can reach via associative array referencing.

And the way you tell an instance variable apart from a content variable (content variables being the ones that might come from the PDF content itself) is that every instance variable name starts with a space. iconic little detail honestly ✨

Variable names that don't start with a space? Those directly reflect elements in a PDF dictionary. And for a PDF::Builder::Basic::PDF::File, those elements reflect the ones in the trailer dictionary. iykyk 🦋

And because some variables are not designed for class users to touch at all, they get marked up in the docs like this:

  • (R) — read-only energy, only use this as read-only information, bestie, don't get creative
  • (P) — private, like genuinely not designed for user use at all, but it's included in the documentation anyway for completeness and to make sure nobody else tries to use it 🙈

🌟 newroot

This one lets you create a new root entry that will show up in the trailer dictionary when the file is written or appended. So if you wanna override the root element in the dictionary you already have, you use this entry to say that — without losing the current Root entry. 🫶

heads up though: newroot should point to a PDF level object, not just to a dictionary. a dictionary doesn't have object status, so that won't fly. 💅

🌟 INFILE (R)

Holds the filehandle that was used to read this information into this PDF directory. It's an IO object. 🍓

🌟 fname (R)

The filename reflected by INFILE, or the original IO object that got passed in. either way, she's the name girlie 🌸

🌟 update (R)

This tells you that the read file has been opened for update, and that at some point "$p->appendfile()" can be called to update the file with all the changes that have been made to the in-memory representation. 🔥

🌟 maxobj (R)

Holds the first usable object number that sits above any object numbers that have already appeared in the file so far. ⭐

🌟 outlist (P)

A list of Objind that are gonna be output the next time appendfile() or outfile() happens. 🦋

🌟 firstfree (P)

The first free object in the free object list. Free objects get removed from the front of the list and added to the end. it's a whole queue situation, very demure 🎀

🌟 lastfree (P)

The last free object in the free list. Fun fact: it might be the same as "firstfree" if there's only one free object hanging around. 💅

🌟 objcache (P)

All objects live in the cache, and the whole reason is to make sure a system only ever has one occurrence of each object. Basically, the objind class acts as a container type class holding the PDF object structure, and it would be genuinely unfortunate if two identical place-holders were floating around a system. like, messy. we don't do messy. 💀

🌟 epos (P)

The end location of the read-file. that's it, that's the whole variable 🌈

And bestie, here's the little structural tea ☕: each trailer dictionary contains a number of private instance variables whose whole job is holding the chain together. 🔗

🌟 loc (P)

Holds the location of the start of the cross-reference table that comes before the trailer. ✨

🌟 xref (P)

Holds an anonymous array of each cross-reference table entry. 🍓

🌟 prev (P)

A reference to the previous table. 🦋

important distinction, don't mix these up: this is not the same as the Prev entry that lives in PDF, which contains the location of the previous cross-reference table. one is a reference, one is a location. prev vs Prev. case-sensitive, bestie, keep your eyes on it 👀

✨ METHODS ✨

new 🌱

PDF::Builder::Basic::PDF::File->new()

Makes you a brand new, empty file object — and this lil guy can be the host for all your other PDF objects, bestie. There's literally no file attached to it, so the whole vibe is "this was created in readiness for making a new PDF file." Manifesting that PDF, fr fr. 💖

open 📂

$p = PDF::Builder::Basic::PDF::File->open($filename, $update, %options)

Opens the file and reads all the trailers and cross reference tables so it can build a complete directory of objects. Iconic behavior.

  • $filename can be a string or an IO object. Whatever slays.
  • $update tells us whether this file is being opened for updating and editing (a TRUE value) or just to be read (FALSE or undefined, aka not that deep).

%options may include:

  • diags => 1 — if diags is set to 1, you get various warning messages whenever a suspicious PDF structure is found, and some fixup may be attempted. Now, no guarantee that any fixup will actually turn the PDF into something legitimate, or that there won't be other problems lurking further down the line. If you don't give this flag and a structural problem shows up, it's fairly likely that errors (and even a program crash 😭) may happen further along. So if you're experiencing crashes while reading in a PDF file, try running with diags and see what gets reported. It's giving detective energy. 🔍
There are so many PDF files out "in the wild" that, while failing to conform to Adobe's standards, appear to be tolerated by PDF Readers. So Builder will not fail on them — it will merely comment on their existence. Petty but polite. 💅

version 📌

$new_version = $p->pdf_version($version, %opts) # Set
$ver = $p->pdf_version() # Get

Gets/sets the PDF version (like, 1.5 bestie). Setting it sets both the header and trailer versions. Getting it returns whichever is higher between the header and trailer versions — main character wins, obviously. 👑

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, because you might have already read in a higher level file, or used a higher level feature. That message is suppressed if the 'silent' option is given with any value. 🤫

header_version 🎀

$new_version = $p->header_version($version, %opts) # Set
$version = $p->header_version() # Get

Gets/sets the PDF version stored in the file header.

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. This message is suppressed if the 'silent' option is given with any value. 💜

trailer_version 🦋

$new_version = $p->trailer_version($version, %opts) # Set
$version = $p->trailer_version() # Get

Gets/sets the PDF version stored in the document catalog.

Heads up: the minimum PDF level for a trailer version is 1.4. It is not permitted to set a PDF level of 1.3 or lower. And an existing PDF (read in) of 1.3 or below returns undefined. So like… no. 🙈

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. This message is suppressed if the 'silent' option is given with any value. 🌸

require_version 🔒

$prev_version = $p->require_version($version)

Makes sure the PDF version is at least $version. Silently sets the version to the higher level. No drama, just quietly upgrading you. ✨

release 💀

$p->release()

Releases ALL of the memory used by the PDF document and all of its component objects. After calling this method, do NOT expect to have anything left in the PDF::Builder::Basic::PDF::File object — so if you need to save, be absolutely sure you do it before calling this method. Save first, release after. Periodt.

NOTE, that it is important that you call this method on any PDF::Builder::Basic::PDF::File object when you wish to destroy it and free up its memory. Internally, PDF files have an enormous number of cross-references, and this causes circular references within the internal data structures. Calling release() causes a brute-force cleanup of the data structures, freeing up all of the memory. Once you've called this method, though, don't expect to be able to do anything else with the PDF::Builder::Basic::PDF::File object — it'll have no internal state whatsoever. It's gone, girl. 🫶

append_file ➕

$p->append_file()

Appends the objects for output to the read file, and then appends the appropriate table. Chill little add-on. 🍓

out_file 📝

$p->out_file($fname)

Writes a PDF file to a file of the given filename, based on the current list of objects to be output. It creates the trailer dictionary based on information in $self.

$fname may be a string or an IO object. Both are valid, bestie. 💖

create_file 🌟

$p->create_file($fname)

Creates a new output file (no check is made of an existing open file, so like… be aware) of the given filename or IO object.

Note: make sure that $p->{' version'} is set correctly before calling this function. Do not skip this step, I'm begging. 😭

close_file 🚪

$p->close_file()

Closes up the open file for output by outputting the trailer, etc. Tidy. ✨

readval 📖

($value, $str) = $p->readval($str, %opts)

Reads a PDF value from the current position in the file. If $str is too short, it reads some more from the current location in the file until the whole object is read. This is a recursive call which may slurp in a whole big stream (unprocessed). Hungry lil function. 🍜

Returns the recursive data structure it read, and also the current $str that has been read from the file.

read_obj 🔎

$ref = $p->read_obj($objind, %opts)

Given an indirect object reference, it locates it and reads the object, returning the read-in object. Found it, read it, served it. 💅

read_objnum 🔢

$ref = $p->read_objnum($num, $gen, %opts)

Returns a fully read object of the given number and generation in this file.

new_obj 🆕

$objind = $p->new_obj($obj)

Creates a new, free object reference based on free space in the cross reference chain. If nothing is free, then it thinks up a new number (inventive queen 👑). If $obj is given, then it turns that object into this new object rather than returning a new object.

out_obj 📤

$p->out_obj($obj)

Indicates that the given object reference should appear in the output xref table, whether with data or freed. Show up and be counted, babe. ✨

free_obj 🕊️

$p->free_obj($obj)

Marks an object reference for output as being freed. Let it go, it's not your era anymore. 💜

remove_obj 🧹

$p->remove_obj($objind)

Removes the object from all places where we might remember it. Memory: cleared. Cleanup era. 🌸

ship_out 🚢

$p->ship_out(@objects)
$p->ship_out()

Ships the given objects (or all objects for output if @objects is empty) to the currently open output file (assuming there is one — fingers crossed 🫶). Freed objects are not shipped, and once an object is shipped it is switched such that this file becomes its source and it will not be shipped again unless out_obj is called again.

Notice that a shipped out object can be re-output or even freed, but that it will not cause the data already output to be changed. What's written is written, bestie. 💀

copy 📋

$p->copy($outpdf, \&filter)

Iterates over every object in the file, reading the object, calling filter with the object, and outputting the result. If filter is not defined, it just copies input to output. Simple, effective, ate. 🔥

🙈 PRIVATE METHODS & FUNCTIONS 💅

The following methods and functions are considered private to this class. That does not mean you cannot use them if you have a need — just that they aren't really designed for users of this class. So like, they're not for the general public but the door's unlocked, iykyk. 🤫

locate_obj 🗺️

$offset = $p->locate_obj($num, $gen)

Returns a file offset to the object asked for by following the chain of cross reference tables until it finds the one you want. A whole scavenger hunt. 🔍

update 🔄

update($fh, $str, $instream)

Keeps reading $fh for more data to ensure that $str has at least a line full for readval to work on. At this point we also take the opportunity to ignore comments. Not me ignoring comments, that's literally the job. 🙈

test_obj 🧪

$objind = $p->test_obj($num, $gen)

Tests the cache to see whether an object reference (which may or may not have been getobj()ed) has been cached. Returns it if it has. Vibe check on the cache. ✅

add_obj 🧺

$p->add_obj($objind)

Adds the given object to the internal object cache. Tucking it in safely. 🎀

readxrtr 🔁

$tdict = $p->readxrtr($xpos, %options)

Recursive function which reads each of the cross-reference and trailer tables in turn until there are no more. It keeps going until it's done, no cap.

Returns a dictionary corresponding to the trailer chain. Each trailer also includes the corresponding cross-reference table.

The structure of the xref private element in a trailer dictionary is of an anonymous hash of cross reference elements by object number. Each element consists of an array of 3 elements corresponding to the three elements read in [location, generation number, free or used]. See the PDF specification for details. (Yes, actually see it, bestie.)

See "open" for options allowed. 👀

out_trailer 📦

$p->out_trailer($tdict, $update)
$p->out_trailer($tdict)

Outputs the body and trailer for a PDF file by outputting all the objects in the ' outlist' and then outputting a xref table for those objects and any freed ones. It then outputs the trailing dictionary and the trailer code. Wrap it up with a bow. 🎀

_new 🌫️

PDF::Builder::Basic::PDF::File->_new()

Creates a very empty PDF file object (used by new() and open()). The blankest of slates. ✨

👑 AUTHOR 🌸

Martin Hosken Martin_Hosken@sil.org

Copyright Martin Hosken 1999

No warranty or expression of effectiveness, least of all regarding anyone's safety, is implied in this software or documentation. 🫶 (They said it, not me — but it's real and you should know it.)

And that's the whole page, bestie!! This was perl v5.42.0, dated 2026-01-17, from the PDF::Bu...F::File(3) manpage — you're fully caught up now, go forth and slay those PDFs. 💖✨🎀🦋

📦 where this page comes from