.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "Gantry::Utils::FormMunger 3"
.TH Gantry::Utils::FormMunger 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Gantry::Utils::FormMunger \- Munges form hashes like the ones bigtop makes.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Gantry::Utils::FormMunger;
.Ve
.PP
.Vb 1
\&    my $form = ...; # make a form hash
.Ve
.PP
.Vb 1
\&    my $munger = Gantry::Utils::FormMunger->new( $form );
.Ve
.PP
.Vb 2
\&    # change properties of existing fields:
\&    $munger->clear_props( 'field_name', qw( name keys to delete) );
.Ve
.PP
.Vb 2
\&    $munger->clear_all_props( 'field_name' );
\&    # removes all keys except name
.Ve
.PP
.Vb 5
\&    $munger->set_props(
\&        'field_name',
\&        { prop => 'value', ... },
\&        $replace_props
\&    ); # modifies only the keys you pass
.Ve
.PP
.Vb 4
\&    $munger->set_props_for_fields(
\&        [ 'field1', 'field2', ... ],
\&        { prop => 'value', ... },
\&    ); # like set_props but for all listed fields
.Ve
.PP
.Vb 4
\&    $munger->set_props_except_for(
\&        [ 'skip_this_one', 'and_this_one' ],
\&        { prop => 'value', ... },
\&    ); # like set_props_for, but negated listed fields are skipped
.Ve
.PP
.Vb 1
\&    $munger->set_props_all( { prop => 'value', ... } );
.Ve
.PP
.Vb 2
\&    # get the field so you can work it yourself:
\&    my $field = $munger->get_field( 'name' );
.Ve
.PP
.Vb 2
\&    # modify the field list:
\&    my $deceased = $munger->drop_field( 'name' ); # removes it from the form
.Ve
.PP
.Vb 2
\&    $munger->append_field(  { name => 'name', ... } ); # add at end
\&    $munger->unshift_field( { name => 'name', ... } ); # add at beginning
.Ve
.PP
.Vb 2
\&    $munger->add_field_after(  'target', { name => 'name', ... } );
\&    $munger->add_field_before( 'target', { name => 'name', ... } );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is designed to simplify work with Gantry form.tt form hash
data structures.  If makes modifications to the fields array in that
hash.  Usually, bigtop generates that hash.  If you are in a standard
\&\s-1CRUD\s0 situation, the generated form is all you need.  But, if you need
to share the form in different contexts, it may be necessary to modify
it to suit those contexts.  That is what this module does.
.PP
If you want, you could even use this module to build your entire form
hash, but that might be painful.  Instead, you usually pass a form hash
to its constructor.  Usually, you get that hash from a \s-1GEN\s0 module's form
method which was generated by bigtop.
.PP
Once you have the object, you can call any of the methods below to
modify its fields array.  Most of the methods return nothing useful.
The exceptions are noted below.
.PP
All methods are instance methods unless marked.
.SH "METHODs"
.IX Header "METHODs"
.IP "new (class method)" 4
.IX Item "new (class method)"
Parameters: a form hash.  If you don't already have one try:
.Sp
.Vb 1
\&    my $munger = Gantry::Utils::FormMunger->new( { fields => [] } );
.Ve
.Sp
It is better to use one that already has fields.
.Sp
Returns: a munger object upon which you may call the rest of the methods.
.IP "clear_props" 4
.IX Item "clear_props"
Selectively removes specified properties from one field.  This is
done by using delete on the fields subhash.
.Sp
Parameters: name of field to work on, list of properties to remove from its
fields hash
.IP "clear_all_props" 4
.IX Item "clear_all_props"
Given the name of a field, this method deletes all of its properties except
its name.
.Sp
Parameters: name of field
.IP "set_props" 4
.IX Item "set_props"
Given a field name, and a list of properties, sets those properties on that
field.
.Sp
Parameters:
.RS 4
.IP "field_name" 4
.IX Item "field_name"
name of field to work on
.IP "props" 4
.IX Item "props"
hash reference of properties to assign on the field
.IP "replace" 4
.IX Item "replace"
Flag.  If true, all keys are deleted prior to application of props.
Note that you must supply a name property, or the field will have no
name and everyone Will Be Upset.
.RE
.RS 4
.RE
.IP "set_props_for_fields" 4
.IX Item "set_props_for_fields"
Like \f(CW\*(C`set_props\*(C'\fR, but works for several named fields at once.  This
is more efficient than separate calls, since the fields array is
only traversed once.
.Sp
Do not change field names with this method.  Use \f(CW\*(C`set_props\*(C'\fR for that.
Trying to use this method will leave all fields involved with the
same name, confusing everyone including this module.
.Sp
Parameters:
.RS 4
.IP "fields" 4
.IX Item "fields"
Array reference, listing fields to work on.
.IP "props" 4
.IX Item "props"
Hash reference of properties to assign on each field.
.RE
.RS 4
.RE
.IP "set_props_except_for" 4
.IX Item "set_props_except_for"
Like \f(CW\*(C`set_props_for\*(C'\fR, but you list fields to skip, instead of fields to
work on.  Every field not mentioned is affected.  The parameters
are the same as for \f(CW\*(C`set_props_for\*(C'\fR.
.Sp
Note that it is extremely unwise to consider changing field names with this
method, since that would make the field names of all fields modified
the same.
.IP "set_props_all" 4
.IX Item "set_props_all"
Like \f(CW\*(C`set_props_for\*(C'\fR, but it works on all fields.
.Sp
Note that it is extremely unwise to consider changing field names with this
method, since that would make all field names the same.
.Sp
Parameters:
.RS 4
.IP "props" 4
.IX Item "props"
Hash reference of properties to assign on each field.
.RE
.RS 4
.RE
.IP "get_field" 4
.IX Item "get_field"
Returns the subhash for a given field.
.Sp
Parameters: name of field to return
.Sp
Returns: subhash for the named field (if there is one)
.IP "drop_field" 4
.IX Item "drop_field"
Deletes a field from the fields array.
.Sp
Parameters: name of doomed field
.Sp
Returns: the hash reference for the dearly departed.
.IP "append_field" 4
.IX Item "append_field"
Adds a new field at the end of the fields array (so it will appear last
on the form).
.Sp
Parameters: a hash reference for a new field
.IP "unshift_field" 4
.IX Item "unshift_field"
Just like \f(CW\*(C`append_field\*(C'\fR, except the new field becomes the first field.
.IP "add_field_after" 4
.IX Item "add_field_after"
Adds a new field to the fields array immediately after a named field.
If the named field is not found, the new field goes at the end.
.Sp
Parameters:
.RS 4
.IP "target" 4
.IX Item "target"
Name of field immediately before new field.
.IP "props" 4
.IX Item "props"
Hash reference of props for new field.
.RE
.RS 4
.RE
.IP "add_field_before" 4
.IX Item "add_field_before"
Just like \f(CW\*(C`add_field_after\*(C'\fR, except that the new field goes immediately
before the named field.  (If the name is not found, the new field still
goes at the end.)
.SH "AUTHOR"
.IX Header "AUTHOR"
Phil Crow, <crow.phil@gmail.com<gt>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007 Phil Crow
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.