.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PDF::FDF::Simple 3pm"
.TH PDF::FDF::Simple 3pm "2022-06-14" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDF::FDF::Simple \- Read and write (Acrobat) FDF files.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  my $fdf = new PDF::FDF::Simple ({ filename => \*(Aq/tmp/test.fdf\*(Aq });
\&  $fdf\->skip_undefined_fields (1);
\&  $fdf\->content ({
\&                  \*(Aqname\*(Aq                 => \*(AqFred Madison\*(Aq,
\&                  \*(Aqorganisation\*(Aq         => \*(AqLuna Lounge Ltd.\*(Aq,
\&                  \*(Aqdotted.field.name\*(Aq    => \*(AqHello world.\*(Aq,
\&                  \*(Aqlanguage.radio.value\*(Aq => \*(AqFrench\*(Aq,
\&                  \*(Aqmy.checkbox.value\*(Aq    => \*(AqOn\*(Aq,   # \*(AqOn\*(Aq / \*(AqOff\*(Aq
\&                 });
\&  $fdf\->save or print $fdf\->errmsg;
\&  $fdf\->save (\*(Aqotherfile.fdf\*(Aq);
\&  my $fdfcontent = $fdf\->load;
\&  $fdfcontent = $fdf\->load ($fdfstring);
\&  print $fdf\->{\*(Aqorganisation\*(Aq};
\&  print $fdf\->{\*(Aqdotted.field.name\*(Aq};
\&  print $fdf\->as_string;
\&  print "Corresponding PDF (attribute /F): ".$fdf\->attribute_file."\en";
\&  print "IDs (attribute /ID): ";
\&  print $_ foreach @{$fdf\->attribute_id}; print "\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Helps creating and extracting the content of \s-1FDF\s0 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.
.PP
After the extraction process the content is available within a hash
reference.
.PP
For creating \s-1FDF\s0 files it currently only supports setting text
values. Anyway, this should be enough to create \s-1FDF\s0 files for text
fields, text areas, checkboxes and radio buttons.
.PP
PDF::FDF::Simple uses Parse::RecDescent and understands both, the
\&\*(L"Kids\*(R" notation and the \*(L"dotted\*(R" notation for field names. Saving will
always use the \*(L"dotted\*(R"\- notation.
.SS "Text fields / Text areas"
.IX Subsection "Text fields / Text areas"
Text fields and text areas are simply filled with the given text.
.SS "Radio button groups"
.IX Subsection "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 \s-1PDF\s0 where
the \s-1FDF\s0 is loaded into.
.SS "Checkboxes"
.IX Subsection "Checkboxes"
In the \s-1PDF\s0 document into which the \s-1FDF\s0 is loaded a checkbox field is
set to checked/unchecked with field values 'On' or 'Off',
respectively.
.SH "API Methods"
.IX Header "API Methods"
.SS "new"
.IX Subsection "new"
Constructor. Takes a hash reference for arguments.
.SS "skip_undefined_fields"
.IX Subsection "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 ('').
.SS "filename"
.IX Subsection "filename"
Get/set target filename (string).
.SS "content"
.IX Subsection "content"
Get/set content of fields (hashref).
.SS "attribute_file"
.IX Subsection "attribute_file"
Get/set the corresponding \s-1PDF\s0 filename of the form.
This method corresponds to the /F attribute in \s-1FDF\s0 content.
.SS "attribute_ufile"
.IX Subsection "attribute_ufile"
Get/set the corresponding \s-1PDF\s0 filename of the form.  This method
corresponds to the /UF attribute in \s-1FDF\s0 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 \*(L"ufile\*(R"
due to lack of better knowledge.
.SS "attribute_id"
.IX Subsection "attribute_id"
Get/set the list (array reference) of form IDs.
This method corresponds to the /ID attribute in \s-1FDF\s0 content.
.SS "load"
.IX Subsection "load"
Load an existing \s-1FDF\s0 file named via \f(CW\*(C`filename\*(C'\fR and stores the
information in a hashref (see also \f(CW\*(C`content\*(C'\fR).
.PP
An optional parameter can be given that contains \s-1FDF\s0 content. In that
case it is not read from file \f(CW\*(C`filename\*(C'\fR.
.SS "save (optional_filename)"
.IX Subsection "save (optional_filename)"
Save the \s-1FDF\s0 content into a file, using either the directly given
\&\f(CW\*(C`optional_filename\*(C'\fR parameter or (if \f(CW\*(C`optional_filename\*(C'\fR is not
given) the filename that was set via \f(CW\*(C`filename\*(C'\fR.
.SS "as_string"
.IX Subsection "as_string"
Returns the \s-1FDF\s0 content as scalar string, so you can work with it
without the need to save into file.
.SS "errmsg"
.IX Subsection "errmsg"
Get/set error message. Will be set internally when an error
occured. Just read it, setting it is useless.
.SH "Internal Methods"
.IX Header "Internal Methods"
Those methods are used internally and can be overwritten in derived
classes. You shouldn't use them directly.
.SS "_pre_init"
.IX Subsection "_pre_init"
Overwritable method for setting default values for initialization
before overtaking constructor params.
.SS "_post_init"
.IX Subsection "_post_init"
Overwritable method for setting default values for initialization
after overtaking constructor params and building Parse::RecDescent
grammar.
.SS "init"
.IX Subsection "init"
Takes over the values from the given constructor hash.
.SS "_fdf_header"
.IX Subsection "_fdf_header"
Returns a string which will be written before all field data.
.SS "_fdf_footer"
.IX Subsection "_fdf_footer"
Returns a string which will be written after all field data.
.SS "_quote"
.IX Subsection "_quote"
Does all quoting for field value strings.
.SS "_fdf_field_formatstr"
.IX Subsection "_fdf_field_formatstr"
Returns a format string for use in sprintf that creates key/value
pairs.
.SS "_map_parser_output"
.IX Subsection "_map_parser_output"
Puts the Parse::RecDescent output from a nested hash into a simple
hash and returns its reference.
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
.IP "\(bu" 4
Parse::RecDescent (\s-1VERSION 1.94\s0)
.IP "\(bu" 4
Class::Accessor
.SH "A COMMENT ABOUT PARSING"
.IX Header "A COMMENT ABOUT PARSING"
For whose who are interested, the grammar doesn't implement a fully
\&\s-1PDF\s0 or \s-1FDF\s0 specification (\s-1FDF\s0 is just a subset of \s-1PDF\s0). The approach
is rather pragmatic. It only searches for /Fields and tries to ignore
the surrounding rest. This \*(L"works for me\*(R" (\s-1TM\s0) but it doesn't
guarantee that all possible FDFs can be parsed. If you have a strange
\&\s-1FDF\s0 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
.IP "\(bu" 4
Steffen Schwigon <ss5@renormalist.net>,
.IP "\(bu" 4
Tim Schreier
.SH "REPOSITORY"
.IX Header "REPOSITORY"
The public repository is hosted on github:
.PP
.Vb 1
\&  git clone git://github.com/renormalist/pdf\-fdf\-simple.git
.Ve
.SH "LICENSE"
.IX Header "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.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
I am interested in comments/enhancements/bugreports. Drop me
<ss5@renormalist.net> a mail if you use this module.