PDF::FDF::Simple(3pm)

📦
version 0.21 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

🌸 PDF::FDF::Simple 🌸

okay bestie, sit down, hydrate, because today we're learning PDF::FDF::Simple — that's the whole name, that's the vibe, she's a Perl module and she reads and writes FDF files. yes, Acrobat FDF files. no, I will not be normal about it. 💖

✨ NAME ✨

PDF::FDF::Simple — read and write (Acrobat) FDF files. that's it, that's the girl. periodt. 💅

🎀 SYNOPSIS 🎀

here's the whole flex in one go, look at her:

my $fdf = new PDF::FDF::Simple ({ filename => '/tmp/test.fdf' });
$fdf->skip_undefined_fields (1);
$fdf->content ({
                'name'                 => 'Fred Madison',
                'organisation'         => 'Luna Lounge Ltd.',
                'dotted.field.name'    => 'Hello world.',
                'language.radio.value' => 'French',
                'my.checkbox.value'    => 'On',   # 'On' / 'Off'
               });
$fdf->save or print $fdf->errmsg;
$fdf->save ('otherfile.fdf');
my $fdfcontent = $fdf->load;
$fdfcontent = $fdf->load ($fdfstring);
print $fdf->{'organisation'};
print $fdf->{'dotted.field.name'};
print $fdf->as_string;
print "Corresponding PDF (attribute /F): ".$fdf->attribute_file."\n";
print "IDs (attribute /ID): ";
print $_ foreach @{$fdf->attribute_id}; print "\n";

like?? she does everything. creating, loading, saving, stringifying, the whole main character arc. 👑

🦋 DESCRIPTION 🦋

so what does she actually do? she helps you create and extract the content of FDF files. she's meant to be a simple replacement for the Adobe FdfToolkit — and because of that, some of her behavior is orientated on how FdfToolkit handles stuff, especially the way she deals with all those diverse whitespace/newline artefacts. (whitespace drama is real and she does not engage.) 💀

after the extraction process, the content is available within a hash reference. cute, convenient, iconic.

for creating FDF files, she currently only supports setting text values. and honestly? that should be enough, because it's enough to create FDF files for text fields, text areas, checkboxes and radio buttons. slay.

PDF::FDF::Simple uses Parse::RecDescent and understands both the "Kids" notation and the "dotted" notation for field names. saving, though? saving will always use the "dotted"- notation. no cap. 💅

🌈 Text fields / Text areas

text fields and text areas are simply filled with the given text. that's the whole thing. so easy it's giving effortless. ✨

📻 Radio button groups

in a radio button group, the entry that matches exactly the field value is selected. the entries and their values are defined in the PDF where the FDF is loaded into — so like, not her business, she just matches. 💖

☑️ Checkboxes

in the PDF document into which the FDF is loaded, a checkbox field is set to checked/unchecked with field values 'On' or 'Off', respectively. two options, no in-between, she's decisive. 🎀

💅 API Methods 💅

the ones you're actually gonna call, bestie. this is the good stuff.

🌟 new

constructor. takes a hash reference for arguments. that's the whole introduction, she's lowkey mysterious. 💜

🌟 skip_undefined_fields

option, default is 0. if you set it to a true value (like, say, 1), then fields whose value is undefined are not contained in the generated fdf. by default though, undefined field values get converted to an empty string (''). so pick your fighter. 🫶

🌟 filename

get/set the target filename (string). simple. clean. does what it says. ✨

🌟 content

get/set content of fields (hashref). the whole bag of field values, right there. 🎀

🌟 attribute_file

get/set the corresponding PDF filename of the form. this method corresponds to the /F attribute in FDF content. iykyk. 💖

🌟 attribute_ufile

get/set the corresponding PDF filename of the form. this method corresponds to the /UF attribute in FDF content.

okay so real talk: it is not perfectly clear whether the /UF means the same as /F. it was used when Acrobat 8 appeared, but it seems to be not documented. the author named it just "ufile" due to lack of better knowledge — and honestly? relatable. we've all been there. 🙈

🌟 attribute_id

get/set the list (array reference) of form IDs. this method corresponds to the /ID attribute in FDF content. plural energy, she's a list. ⭐

🌟 load

load an existing FDF file named via filename and stores the information in a hashref (see also content).

you can also hand her an optional parameter that contains FDF content — in that case, it is not read from the file filename. flexible queen. 🦋

🌟 save (optional_filename)

save the FDF content into a file, using either the directly given optional_filename parameter, or — if optional_filename is not given — the filename that was set via filename. either way, she's writing. 📝

🌟 as_string

returns the FDF content as a scalar string, so you can work with it without the need to save into a file. no filesystem commitment, just vibes. ✨

🌟 errmsg

get/set error message. it will be set internally when an error occured. just read it, setting it is useless. like, genuinely, don't bother. she's telling you for your own good. 💀

🧚 Internal Methods 🧚

those methods are used internally and can be overwritten in derived classes. you shouldn't use them directly. hands off, bestie, this is backstage. 🎀

🔧 _pre_init

overwritable method for setting default values for initialization before overtaking constructor params. early bird behavior. 🌸

🔧 _post_init

overwritable method for setting default values for initialization after overtaking constructor params and building the Parse::RecDescent grammar. late-stage glow-up. 💜

🔧 init

takes over the values from the given constructor hash. 🫶

🔧 _fdf_header

returns a string which will be written before all field data. the opening act. 🌈

returns a string which will be written after all field data. the closing credits. ⭐

🔧 _quote

does all quoting for field value strings. she handles the quotes so you don't have to. 💅

🔧 _fdf_field_formatstr

returns a format string for use in sprintf that creates key/value pairs. yes, sprintf format string. yes, exactly like that. ✨

🔧 _map_parser_output

puts the Parse::RecDescent output from a nested hash into a simple hash and returns its reference. she flattens it, beautifully. 🎀

📋 PREREQUISITES 📋

you need these, no skipping:

  • Parse::RecDescent (VERSION 1.94)
  • Class::Accessor

that's the list. short, sweet, mandatory. 💖

🔍 A COMMENT ABOUT PARSING 🔍

for whose who are interested (yes, that's the energy, come sit with us) — the grammar doesn't implement a fully PDF or FDF specification (FDF is just a subset of PDF). the approach is rather pragmatic. it only searches for /Fields and tries to ignore the surrounding rest.

this "works for me" (TM) but it doesn't guarantee that all possible FDFs can be parsed. 😭 so if you've got a strange FDF that cannot be parsed, please send it to the author with the expected content description — or extend the parser by yourself and send a patch. either way, contribute to the ecosystem, bestie. 🫶

👑 AUTHOR 👑

  • Steffen Schwigon <ss5@renormalist.net>,
  • Tim Schreier

legends, both of them. 💜

🌐 REPOSITORY 🌐

the public repository is hosted on github. go clone her:

git clone git://github.com/renormalist/pdf-fdf-simple.git

📜 LICENSE 📜

Copyright (c) 2004 .. 2008 Steffen Schwigon. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

same terms as Perl itself, we love a permissive icon. 💖

💌 FEEDBACK 💌

the author is interested in comments/enhancements/bugreports. drop a mail to <ss5@renormalist.net> if you use this module. like actually do it, feedback is a love language. 🎀

and that's the whole page, bestie — this one shipped as perl v5.34.0, dated 2022-06-14. go forth and FDF. bye mwah 💖✨🎀🦋

📦 where this page comes from