PDF::Report(3pm)

📦
version 1.36 · 2 versions
  • 1.36 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 1.36 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 PDF::Report — the manual, but make it make sense 💖

okay bestie, sit down, hydrate, and let me tell you about PDF::Report — a wrapper written for PDF::API2. This is the PDF::Report(3pm) page from the User Contributed Perl Documentation, and yes we're doing this properly, no skimming, no skipping, periodt. ✨

🌸 NAME 🌸

PDF::Report — a wrapper written for PDF::API2. That's it, that's the whole vibe. 🎀

🦋 SYNOPSIS 🦋

Look at this, it's literally three lines, you can do this:

    use PDF::Report;

my $pdf = new PDF::Report(%opts);

That's the whole opening move. You pull the module in, you make yourself an object, and you go live your life. 💅

✨ DESCRIPTION ✨

So here's the tea: this is a wrapper for Alfred Reibenschuh's PDF::API2. And what does it do with that? It defines methods to create PDF reports. That's the whole personality. It's a report-making bestie sitting on top of a PDF-making bestie. Iconic chain of command honestly. 👑

⭐ VERSION ⭐

 1.36

Yes bestie, we're on 1.36. Write it down. 🍓

💅 METHODS 💅

okay here comes the main event, the whole roster, every single one, let's go:

🎀 new 🎀

my $pdf = new PDF::Report(%opts);

Creates a new pdf report object. If no %opts are specified, the module will use the factory defaults. That's it. No drama, no fuss, defaults carry you. 🫶

Example:

my $pdf = new PDF::Report(PageSize => "letter",
                          PageOrientation => "Landscape");

my $pdf = new PDF::Report(File => $file);

Look at that second one, so chill, just hand it a file and go.

%opts:

Here's your option menu, don't lose it:

  • PageSize — pick your paper, bestie: '4A', '2A', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', '4B', '2B', 'B0', 'B1', 'B2', 'B3', 'B4', 'B5', 'B6', 'LETTER', 'BROADSHEET', 'LEDGER', 'TABLOID', 'LEGAL', 'EXECUTIVE', '36X36'
  • PageOrientation — which way is it facing: 'Portrait', 'Landscape'

🦋 newpage 🦋

$pdf->newpage($nopage);

Creates a new blank page. Pass $nopage = 1 to toggle page numbering. That's the little switch, don't forget it exists. ✨

🌸 openpage 🌸

$pdf->openpage($index);

If no index is specified, this will open the last page of the document. No index = last page, that's the default behaviour, no cap. 🎀

💜 importpage 💜

Import page from another PDF document, see PDF::API2. That's it, that's the whole entry, go read the other manual for the details, iykyk. 🧚

💖 clonepage 💖

Clone page within document, see PDF::API2. Same deal, the details live over there. 👑

🌈 getPageDimensions 🌈

($pagewidth, $pageheight) = $pdf->getPageDimensions();

Returns the width and height of the page according to what page size chosen in "new". So whatever you picked up in new, this hands you back the measurements. Cute. 🦋

🍓 addRawText 🍓

$pdf->addRawText($text, $x, $y, $color, $underline, $indent, $rotate);

Add $text at position $x, $y with $color, $underline, $indent and/or $rotate. Yes you can rotate it. Slay.

⚠️ okay this next part is the important lore, pay attention bestie:

PDF::API2 removes all space between every word in the string you pass and then rejoins each word with one space. So if you want to use a string with more than one space between words for formatting purposes, you can either use the hack below or change PDF::API2 (that's what I did ;). The code below may or may not work according to what font you are using. I used 2 \xA0 per space because that worked for the Helvetica font I was using.

To use a fixed width string with more than one space between words, you can do something like:

sub replaceSpace {
  my $text = shift;
  my $nbsp = "\xA0";
  my $new = '';
  my @words = split(/ /, $text);
  foreach my $word (@words) {
    if (length($word)) {
      $new.=$word . ' ';
    } else {
      $new.=$nbsp . $nbsp;
    }
  }
  chop($new);
  return $new;
}

Copy it, paste it, thank me later. 💖

💅 setAddTextPos 💅

$pdf->setAddTextPos($hPos, $vPos);

Set the position on the page. Used by the addText function. You set it here, addText uses it there. Teamwork. 🫶

✨ getAddTextPos ✨

($hPos, $vPos) = $pdf->getAddTextPos();

Return the (x, y) value of the text position. Yes, (x, y). That's exactly how the original says it. Not changing it. 💜

🎀 setAlign 🎀

$pdf->setAlign($align);

Set the justification of the text. Used by the addText function. Left, right, center, whatever, you pick. 👑

⭐ getAlign ⭐

$align = $pdf->getAlign();

Returns the text justification. Just tells you where you set it. Simple. 🍓

🦋 wrapText 🦋

$newtext = $pdf->wrapText($text, $width);

This is a helper function called by addText, which can be called by itself. wrapText() wraps $text within $width. It's a helper, but it's a helper with main character energy, you can absolutely call it on its own. 💅

🌸 addText 🌸

$pdf->addText($text, $hPos, $textWidth, $textHeight);

Takes $text and prints it to the current page at $hPos. You may just want to pass this function $text if the text is "pre-wrapped" and setAddTextPos has been called previously. Pass a $hPos to change the position the text will be printed on the page. Pass a $textWidth and addText will wrap the text for you. $textHeight controls the row height. Four knobs, all of them optional-ish depending on your vibe. 🎀

💜 addParagraph 💜

$pdf->addParagraph($text, $hPos, $vPos, $width, $height, $indent,
$lead);

Add $text at ($hPos, $vPos) within $width and $height, with $indent. $indent is the number of spaces at the beginning of the first line. Yes, just the first line. First-line indent only. 🧚

💖 centerString 💖

$pdf->centerString($a, $b, $yPos, $text);

Centers $text between points $a and $b at position $yPos. Be careful how much text you try to jam between those points, this function shrinks the text till it fits! fr fr, it will squeeze your text to fit. Don't put a whole novel between two points and act surprised. 😭

🌈 setRowHeight 🌈

No description given in the original. It's just here, sitting pretty, existing. Respect the mystery. ⭐

🍓 getStringWidth 🍓

$pdf->getStringWidth($String);

Returns the width of $String according to the current font and fontsize being used. So it depends on your font and size, not a fixed number. Keep that in mind. ✨

💅 addImg 💅

$pdf->addImg($file, $x, $y);

Add image $file to the current page at position ($x, $y). Simple, clean, one image, one spot. 🦋

🎀 addImgScaled 🎀

$pdf->addImgScaled($file, $x, $y, $scale);

Add image $file to the current page at position ($x, $y) scaled to $scale. Same as before but now with a size slider. 👑

⭐ setGfxLineWidth ⭐

$pdf->setGfxLineWidth($width);

Set the line width drawn on the page. Thicc lines, thin lines, your call. 💜

🦋 getGfxLineWidth 🦋

$width = $pdf->getGfxLineWidth();

Returns the current line width. Whatever you set, it tells you back. 🫶

🌸 drawLine 🌸

$pdf->drawLine($x1, $y1, $x2, $y2);

Draw a line on the current page starting at ($x1, $y1) and ending at ($x2, $y2). Start point, end point, line. We love a straight line. 🍓

💜 drawRect 💜

$pdf->drawRect($x1, $y1, $x2, $y2);

Draw a rectangle on the current page. Top left corner is represented by ($x1, $y1) and the bottom right corner is ($x2, $y2). Top-left to bottom-right, that's the mapping, don't get it twisted. 🎀

💖 shadeRect 💖

$pdf->shadeRect($x1, $y1, $x2, $y2, $color);

Shade a rectangle with $color. Top left corner is ($x1, $y1) and the bottom right corner is ($x2, $y2). Same corner rules as drawRect, but now it's filled in. Slay. ✨

Defined color-names are:

aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque,
black, blanchedalmond, blue, blueviolet, brown, burlywood,
cadetblue, chartreuse, chocolate, coral, cornflowerblue, cornsilk,
crimson, cyan, darkblue, darkcyan, darkgoldenrod, darkgray,
darkgreen, darkgrey, darkkhaki, darkmagenta, darkolivegreen,
darkorange, darkorchid, darkred, darksalmon, darkseagreen,
darkslateblue, darkslategray, darkslategrey, darkturquoise,
darkviolet, deeppink, deepskyblue, dimgray, dimgrey, dodgerblue,
firebrick, floralwhite, forestgreen, fuchsia, gainsboro, ghostwhite,
gold, goldenrod, gray, grey, green, greenyellow, honeydew, hotpink,
indianred, indigo, ivory, khaki, lavender, lavenderblush, lawngreen,
lemonchiffon, lightblue, lightcoral, lightcyan,
lightgoldenrodyellow, lightgray, lightgreen, lightgrey, lightpink,
lightsalmon, lightseagreen, lightskyblue, lightslategray,
lightslategrey, lightsteelblue, lightyellow, lime, limegreen, linen,
magenta, maroon, mediumaquamarine, mediumblue, mediumorchid,
mediumpurple, mediumseagreen, mediumslateblue, mediumspringgreen,
mediumturquoise, mediumvioletred, midnightblue, mintcream,
mistyrose, moccasin, navajowhite, navy, oldlace, olive, olivedrab,
orange, orangered, orchid, palegoldenrod, palegreen, paleturquoise,
palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue,
purple, red, rosybrown, royalblue, saddlebrown, salmon, sandybrown,
seagreen, seashell, sienna, silver, skyblue, slateblue, slategray,
slategrey, snow, springgreen, steelblue, tan, teal, thistle, tomato,
turquoise, violet, wheat, white, whitesmoke, yellow, yellowgreen

or the rgb-hex-notation:

#rgb, #rrggbb, #rrrgggbbb and #rrrrggggbbbb

or the cmyk-hex-notation:

%cmyk, %ccmmyykk, %cccmmmyyykkk and %ccccmmmmyyyykkkk

and additionally the hsv-hex-notation:

!hsv, !hhssvv, !hhhsssvvv and !hhhhssssvvvv

So like, name it, hash it, percent it, or bang it. Four whole ways to say a color. Rainbow-coded honestly. 🌈

🎀 drawPieGraph 🎀

$pdf->drawPieGraph($x, $y, $size, $rData, $rLabels);

Method to create a piegraph using a reference to an array of values. It also takes a reference to an array for labels for each data value. A legend with all the colors and labels will appear if $rLabels is passed. $x and $y are the coordinates for the center of the pie and $size is the radius. Center, radius, data ref, label ref. Boom, pie. 🥧 (well, pie chart.) 👑

⭐ getcolors ⭐

Returns list of available colours. That's it. Short king of a method. 💜

🦋 drawBarcode 🦋

$pdf->drawBarcode($x, $y, $scale, $frame, $type, $code, $extn, $umzn,
                        $lmzn, $zone, $quzn, $spcr, $ofwt, $fnsz,
$text);

This is really not that complicated, trust me! ;) I am pretty unfamiliar with barcode lingo and types so if I get any of this wrong, lemme know! This is a very flexible way to draw a barcode on your PDF document. Okay here's the full breakdown, one by one:

  • $x and $y represent the center of the barcode's position on the document.
  • $scale is the size of the entire barcode, 1 being 1:1, which is all you'll need most likely.
  • $type is the type of barcode which can be codabar, 2of5int, 3of9, code128, or ean13.
  • $code is the alpha-numeric code which the barcode will represent.
  • $extn is the extension to the $code, where applicable.
  • $umzn is the upper mending zone and $lmzn is the lower mending zone.
  • $zone is the the zone or height of the bars. (yes, "the the", it's in the original, I'm keeping it, it's canon now 😭)
  • $quzn is the quiet zone or the space between the frame and the barcode.
  • $spcr is what to put between each number/character in the text.
  • $ofwt is the overflow width.
  • $fnsz is the fontsize used for the text.
  • $text is optional text beneathe the barcode.

See? Not that complicated. Sixteen-ish arguments but they all have jobs. 💅

🌸 setFont 🌸

$pdf->setFont($font);

Creates a new font object of type $font to be used in the page. New font object, just for your page. 🎀

💜 getFont 💜

$fontname = $pdf->getFont();

Returns the font name currently being used. Current font, right now, at this moment. ⭐

💖 setSize 💖

$pdf->setSize($size);

Sets the fontsize to $size. Called before setFont(). Order matters bestie, size first, then font. Don't reverse it. 🫶

🍓 getSize 🍓

$fontsize = $pdf->getSize();

Returns the font size currently being used. Same energy as getFont but for size. ✨

💅 pages 💅

$pages = $pdf->pages();

The number of pages in the document. Count 'em. 🦋

🎀 setInfo 🎀

$pdf->setInfo(%infohash);

Sets the info structure of the document. Valid keys for %infohash: Creator, Producer, CreationDate, Title, Subject, Author, etc. Metadata moment. Put your name on it. 👑

⭐ getInfo ⭐

%infohash = $pdf->getInfo();

Gets meta-data from the info structure of the document. Valid keys for %infohash: Creator, Producer, CreationDate, Title, Subject, Author, etc. Same keys, but reading instead of writing. 💜

🦋 saveAs 🦋

Saves the document to a file.

# Save the document as "file.pdf"
my $fileName = "file.pdf";
$pdf->saveAs($fileName);

That's it, that's the whole thing. Name it, save it, done. 🍓

🌸 Finish 🌸

Returns the PDF document as text. Pass your own custom routine to do things on the footer of the page. Pass 'roman' for Roman Numeral page numbering.

# Hand the document to the web browser
print "Content-type: application/pdf\n\n";
print $pdf->Finish();

So you can hand it straight to the browser like that. Content-type first, then the document. Classic. 💅

💖 getPDFAPI2Object 💖

Object method returns underlying PDF::API2 object. For when you wanna go under the wrapper and talk to the base module directly. iykyk. ✨

💜 AUTHOR EMERITUS 💜

Andrew Orr — the legend emeritus. Respect the emeritus status. 👑

🌈 MAINTAINER 🌈

Aaron TEEJAY Trevena — current holder of the crown, keeping this thing alive. 🫶

🎀 BUGS 🎀

Please report any bugs or feature requests to "bug-calendar-model at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PDF-Report>.

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. So like, you file it, I see it, you get updates. Closed loop, no ghosting. 💖

okay bestie that's part 1, and there is more coming, so don't go anywhere, hydrate, stretch, and keep scrolling 💅✨

💖 SUPPORT 💖

okay bestie, if you ever get stuck (and you won't, you're doing amazing), the docs for this module live right at your fingertips, no cap:

and if you wanna go full detective mode, there's a whole lil network of places to peek at:

  • RT: CPAN's request tracker (report bugs here) — this is the spot to snitch on bugs, they wanna hear it fr fr

http://rt.cpan.org/NoAuth/Bugs.html?Dist=PDF-Report

  • AnnoCPAN: Annotated CPAN documentation — the docs but with the community's lil commentary sprinkled on top ✨

http://annocpan.org/dist/PDF-Report

  • CPAN Ratings — go drop your hot take, be honest but be nice 💅

http://cpanratings.perl.org/d/PDF-Report

  • METACPAN — the main character of CPAN interfaces, she has everything

https://metacpan.org/module/PDF::Report/

  • GITHUB — the source code's actual home, come thru 🫶

https://github.com/hashbangperl/perl-pdf-report

🌈 SEE ALSO 🌈

  • PDF::API2 — the icon this whole thing is built on top of, lowkey the blueprint 💜

Copyright 2008-2010 Andy Orr

Copyright 2013 Aaron Trevena

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

so basically you can remix it, share it, whatever — just respect the license terms, mkay? it's giving generous but read-the-fine-print energy 📖✨

and that's a wrap on this whole page, bestie 🎀 you just read the manual for perl v5.34.0, dated 2022-06-16, aka PDF::Report(3pm) — go forth and generate some iconic PDFs, you absolute legend 👑💖

📦 where this page comes from