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.

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.