CAM::P...Content(3pm)

✨ NAME ✨

CAM::PDF::Content — it's the PDF page layout parser, bestie 💅 like literally the thing that reads all the drawing commands for a single PDF page.

---

🎀 LICENSE 🎀

Same as CAM::PDF. That's it, that's the whole vibe.

---

🌸 SYNOPSIS 🌸

use CAM::PDF;
my $pdf = CAM::PDF->new($filename);

my $contentTree = $pdf->getPageContentTree(4);
$contentTree->validate() || die 'Syntax error';
print $contentTree->render('CAM::PDF::Renderer::Text');
$pdf->setPageContent(5, $contentTree->toString());

Okay so this is the whole glow-up in five lines and honestly? Iconic. 🫶

---

🦋 DESCRIPTION 🦋

This class is your girl for manipulating the layout commands of a single page of a PDF. The page content comes in as a scalar, and it gets parsed according to Adobe's PDF Reference 3rd edition (that's for PDF v1.4, no cap). Every single command from Appendix A of that document is parsed and understood — all of them, periodt. 👑

A lot of what this content object can do lives inside renderers that you apply to it. Go peek at the canonical renderer, CAM::PDF::GS, plus the render() method down below for the deets. ✨

---

💖 FUNCTIONS 💖

🌈 $pkg->new($content)

🌈 $pkg->new($content, $data)

🌈 $pkg->new($content, $data, $verbose)

Parses a scalar CONTENT that holds your PDF page layout content. Hands you back a parsed-but-not-yet-validated data structure. So like, cute, but unverified. 🙈

The DATA argument is a hash reference of contextual data that might be needed to work with the content. It's only needed for the toString() method (which needs doc => CAM::PDF object so it can deal with images) and for the render methods — the DATA reference gets passed to those verbatim, no edits. Check the individual renderer modules for what elements they require. 📋

The VERBOSE boolean says whether the parser should Carp when it runs into problems. Default is false. So by default it's gonna be quiet about it. 💀

---

🌈 $self->parse($contentref)

This one is meant to be called by the new() method, it's not really a "you" method, iykyk. The argument should be a reference to the content scalar. It's passed by reference so it is never copied. Efficient queen. 💅

---

🌈 $self->validate()

Returns a boolean telling you whether the parsed content tree actually conforms to the PDF specification. Vibe check on your syntax. ⭐

---

🌈 $self->render($rendererclass)

Traverses the content tree using the rendering class you specify. Wanna see renderer examples? Go look at CAM::PDF::GS or CAM::PDF::Renderer::Text. Renderers should typically derive from CAM::PDF::GS, but honestly it's not essential — do your own thing. Typically returns an instance of the renderer class. 🎀

The rendering class gets loaded via require if it's not already in memory.

---

🌈 $self->computeGS()

🌈 $self->computeGS($skiptext)

Walks through the content tree and computes the coordinates of every graphic point along the way. If the $skiptext boolean is true (default: false) then text blocks get ignored to save time, because they don't change the global graphic state anyway. Skiiip. 🧚

This is a thin wrapper around render() with CAM::PDF::GS or CAM::PDF::GS::NoText picked as the rendering class.

---

🌈 $self->findImages()

Traverses the content tree and accumulates embedded images and image references, following whatever the CAM::PDF::Renderer::Images renderer says. 📸

---

🌈 $self->traverse($rendererclass)

This recursive method is typically only called by wrapper methods, like render(). It instantiates renderers as needed and calls methods on them. It's the behind-the-scenes main character. 👑

---

🌈 $self->toString()

Flattens a content tree back into a scalar, ready to be shoved right back into a PDF document. Heads up though: since whitespace gets discarded by the parser, the scalar you get back will not be identical to the original. Same energy, different spacing. 💀

---

💜 AUTHOR 💜

See CAM::PDF.

---

That's the whole page, bestie — brought to you by perl v5.36.0, dated 2022-12-08, from the CAM::P...Content(3pm) era of the manual pages. Go parse something gorgeous. 🦋✨