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.