PDF::A...:Simple(3pm)

📦
version 1.1.4u · 2 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

PDF::API2::Simple — a simplistic lil wrapper for the excellent PDF::API2 modules 💖 no cap, it's the friendly front door to a very big house.

✨ SYNOPSIS ✨

use PDF::API2::Simple;

my $pdf = PDF::API2::Simple->new(
                                 file => 'output.pdf'
                                );

$pdf->add_font('VerdanaBold');
$pdf->add_font('Verdana');
$pdf->add_page();

$pdf->link( 'http://search.cpan.org', 'A Hyperlink',
            x => 350,
            y => $pdf->height - 150 );

for (my $i = 0; $i < 250; $i++) {
     my $text = "$i - All work and no play makes Jack a dull boy";

     $pdf->text($text, autoflow => 'on');
}

$pdf->save();

okay bestie, real talk: PDF coordinates are NOT like the coordinates you're used to 🙈 The coordinate (0, 0), for example, is at the lower-left hand corner. So x still grows to the right — classic — but y grows towards the top. Yes, it's giving math class. Yes, you will get used to it. 💅

💅 METHODS 💅

🎀 new

PDF::API2::Simple->new(
            'file' => 'output.txt',
            'width' => 612,
            'height' => 792,
            'line_height' => 10,
            'margin_left' => 20,
            'margin_top' => 20,
            'margin_right' => 20,
            'margin_bottom' => 50,
            'width_right' => 0,
            'height_bottom' => 0,
            'effective_width' => 0,
            'effective_height' => 0,
            'header' => undef,
            'footer' => undef,
);

Makes you a shiny new PDF::API2::Simple instance ✨ The good strategy is to spin up a fresh object for every pdf file you wanna create. That said? It's literally up to you, bestie, live your truth. 🦋

  • file — the PDF file you want to write to. No default, this parameter is required. You gotta give it a home.
  • width — how wide the PDF is. Defaults to 612, aka the 8 1/2 x 11 US Letter width 📏
  • height — how tall the PDF is. Defaults to 792, aka the 8 1/2 x 11 US Letter height 📐
  • line_height — the standard height you want to define for lines. Default is 10.
  • margin_left — how much margin space you want on the left side. Obviously you can specify whatever coordniates you want, girl. Default is 20.
  • margin_top — how much margin space you want at the top of every page. Default is 20.
  • margin_right — how much margin space you want on the right side of every page. Default is 20.
  • margin_bottom — how much margin space you want at the bottom of every page. Default is 50.
  • width_right — a lil convenience property holding the furthest x of the page, once the margins you specified are accounted for 👑
  • height_bottom — a convenience property holding the largest "y" of the page, taking the bottom margin into account.
  • effective_width — a convenience property holding the width of the page after left and right margin have been accounted for.
  • effective_height — a convenience property holding the height of the page after the top and bottom margin have been accounted for.
  • header — this CODE reference gets called every single time a page is appended to the PDF, so you can specifiy a header for your pages 🎀
  • footer — this CODE reference gets called every time a page is ended, so you can specifiy a footer for your pages 🎀

🦋 open

PDF::API2::Simple->open(
            'open_file' => 'my_pdf.pdf',
            'open_page' => 1,              # Default is 1.
            # Any other options to new.
);

This one opens an existing PDF so you can edit it 🔥 You can toss in any other arguments that are valid for new too, and they'll get set on the resulting object. It's giving "glow up an old file" energy.

🌈 Space Management

These methods are here to help you manage the space on each page of your PDF. Space management? We love her. 💜

next_line_would_extend_page

Returns a true value if the current y minus line_height would write past the bottom margin. Basically a vibe check before you commit. 😭

would_extend_page "theoretical_y"

Returns a true value if the theoretical_y would write past the bottom margin. Hypothetical queen. 🧚

next_line

Reduces the current y by line_height. Down we go ⬇️

add_page

Closes the current page, resets the x and y values to thier default coordinates, and calls the header callback — if you specified one. This method may be called for in, such as if your autoflow text wraps over a page. 🌸

end_page

Closes the current page, and calls the footer callback, if you specified one. This method is usually called for you, so don't stress, bestie, it's got you. 🫶

💖 General Management

These methods help you manage the PDF itself. Every icon needs a manager. 💅

add_font "font_name"

This method adds a font to be used throughout the PDF. You MUST call this at least once before laying out your PDF — no font, no text, periodt. font_name is a font name, such as 'Arial', or 'Verdana'. Appending 'Bold' seems to make the text bold, as in 'VerdanaBold'. Refer to PDF::API2 for more details. 📚

You can optionally pass a font object and font size if you have loaded an external font. Look at her go:

my $font_obj = $pdf->pdf->ttfont('new_font.ttf');
$pdf->add_font('NewFont', $font_obj, '12');

Refer to PDF::API2 for the various font methods, like ttfont, available. ✨

set_font "font_name"[, "pt"]

Sets the current font by name, and optionally a font size. Mix and match, you got this. 🎀

as_string

An alias for the stringify method. Same energy, different name. 💫

stringify

Ends the current page, and returns the pdf as a string. 🧵

save ["file"]

Ends the current page, and saves the document to the file argument — or to the file you specified when instaniating the object. If no suitable file can be found to save in, a Carp::croak is emitted 🐸 (yes, an actual croak, it's dramatic but valid). Aliases for this method are saveas and save_as. ✨

⭐ Layout

These methods modify the actual layout of the PDF. Heads up: most of these methods set some internal state 👀 Most often, the last x and y are set after the rendered object.

Most times, underscores may be stripped and the arguments will still work — such as the difference between fill_color and fillcolor. The vibes are flexible, iykyk. 💅

popup "text"[, %opts]

Creates a 25x25 box at opts{x} (or the current x), opts{y} (or the current y) to represent an annotation at that point. The user can then click that icon to get the full annotation. It's giving "little mystery button" 🔍

url

This is an alias for the link method. 💖

link "url", "text"[, %opts]

Specifies a link to url, having text. %opts may contain:

  • x — the x position of the link. Defaults to x.
  • y — the y position of the link. Defaults to y.
  • limit — the amount to limit the text. This adds an ellipis (...) a few characters from the end if the text length is greater than this numerical value. Defaults to 0, which is to mean "do not limit". 🚫
  • align — which alignment you want for your text. The choices are 'left', 'center', and 'right'. Defaults to 'left'.
  • font — specifies via font name the font to use. This sets the current font.
  • font_size — specifies the font size. This sets the current font size.
  • fill_color — specifies the fill color. This sets the current fill color. 🎨
  • stroke_color — specifies the stroke color. This sets the current stroke color. 🖌️

This method returns the width of the text. 📏

text "text"[, %opts]

Renders text onto the PDF. The main event, honestly 👑

  • x — the x position of the link. Defaults to x.
  • y — the y position of the link. Defaults to y.
  • limit — the amount to limit the text. This adds an ellipis (...) a few characters from the end if the text length is greater than this numerical value. Defaults to 0, which is to mean "do not limit".
  • align — which alignment you want for your text. The choices are 'left', 'center', and 'right'. Defaults to 'left'.
  • autoflow — any value but 'off' will notify this method to use "autoflowing" heuristics to gracefully wrap your text over lines and pages. Super useful for variable length text 🌊 Note that due to laziness, this option is mutually exclusive with limit. Pick a lane, babe. 💀
  • font — specifies via font name the font to use. This sets the current font.
  • font_size — specifies the font size. This sets the current font size.
  • fill_color — specifies the fill color. This sets the current fill color.
  • stroke_color — specifies the stroke color. This sets the current stroke color.

If autoflow was not specified, this method returns the width of the text in scalar context, and the bounding box of the text in list context. In autoflow mode, this method returns nothing. Yeah, nothing. Silently. 🙈

image "src"[, %opts]

Renders an image onto the PDF 🖼️ The following image types are supported: JPG, TIFF, PNM, PNG, GIF, and PDF. Note that the module figures out the image type by file extension — so don't be weird with your file names. 😭

  • x — the x position of the link. Defaults to x.
  • y — the y position of the link. Defaults to y.
  • width — the width of the image. Defaults to 100.
  • height — the height of the image. Defaults to 100.
  • scale — amount to scale the image. Defaults to 1. (only available for PDF types) 🔍

line [, %opts]

Renders a line onto the PDF. Simple. Elegant. Iconic. 📏

  • x — the x position of the line. Defaults to x.
  • y — the y position of the line. Defaults to y.
  • to_x — the x position where to draw the line to.
  • to_y — the y position where to draw the line to.
  • fill_color — specifies the fill color. This sets the current fill color. Defaults to current_fill_color.
  • stroke_color — specifies the stroke color. This sets the current stroke color. Defaults to current_stroke_color.
  • width — specifies the width of the line. Defaults to 0.5.

rect [, %opts]

Renders a rectangle onto the PDF. Rectangles are usually drawn specifying two coordinates diagonal from each other — (5, 5) to (30, 30) for example, which would produce a 25 x 25 square. Math is mathing. ✨

  • x — the x position of the rect. Defaults to x.
  • y — the y position of the rect. Defaults to y.
  • to_x — the x position where to draw the rect to.
  • to_y — the y position where to draw the rect to.
  • stroke — a value of 'on', 'true', or 'yes' will enable the stroke. Defaults to 'on'.
  • fill — a value of 'on', 'true', or 'yes' will enable the fill. Defaults to 'off'.
  • fill_color — specifies the fill color. This sets the current fill color. Defaults to current_fill_color.
  • stroke_color — specifies the stroke color. This sets the current stroke color. Defaults to current_stroke_color.
  • width — specifies the width of the line. Defaults to 0.5.

💖 PROPERTIES 💖

Okay bestie, here's the tea ☕ — all of these are read/write, which means you can use them like $pdf->prop to read the value, or $pdf->prop('val') to set it. Iconic, right? 🫶

Gets/sets the header callback. Yes callback. Like a function. Very fancy of you. ✨

Gets/sets the footer callback. Same energy, but at the bottom, obviously. 💅

🌸 file

Gets/sets the file used to save the PDF. Fair warning bestie: it's recommended that you do not set this. Just let it be. 🙈

🌸 width

Gets/sets the width of the current page. And yeah — it's recommended that you do not set this either. Hands off, girlie. ✋

🌸 height

Gets/sets the height of the current page. Also on the "please don't touch" list. It's recommended that you do not set this. 🚫

🌸 line_height

Gets/sets the default line height. This one gets used in most space layout methods, so she's booked and busy. 👑

🌸 margin_left

Gets/sets the left margin. 🍓

🌸 margin_top

Gets/sets the top margin. ⭐

🌸 margin_right

Gets/sets the right margin. 🌈

🌸 margin_bottom

Gets/sets the bottom margin. 💜

🌸 width_right

Gets/sets the calculated value, "width" minus "margin_right". Math! We love her. 🧮

🌸 height_bottom

Gets/sets the calculated value, "height" minus "margin_bottom". More math! ✨

🌸 effective_width

Gets/sets the calculated value, "width" minus ("margin_left" plus "margin_right"). The real usable width, no cap. 💯

🌸 effective_height

Gets/sets the calculated value, "height" minus ("margin_top" plus "margin_bottom"). Same vibe, vertical. 🦋

🌸 current_page

Gets/sets the current page object. Ngl it's hard to find a good reason to set this one, but bestie… it is possible to do so. Main character energy only. 💅

🌸 pdf

Gets/sets the raw PDF::API2 object. This gives you great flexibility in your applications — like, go off, you have the whole toolbox now. 🔥

🌸 fonts

Gets/sets the array of fonts we have been storing via the add_font method. Your little font collection, bestie. 🎀

🌸 current_font

Gets/sets the current font. ✨

🌸 current_font_size

Gets/sets the current font size. ✨

🌸 current_stroke_color

Gets/sets the current stroke color. The aliases for this method are stroke_color and strokecolor. Three names, one slay. 👯

🌸 current_fill_color

Gets/sets the current fill color. The aliases for this method are fontcolor, set_font_color, font_color, fillcolor and fill_color. Ma'am has a lot of nicknames and honestly? Respect. 😭

🌸 x

Gets/sets the current x position. 📍

🌸 y

Gets/sets the current y position. 📍

🐛 BUGS / FIXES 🐛

Found a bug? Got a fix? Wanna pitch an improvement or just scream a suggestion into the void? Please mail all bug reports, fixes, improvements and suggestions to bugs -at- redtreesystems -dot- com. (Yes, written like that on purpose. Write it out properly when you actually send it, bestie. 💖)

🎀 PLUG AND LICENSE 🎀

This project belongs to Red Tree Systems, LLC — <http://www.redtreesystems.com> — but it's been placed into the public domain in the hopes that it will be educational and/or useful. So like… take it, babes, it's yours. 🌈

Red Tree Systems, LLC requests that this section be kept intact with any modification of this module, or derivitive work thereof. So keep the plug, okay? Don't be that person. 🫶

🌟 THANKS 🌟

The gratitude section, because we always thank the people who carried. 😭💖

  • Thanks to Jim Brandt for noting that the default values didn't do well with false values. 🙈
  • Thanks to Denis Evdokimov for submitting more margin-fixing goodness. 🛠️
  • Thanks to Jonathan A. Marshall for fixing a long standing margin issue, and pointing out further documentation shortcomings. 👑
  • Thanks to Jim Brandt for the open method, contributing code to add_font, and offering beer. 🍻 (beer offer noted, iconic)
  • Thanks to Pradeep N Menon and Alfred Reibenschuh for pointing out optimizaiton issues, and helping to resolve them. ⚡
  • Thanks to Simon Wistow for uncovering several bugs and offering up code. 🐛🔍
  • Thanks to Bryan Krone for pointing out our documentation shortcomings. 📝

🌈 SEE ALSO 🌈

  • PDF::API2

There is an examples folder with this dist that should help you get started — go look at it, fr fr, it's giving tutorial energy. ✨

You may contact pdfapi2simple -AT- redtreesystems _dot_ com for support on an individual or commercial basis. Bestie support line, open for business. 🫶

And that's a wrap, girlie! 🎀 This lil masterpiece is from perl v5.36.0, dated 2023-12-04 — so if you're holding an older copy, you're on the wrong version, no cap. Go forth and make beautiful PDFs, bestie, you ate. 💅✨👑

📦 where this page comes from