1CGI::Struct(3) User Contributed Perl Documentation CGI::Struct(3)
2
6 CGI::Struct - Build structures from CGI data
7
9 Version 1.21
10
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 use CGI;
17 use CGI::Struct;
18 my $cgi = CGI->new;
19 my %params = $cgi->Vars;
20 my $struct = build_cgi_struct \%params;
21
23 CGI::Struct lets you transform CGI data keys that look like perl data
24 structures into actual perl data structures.
25 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 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 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
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 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 use CGI;
56 my $cgi = CGI->new;
57 my %params = $cgi->Vars;
58 You'll wind up with something like
60 %params = (
62 'uinfo{name}' => 'Bob',
63 'uinfo{addr}' => '123 Main Street',
64 'uinfo{email}' => 'bob@bob.bob',
65 )
66 Now we use CGI::Struct to parse that out
68 use CGI::Struct;
70 my $struct = build_cgi_struct \%params;
71 and we wind up with a structure that looks more like
73 $struct = {
75 'uinfo' => {
76 name => 'Bob',
77 addr => '123 Main Street',
78 email => 'bob@bob.bob',
79 }
80 }
81 which is much simpler to use in your code.
83 Arrays
85 CGI::Struct also has the ability to build out arrays.
86 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 Run it through CGI to get the parameters, run through
92 "build_cgi_struct", and we get
93 $struct = {
95 'cousins' => [
96 'Jill',
97 'Joe',
98 'Judy'
99 ]
100 }
101 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 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 $struct = {
112 'cousins' => [
113 undef,
114 'Jill',
115 'Joe',
116 'Judy'
117 ]
118 }
119 See also the "Auto-arrays" section.
121 NULL delimited multiple values
123 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 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 <select name="users{bob}{cousins}[5]{firstname}">
135 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 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 The above "select" could be written using dots for some or all of the
145 hash keys instead, looking a little Javascript-ish
146 <select name="users.bob.cousins[5].firstname">
148 <select name="users.bob{cousins}[5].firstname">
149 <select name="users{bob}.cousins[5]{firstname}">
150 of course, you wouldn't really want to mix-and-match in one field in
152 practice; it just looks silly.
153 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 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 <select multiple="multiple" name="users[]">
165 turns into
167 $struct->{users} = ['lots', 'of', 'choices'];
169 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 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 $struct->{users} = ['one choice'];
183 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
189 build_cgi_struct
190 $struct = build_cgi_struct \%params;
191 $struct = build_cgi_struct \%params, \@errs;
193 $struct = build_cgi_struct \%params, \@errs, \%conf;
195 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 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 A hash reference may be supplied as a third argument for passing config
210 parameters. The currently supported parameters are:
211 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 The default is false (i.e., do use "." as separator). Pass a true
219 value (like 1) to not do so.
220 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 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 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 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
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 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 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 The structure building done here is a perlish equivalent to the
258 structure building PHP does with passed-in parameters.
259
261 Matthew Fuller, "<fullermd@over-yonder.net>"
262
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
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
277 You can find documentation for this module with the perldoc command.
278 perldoc CGI::Struct
280 You can also look for information at:
282 • RT: CPAN's request tracker
284 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Struct>
286 • AnnoCPAN: Annotated CPAN documentation
288 <http://annocpan.org/dist/CGI-Struct>
290 • CPAN Ratings
292 <http://cpanratings.perl.org/d/CGI-Struct>
294 • Search CPAN
296 <http://search.cpan.org/dist/CGI-Struct/>
298
300 Copyright 2010-2012 Matthew Fuller.
301 This software is licensed under the 2-clause BSD license. See the
303 LICENSE file in the distribution for details.
304perl v5.36.0 2023-01-20 CGI::Struct(3)