NAME

HTTP::Rollup - translate an HTTP query string to a hierarchical structure

SYNOPSIS

use HTTP::Rollup qw(RollupQueryString);

my $rollup = new HTTP::Rollup;

my $hashref = $rollup->RollupQueryString($query_string);

DESCRIPTION

Given input text of the format:

employee.name.first=Jane
employee.name.last=Smith
employee.address=123%20Main%20St.
employee.city=New%20York
id=444
phone=(212)123-4567
phone=(212)555-1212
@fax=(212)999-8877

Construct an output data structure like this:

  $hashref = {
    employee => {
		  name => {
			   "first" => "Jane",
			   "last" => "Smith",
			  },
		  address => "123 Main St.",
		  city => "New York"
		},
    phone => [
	       "(212)123-4567",
	       "(212)555-1212"
	     ],
    fax => [
	     "(212)999-8877"
	   ],
    id => 444
  };

This is intended as a drop-in replacement for the HTTP query string parsing implemented in CGI.pm, adding the ability to assemble a nested data structure (CGI.pm constructs purely flat structures).

e.g. given the sample input above, CGI.pm would produce:

$hashref = {
  "employee.name.first" => [ "Jason" ],
  "employee.name.last" => [ "Smith" ],
  "employee.name.address" => [ "123 Main St." ],
  "employee.name.city" => [ "New York" ],
  "phone" => [ "(212)123-4567", "(212)555-1212" ],
  "@fax"=> [ "(212)999-8877" ],
  "id" => [ 444 ]
};

If no $query_string parameter is provided, HTTP::Rollup will attempt to find the input in the same manner used by CGI.pm (the internal _query_string function is pretty much cloned from CGI.pm).

HTTP::Rollup runs under both CGI or mod_perl contexts, and from the command line (reads from @ARGV or stdin).

FEATURES

• Data nesting using dot notation

• Recognizes a list if there is more than one value with the same name

• Lists can be forced with a leading @-sign, to allow for lists that could have just one element (eliminating ambiguity between scalar and single- element list). The @ will be stripped.

FUNCTIONS

new([ FORCE_LIST => 1 ], [ DELIM => ";" ])

The FORCE_LIST switch causes CGI.pm-style behavior, as above, for backward compatibility.

The DELIM option specifies the input field delimiter. This is not auto-detected. Default is the standard ampersand, though semicolon has been proposed as a replacement to avoid conflict with the ampersand used for character entities.

Specifying "\n" for the delimiter is helpful for parsing parameters on stdin.

RollupQueryString()

Workhorse function.

AUTHOR

Jason W. May <jmay@pobox.com>

COPYRIGHT

Copyright (C) 2002-2005 Jason W. May. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.