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:

• $parameters ( GX::HTTP::Parameters object )

Exceptions:

• GX::Exception

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:

• GX::Exception

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:

• GX::Exception

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:

• @parameters ( GX::HTTP::Parameters objects )

Exceptions:

• GX::Exception

This method can also be used as a constructor:

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

Arguments:

• @parameters ( GX::HTTP::Parameters objects )

Returns:

• $parameters ( GX::HTTP::Parameters object )

Exceptions:

• GX::Exception

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:

• GX::Exception

This method can also be used as a constructor:

    $parameters = GX::HTTP::Parameters->parse( $string );

Arguments:

• $string ( byte string )

Returns:

• $parameters ( GX::HTTP::Parameters object )

Exceptions:

• GX::Exception

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 (c) 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.

cpanm GX

perl -MCPAN -e shell
install GX