GX::HTTP::Parameters

Module Version: 0.2000_01

NAME

GX::HTTP::Parameters - Container class for key / value pairs

SYNOPSIS

# Load the class
use GX::HTTP::Parameters;

# Create a new container object
$parameters = GX::HTTP::Parameters->new;

# Add a key / value pair
$parameters->add( 'customer' => 'Wile E. Coyote' );

# Get the (first) value for a key
$value = $parameters->get( 'customer' );

# Add multiple values for a key
$parameters->add( 'shopping_cart' => ( 'Birdseed', 'Rocket Laucher' ) );

# Get all values for a key
@values = $parameters->get( 'shopping_cart' );

# Parse a query string (or HTML form data)
$parameters = GX::HTTP::Parameters->parse( 'customer=Wile%20E.%20Coyote' );

# Get the container data as an URL-encoded string
print $parameters->as_string;

# Same as above
print $parameters;

DESCRIPTION

This module provides the GX::HTTP::Parameters class which extends the GX::Class::Object class.

METHODS

Constructor

new

Returns a new GX::HTTP::Parameters object.

$parameters = GX::HTTP::Parameters->new( %attributes );
Attributes:
  • encoding ( string )

    The encoding to use in parse() and as_string(), for example "utf-8" or "iso-8859-1". See Encode for a list of supported encodings.

Returns:
Exceptions:

Also see merge() and parse().

Public Methods

add

Adds the given parameter key / value pair to the container.

$parameters->add( $key, $value );
Arguments:
  • $key ( string )
  • $value ( string )

Multiple values can be passed as a list:

$parameters->add( $key, @values );
Arguments:
  • $key ( string )
  • @values ( strings )

as_string

Returns the parameter key / value pairs as an URL-encoded string of bytes.

$string = $parameters->as_string;
Returns:
  • $string ( byte string )
Exceptions:

This method uses the url_encode() function from GX::HTTP::Util internally, so spaces are encoded as "%20" (and not as "+").

clear

Empties the container and clears the encoding attribute.

$parameters->clear;

count

Returns the number of (distinct) parameter keys.

$count = $parameters->count;
Returns:
  • $count ( integer )

decode

Decodes the parameter keys / values.

$parameters->decode( $encoding );
Arguments:
  • $encoding ( string ) [ optional ]

    Defaults to encoding or, as a final fallback, to "utf8".

Exceptions:

encoding

Returns / sets the encoding to use in parse() and as_string().

$encoding = $parameters->encoding;
$encoding = $parameters->encoding( $encoding );
Arguments:
  • $encoding ( string ) [ optional ]
Returns:
  • $encoding ( string )

exists

Returns true if the specified parameter key exists, otherwise false.

$result = $parameters->exists( $key );
Arguments:
  • $key ( string )
Returns:
  • $result ( bool )

get

Returns the values associated with the given parameter key in the order they were added.

@values = $parameters->get( $key );
Arguments:
  • $key ( string )
Returns:
  • @values ( strings )

In scalar context, the first of those values is returned.

$value = $parameters->get( $key );
Arguments:
  • $key ( string )
Returns:
  • $value ( string )

keys

Returns the (distinct) parameter keys.

@keys = $parameters->keys;
Returns:
  • @keys ( strings )

merge

Adds the key / value pairs from the given GX::HTTP::Parameters objects.

$parameters->merge( @parameters );
Arguments:
Exceptions:

This method can also be used as a constructor:

$parameters = GX::HTTP::Parameters->merge( @parameters );
Arguments:
Returns:
Exceptions:

parse

Parses an URL-encoded query string (or URL-encoded HTML form data) and adds the resulting key / value pairs.

$parameters->parse( $string );
Arguments:
  • $string ( byte string )
Exceptions:

This method can also be used as a constructor:

$parameters = GX::HTTP::Parameters->parse( $string );
Arguments:
  • $string ( byte string )
Returns:
Exceptions:

remove

Removes the given key and all the values associated with it from the container.

$parameters->remove( $key );
Arguments:
  • $key ( string )

set

Same as add(), but replaces any existing values for the specified key with the ones given.

$parameters->set( $key, $value );
$parameters->set( $key, @values );

AUTHOR

Jörg A. Uzarek <uzarek@runlevelnull.de>

COPYRIGHT AND LICENSE

Copyright © 2009-2011 Jörg A. Uzarek.

This module is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License Version 3 as published by the Free Software Foundation.