oracular (3) PDF::FDF::Simple.3pm.gz
NAME
PDF::FDF::Simple - Read and write (Acrobat) FDF files.
SYNOPSIS
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";
DESCRIPTION
Helps creating and extracting the content of FDF files. It is meant to be a simple replacement for the
Adobe FdfToolkit. Therefore some of it's behavior, especially handling of diverse whitespace/newline
artefacts is orientated on FdfToolkit's handling.
After the extraction process the content is available within a hash reference.
For creating FDF files it currently only supports setting text values. Anyway, this should be enough to
create FDF files for text fields, text areas, checkboxes and radio buttons.
PDF::FDF::Simple uses Parse::RecDescent and understands both, the "Kids" notation and the "dotted"
notation for field names. Saving will always use the "dotted"- notation.
Text fields / Text areas
Text fields and text areas are simply filled with the given text.
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.
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.
API Methods
new
Constructor. Takes a hash reference for arguments.
skip_undefined_fields
Option, default is 0. If set to a true value (e.g., 1), then fields whose value is undefined are not
contained in generated fdf. By default undefined field values are converted to empty string ('').
filename
Get/set target filename (string).
content
Get/set content of fields (hashref).
attribute_file
Get/set the corresponding PDF filename of the form. This method corresponds to the /F attribute in FDF
content.
attribute_ufile
Get/set the corresponding PDF filename of the form. This method corresponds to the /UF attribute in FDF
content. 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. I named it just "ufile" due to lack of better knowledge.
attribute_id
Get/set the list (array reference) of form IDs. This method corresponds to the /ID attribute in FDF
content.
load
Load an existing FDF file named via "filename" and stores the information in a hashref (see also
"content").
An optional parameter can be given that contains FDF content. In that case it is not read from file
"filename".
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".
as_string
Returns the FDF content as scalar string, so you can work with it without the need to save into file.
errmsg
Get/set error message. Will be set internally when an error occured. Just read it, setting it is useless.
Internal Methods
Those methods are used internally and can be overwritten in derived classes. You shouldn't use them
directly.
_pre_init
Overwritable method for setting default values for initialization before overtaking constructor params.
_post_init
Overwritable method for setting default values for initialization after overtaking constructor params and
building Parse::RecDescent grammar.
init
Takes over the values from the given constructor hash.
_fdf_header
Returns a string which will be written before all field data.
_fdf_footer
Returns a string which will be written after all field data.
_quote
Does all quoting for field value strings.
_fdf_field_formatstr
Returns a format string for use in sprintf that creates key/value pairs.
_map_parser_output
Puts the Parse::RecDescent output from a nested hash into a simple hash and returns its reference.
PREREQUISITES
• Parse::RecDescent (VERSION 1.94)
• Class::Accessor
A COMMENT ABOUT PARSING
For whose who are interested, 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.
If you have a strange FDF that cannot be parsed please send it to me with the expected content
description or extend the parser by yourself and send me a patch.
AUTHOR
• Steffen Schwigon <ss5@renormalist.net>, • Tim Schreier
REPOSITORY
The public repository is hosted on github:
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.
FEEDBACK
I am interested in comments/enhancements/bugreports. Drop me <ss5@renormalist.net> a mail if you use this module.