Text::PDF::File(3pm)

💖 Text::PDF::File 💖

okay bestie, welcome to the Text::PDF::File page from the User Contributed Perl Documentation — this is the module that literally holds all the trailers and cross-reference tables for a PDF file, and honestly it's giving filing-cabinet energy. It's a Perl 3pm manual, so grab a 🍓 and let's go.

---

✨ SYNOPSIS ✨

$p = Text::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!

bestie do NOT forget that release line. I'm so serious. It's flagged IMPORTANT for a reason 😭

---

🌸 DESCRIPTION 🌸

So this class? It keeps track of the directory aspects of a PDF file. And a directory has two parts, okay:

• the main directory object, which is the parent to all the other objects, and
• a chain of cross-reference tables plus the corresponding trailer dictionaries, starting with that main directory object.

That's the whole vibe. Directory stuff. Chain stuff. PDF stuff. Periodt. 💅

---

🦋 INSTANCE VARIABLES 🦋

ngl, within this class hierarchy they did not make everything visible via methods, because that would've been "a lot of work" (their words). Instead there are various instance variables chillin' here, accessible via associative array referencing.

To tell the instance variables apart from content variables (which might come from the PDF content itself, sneaky), every one of these instance variables starts with a space. It's the secret handshake. 🤝

Variables that do not start with a space? Those directly reflect elements in a PDF dictionary. And for a Text::PDF::File, those elements reflect the ones in the trailer dictionary.

Some variables aren't meant for class users to touch, so they're marked in the docs:

• (R) — read-only info only, bestie. Look, don't touch. 🙈
• (P) — private, not designed for user use at all. It's only in the docs for completeness and so nobody else tries to use it. Respect the boundary. 💀

🎀 newroot

This one's a glow-up variable ✨ — it lets you create a new root entry to appear in the trailer dictionary when the file gets written or appended. If you want to over-ride the root element in the dictionary you already have, use this entry to say so without losing the current Root entry. Iconic, frankly.

heads up: newroot should point to a PDF level object, not just some dictionary that doesn't have object status. Do not play yourself.

🌈 INFILE (R)

Contains the filehandle 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.

🫶 update (R)

This says the read file has been opened for update, and that at some point you can call $p->appendfile() to update the file with the changes you made to the in-memory representation. Memory → disk, slay.

⭐ maxobj (R)

Contains the first useable object number above any that have already appeared in the file so far.

🍓 outlist (P)

A list of Objind that are gonna be output when the next appendfile or outfile happens.

🧚 firstfree (P)

Contains 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 moment.

👑 lastfree (P)

Contains the last free object in the free list. It may be the same as firstfree if there's only one free object. (Solo free object energy.)

💅 objcache (P)

All objects are held in the cache, which ensures a system only 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 unfortunate if two identical place-holders were floating around a system. Two of the same object? Not on our watch. 💀

🌸 epos (P)

The end location of the read-file. That's it. That's the tea.

---

Every trailer dictionary also contains a bunch of private instance variables that hold the chain together. Chain-keeping variables, if you will. 🔗

🎀 loc (P)

Contains the location of the start of the cross-reference table preceding the trailer.

🦋 xref (P)

Contains an anonymous array of each cross-reference table entry.

💜 prev (P)

A reference to the previous table. And bestie, note this differs from the Prev entry which is in PDF itself — that one contains the location of the previous cross-reference table. Similar name, different job. Don't get it twisted. 😭

---

🔥 METHODS 🔥

💖 Text::PDF::File->new

Creates a new, empty file object that can act as the host to other PDF objects. Since there's no file associated with this object, it's assumed that the object is created in readiness for creating a brand new PDF file. Fresh start, main character energy. ✨

🌸 $p = Text::PDF::File->open($filename, $update)

Opens the file and reads all the trailers and cross reference tables to build a complete directory of objects.

• $update specifies whether this file is being opened for updating and editing, or simply to be read.
• $filename may be an IO object.

💅 $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 Text::PDF::File object — so if you need to save, be sure to do it before calling this method. Okay? Save first, release second. Non-negotiable.

NOTE: it is genuinely important that you call this method on any Text::PDF::File object when you wish to destruct 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()" forces 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 Text::PDF::File object — it'll have no internal state whatsoever. It's giving empty shell. 💀

Developer note: as part of that brute-force cleanup, this method will throw a warning message whenever unexpected key values are found within the Text::PDF::File object. This is done to help ensure that any unexpected and unfreed values are brought to your attention, so that you can bug them to keep the module updated properly — otherwise the potential for memory leaks due to dangling circular references will exist. So like... the warnings are a gift, not a jump scare. 🫶

🦋 $p->append_file()

Appends the objects for output to the read file, and then appends the appropriate tale. (Yes, the doc literally says "tale." We're keeping it. 💜)

⭐ $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 an IO object;

🍓 $p->create_file($fname)

Creates a new output file (and no, no check is made of an existing open file) of the given filename or IO object.

bestie, make sure $p->{' version'} is set correctly before calling this function. Note the space in the key. It's not a typo, it's the vibe. 👑

👑 $p->close_file

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

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

Reads a PDF value from the current position in the file. If $str is too short, then 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). Slurp queen.

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

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

Given an indirect object reference, locate it and read the object, returning the read-in object.

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

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

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

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

🌸 $p->out_obj($objind)

Indicates that the given object reference should appear in the output xref table — whether with data or freed. Either way, it's showing up.

🎀 $p->free_obj($objind)

Marks an object reference for output as being freed. Goodbye bestie. 🫡

🦋 $p->remove_obj($objind)

Removes the object from all places where we might remember it.

⭐ $p->ship_out(@objects)

Ships the given objects (or all objects for output if @objects is empty) to the currently open output file (assuming there is one, lol). Freed objects are not shipped, and once an object is shipped it gets 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. Once it's out, it's out. 💅

🍓 $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, then it just copies input to output. Simple. Clean. Lowkey elegant. ✨

---

💀 PRIVATE METHODS & FUNCTIONS 💀

The following methods and functions are considered private to this class. That doesn't mean you can't use them if you have a need — it just means they aren't really designed for users of this class. iykyk. 🤫

🌸 $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. Scavenger hunt, but make it xref tables.

🦋 update($fh, $str)

Keeps reading $fh for more data to ensure that $str has at least a line full for "readval" to work on. At this point they also take the opportunity to ignore comments. Sneaky but efficient. 💜

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

🎀 $p->add_obj($objind)

Adds the given object to the internal object cache.

👑 $tdict = $p->readxrtr($xpos)

Recursive function which reads each of the cross-reference and trailer tables in turn until there are no more. It keeps going and going until there's nothing left. Recursion queen. 🔥

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

💜 $p->out_trailer($tdict)

Outputs the body and trailer for a PDF file by outputting all the objects in the ' outlist' and then outputting an xref table for those objects and any freed ones. Then it outputs the trailing dictionary and the trailer code. Full send. 🚀

🌈 Text::PDF::File->_new

Creates a very empty PDF file object (used by new and open). Emphasis on very. It's empty empty. 💀

---

🌟 AUTHOR 🌟

Martin Hosken Martin_Hosken@sil.org

Copyright Martin Hosken 1999 and onwards.

No warranty or expression of effectiveness, least of all regarding anyone's safety, is implied in this software or documentation. (Read: bestie, it's provided as-is, pls be careful out there. 🙈)

💖 Licensing

This Perl Text::PDF module is licensed under the Perl Artistic License. 💅

---

okay and that's the whole page!! this manual came from perl v5.36.0, dated 2022-10-22, from the Text::PDF::File(3pm) page — mwah, love that for us, go read your PDFs responsibly. 🎀✨🦋