1CGI::Struct(3)        User Contributed Perl Documentation       CGI::Struct(3)
2
3
4

NAME

6       CGI::Struct - Build structures from CGI data
7

VERSION

9       Version 1.21
10

SYNOPSIS

12       This module allows transforming CGI GET/POST data into intricate data
13       structures.  It is reminiscent of PHP's building arrays from form data,
14       but with a perl twist.
15
16         use CGI;
17         use CGI::Struct;
18         my $cgi = CGI->new;
19         my %params = $cgi->Vars;
20         my $struct = build_cgi_struct \%params;
21

DESCRIPTION

23       CGI::Struct lets you transform CGI data keys that look like perl data
24       structures into actual perl data structures.
25
26       CGI::Struct makes no attempt to actually read in the variables from the
27       request.  You should be using CGI or some equivalent for that.
28       CGI::Struct expects to be handed a reference to a hash containing all
29       the keys/values you care about.  The common way is to use something
30       like "CGI->Vars" or (as the author does)
31       "Plack::Request->parameters->mixed".
32
33       Whatever you use should give you a hash mapping the request variable
34       names (keys) to the values sent in by the users (values).  Any of the
35       major CGIish modules will have such a method; consult the documentation
36       for yours if you don't know it offhand.
37
38       Of course, this isn't necessarily tied strictly to CGI; you could use
39       it to build data structures from any other source with similar syntax.
40       All CGI::Struct does is take one hash (reference) and turn it into
41       another hash (reference).  However, it's aimed at CGI uses, so it may
42       or may not work for something else.
43

EXAMPLES

45   Basic Usage
46         <form action="request.cgi">
47          Name:    <input type="text" name="uinfo{name}">
48          Address: <input type="text" name="uinfo{addr}">
49          Email:   <input type="text" name="uinfo{email}">
50         </form>
51
52       When filled out and submitted the data will come in to request.cgi,
53       which will use something like "CGI->Vars" to parse it out into a hash
54
55         use CGI;
56         my $cgi = CGI->new;
57         my %params = $cgi->Vars;
58
59       You'll wind up with something like
60
61         %params = (
62             'uinfo{name}'  => 'Bob',
63             'uinfo{addr}'  => '123 Main Street',
64             'uinfo{email}' => 'bob@bob.bob',
65         )
66
67       Now we use CGI::Struct to parse that out
68
69         use CGI::Struct;
70         my $struct = build_cgi_struct \%params;
71
72       and we wind up with a structure that looks more like
73
74         $struct = {
75             'uinfo' => {
76                 name  => 'Bob',
77                 addr  => '123 Main Street',
78                 email => 'bob@bob.bob',
79             }
80         }
81
82       which is much simpler to use in your code.
83
84   Arrays
85       CGI::Struct also has the ability to build out arrays.
86
87        First cousin:  <input type="text" name="cousins[0]">
88        Second cousin: <input type="text" name="cousins[1]">
89        Third cousin:  <input type="text" name="cousins[2]">
90
91       Run it through CGI to get the parameters, run through
92       "build_cgi_struct", and we get
93
94         $struct = {
95             'cousins' => [
96               'Jill',
97               'Joe',
98               'Judy'
99             ]
100         }
101
102       Of course, most CGIish modules will roll that up into an array if you
103       just call it 'cousins' and have multiple inputs.  But this lets you
104       specify the indices.  For instance, you may want to base the array from
105       1 instead of 0:
106
107        First cousin:  <input type="text" name="cousins[1]">
108        Second cousin: <input type="text" name="cousins[2]">
109        Third cousin:  <input type="text" name="cousins[3]">
110
111         $struct = {
112             'cousins' => [
113               undef,
114               'Jill',
115               'Joe',
116               'Judy'
117             ]
118         }
119
120       See also the "Auto-arrays" section.
121
122       NULL delimited multiple values
123
124       When using CGI's "->Vars" and similar, multiple passed values will wind
125       up as a "\0"-delimited string, rather than an array ref.  By default,
126       CGI::Struct will split it out into an array ref.  This behavior can by
127       disabled by using the "nullsplit" config param; see the function doc
128       below.
129
130   Deeper and deeper
131       Specifying arrays explicitly is also useful when building arbitrarily
132       deep structures, since the array doesn't have to be at the end
133
134         <select name="users{bob}{cousins}[5]{firstname}">
135
136       After a quick trip through "build_cgi_struct", that'll turn into
137       "$struct->{users}{bob}{cousins}[5]{firstname}" just like you'd expect.
138
139   Dotted hashes
140       Also supported is dot notation for hash keys.  This saves you a few
141       keystrokes, and can look neater.  Hashes may be specified with either
142       the "." or with "{}".  Arrays can only be written with "[]".
143
144       The above "select" could be written using dots for some or all of the
145       hash keys instead, looking a little Javascript-ish
146
147         <select name="users.bob.cousins[5].firstname">
148         <select name="users.bob{cousins}[5].firstname">
149         <select name="users{bob}.cousins[5]{firstname}">
150
151       of course, you wouldn't really want to mix-and-match in one field in
152       practice; it just looks silly.
153
154       Sometimes, though, you may want to have dots in field names, and you
155       wouldn't want this parsing to happen then.  It can be disabled for a
156       run of "build_cgi_struct" by passing a config param in; see the
157       function doc below.
158
159   Auto-arrays
160       CGI::Struct also builds 'auto-arrays', which is to say it turns
161       parameters ending with an empty "[]" into arrays and pushes things onto
162       them.
163
164         <select multiple="multiple" name="users[]">
165
166       turns into
167
168         $struct->{users} = ['lots', 'of', 'choices'];
169
170       This may seem unnecessary, given the ability of most CGI modules to
171       already build the array just by having multiple "users" params given.
172       Also, since "build_cgi_struct" only sees the data after your CGI module
173       has already parsed it out, it will only ever see a single key in its
174       input hash for any name anyway, since hashes can't have multiple keys
175       with the same name anyway.
176
177       However, there are a few uses for it.  PHP does this, so it makes for
178       an easier transition.  Also, it forces an array, so if you only chose
179       one entry in the list, "build_cgi_struct" would still make that element
180       in the structure a (single-element) array
181
182         $struct->{users} = ['one choice'];
183
184       which makes your code a bit simpler, since you don't have to expect
185       both a scalar and an array in that place (though of course you should
186       make sure it's what you expect for robustness).
187

FUNCTIONS

189   build_cgi_struct
190         $struct = build_cgi_struct \%params;
191
192         $struct = build_cgi_struct \%params, \@errs;
193
194         $struct = build_cgi_struct \%params, \@errs, \%conf;
195
196       "build_cgi_struct()" is the only function provided by this module.  It
197       takes as an argument a reference to a hash of parameter name keys and
198       parameter value values.  It returns a reference to a hash with the
199       fully built up structure.  Any keys that can't be figured out are not
200       present in the returned hash.
201
202       An optional array reference can be passed as the second argument, in
203       which case the array will be filled in with any warnings or errors
204       found in trying to build the structure.  This should be taken as a
205       debugging tool for the developer's eyes to parse, not a source of
206       friendly-looking warnings to hand to non-technical users or as strongly
207       formatted strings for automated error mining.
208
209       A hash reference may be supplied as a third argument for passing config
210       parameters.  The currently supported parameters are:
211
212       nodot
213           This allows you to disable processing of "." as a hash element
214           separator.  There may be cases where you want a "." as part of a
215           field name, so this lets you still use "{}" and "[]" structure in
216           those cases.
217
218           The default is false (i.e., do use "." as separator).  Pass a true
219           value (like 1) to not do so.
220
221       nullsplit
222           "CGI->Vars" and compatible functions tend to, in hash form, wind up
223           with a NULL-delimited list rather than an array ref when passed
224           multiple values with the same key.  CGI::Struct will check string
225           values for embedded "\0"'s and, if found, "split" the string on
226           them and create an arrayref.
227
228           The "nullsplit" config param lets you disable this if you want
229           strings with embedded "\0" to pass through unmolested.  Pass a
230           false value (like 0) to disable the splitting.
231
232       dclone
233           By default, CGI::Struct uses Storable's "dclone" to do deep copies
234           of incoming data structures.  This ensures that whatever changes
235           you might make to $struct later on don't change stuff in %params
236           too.  By setting dclone to a false value (like 0) you can disable
237           this, and make it so deeper refs in the data structures point to
238           the same items.
239
240           You probably don't want to do this, unless some data is so huge you
241           don't want to keep 2 copies around, or you really do want to edit
242           the original %params for some reason.
243

SEE ALSO

245       CGI, CGI::Simple, CGI::Minimal, Plack, and many other choices for
246       handling transforming a browser's request info a data structure
247       suitable for parsing.
248
249       CGI::State is somewhat similar to CGI::Struct, but is extremely tightly
250       coupled to CGI and doesn't have as much flexibility in the structures
251       it can build.
252
253       CGI::Expand also does similar things, but is more closely tied to CGI
254       or a near-equivalent.  It tries to DWIM hashes and arrays using only a
255       single separator.
256
257       The structure building done here is a perlish equivalent to the
258       structure building PHP does with passed-in parameters.
259

AUTHOR

261       Matthew Fuller, "<fullermd@over-yonder.net>"
262

BUGS

264       Please report any bugs or feature requests to "bug-cgi-struct at
265       rt.cpan.org", or through the web interface at
266       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Struct>.  I will be
267       notified, and then you'll automatically be notified of progress on your
268       bug as I make changes.
269

SUPPORTED VERSIONS

271       CGI::Struct should work on perl 5.6 and later.  It includes a
272       comprehensive test suite, so passing that should be an indicator that
273       it works.  If that's not the case, I want to hear about it so the
274       testing can be improved!
275

SUPPORT

277       You can find documentation for this module with the perldoc command.
278
279           perldoc CGI::Struct
280
281       You can also look for information at:
282
283       ·   RT: CPAN's request tracker
284
285           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Struct>
286
287       ·   AnnoCPAN: Annotated CPAN documentation
288
289           <http://annocpan.org/dist/CGI-Struct>
290
291       ·   CPAN Ratings
292
293           <http://cpanratings.perl.org/d/CGI-Struct>
294
295       ·   Search CPAN
296
297           <http://search.cpan.org/dist/CGI-Struct/>
298
300       Copyright 2010-2012 Matthew Fuller.
301
302       This software is licensed under the 2-clause BSD license.  See the
303       LICENSE file in the distribution for details.
304
305
306
307perl v5.28.0                      2012-11-24                    CGI::Struct(3)
Impressum