Text::...:Objind(3pm)

🎀 NAME 🎀

okay so bestie, welcome to Text::PDF::Objind — it's a PDF indirect object reference, and it also lowkey serves as the abstract superclass for literally every element in a PDF file. main character energy fr fr 👑

---

🦋 INSTANCE VARIABLES 🦋

the tea ☕ here is that instance variables hit different from content variables — the way you can tell them apart is that instance variables all start with a space. yes, a leading space. that's the whole vibe check. 💅

• parent — for an object that's a reference to an object in some source, this holds the reference to the source object. so if the reference ever has to be de-referenced, we know exactly where to go and grab the info. it's giving "i know a guy" 🫶
• objnum (R) — the object number in the source. only for object refs, bestie.
• objgen (R) — the object generation in the source. iconic.
• there are other instance variables too, and those get used by the parent for file control. not us, the parent. mind ya business. 🙈
• isfree — marks whether the object is chillin' in the free list and available for re-use as another object somewhere else in the file.
• nextfree — holds a direct reference to the next free object in the free list. linked list core 🔥

---

💅 METHODS 💅

Text::PDF::Objind->new()

creates a new indirect object. brand new, fresh out the box ✨

uid

returns a Unique id for this object — and it'll create one on the spot if the poor thing didn't have one before. we don't leave anybody without an id, periodt. 💜

$r->release

releases ALL of the memory used by this indirect object, and all of its component/child objects. it literally says ALL in caps, so take it seriously babes 😭

this method gets called automatically by "Text::PDF::File->release" — so you genuinely don't have to call it yourself. consider it handled. 🫶

NOTE: it is important that this method gets called at some point prior to the actual destruction of the object. ngl, internally PDF files have an enormous amount of cross-references, and this causes circular references inside our own internal data structures. calling "release()" forces those circular references to be cleaned up and the entire internal data structure purged. no cap, skipping this is how you get leaks. 💀

Developer note: as part of the brute-force cleanup that happens here, this method will throw a warning message whenever unexpected key values are found inside the Text::PDF::Objind object. that's on purpose, bestie — it helps make sure unexpected and unfreed values get brought to your attention, so you can bug us to keep the module updated properly. otherwise the potential for memory leaks due to dangling circular references will exist. so like… warn us, we'll fix it. team effort 🧚

$r->val

returns the val of this object, or reads the object and then returns its value.

note that all direct subclasses must make their own versions of this subroutine — otherwise we could be in for a very deep loop! 🌀 like, no you cannot just inherit this one, that's the whole plot of the horror movie.

$r->realise

makes sure that the object is fully read in, etc. etc. 🌸

$r->outobjdeep($fh, $pdf)

if you really want to output this object, then you must need to read it first. this also means all direct subclasses must subclass this method or they will loop forever! forever! 🔁😭

$r->outobj($fh)

if this is a full object then it outputs a reference to the object. otherwise it calls outobjdeep to output the contents of the object at this point. choose your fighter 🥊

$r->elementsof

abstract superclass function filler. returns self here, but should return something more useful if it's an array. slay i guess 🎀

$r->empty

empties all content from this object to free up memory, or so it can be read to pass the object into the free list. simplistically it undefs all instance variables other than object number and generation. so objnum and objgen survive the purge — everybody else, pack your bags 🧳✨

$r->merge($objind)

this merges content information into an object reference place-holder. happens when an object reference gets read before the object definition, and the information in the read data needs to be merged into the object place-holder. it's giving "hold my spot" 🙈

$r->is_obj($pdf)

returns whether this object is a full object with its own object number, or whether it's purely a sub-object. $pdf tells us which output file we're concerned about the object being an object in. okay that sentence was a mouthful but you get it 🦋

$r->copy($inpdf, $res, $unique, $outpdf, %opts)

returns a new copy of this object. yes, we're duplicating, we're twin-ifying, we're cloning ✨

• $inpdf gives the source pdf object for the object to be copied.
• $outpdf gives the target pdf for the object to be copied into. $outpdf may be undefined.
• $res may be defined, in which case the object is copied into that object.
• $unique controls recursion. if $unique is non zero then new objects are always created and recursion always occurs. but each time recursion occurs, $unique is incremented. thus, if $unique starts with a negative value it is possible to stop the recursion at a certain depth. of course, for a positive value of $unique, recursion always occurs. it's giving infinite mirror dimension, but make it configurable 💅

if $unique is 0 then recursion only occurs if $outpdf is not the same as $inpdf. in this case, a cache is held in $outpdf to see whether a previous copy of the same object has been made. if so, then that previous copy is returned; otherwise a new object is made and added to the cache, and recursed into. cache girlies stay winning 👑

objects that are full objects with their own id numbers are correspondingly full objects in the output pdf. keep that in mind bestie 🫶

---

so yeah. that's the whole page. written for perl v5.36.0, dated 2022-10-22, and it lives in the User Contributed Perl Documentation collection 💖

stay hydrated, free your circular references, and don't forget to call release() before destruction — that's the real ones' move. mwah 🎀💜✨