NAME

OpenInteract2::ParamContainer - Base for classes that want to hold parameters

SYNOPSIS

package My::Class:

use base qw( OpenInteract2::ParamContainer );

my %PROPERTIES = map { $_ => 1 } qw( foo bar baz );
sub get_skip_params { return %PROPERTIES }

sub new {
    my ( $class, %params ) = @_;
    my $self = bless( {}, $class );

    # assigns all values except where keys specified in 'get_skip_params()'
    $self->param_assign( \%params );
    return $self;
}

# Using the object
my $t = My::Class->new( foo => 42, var => 'a red car' );
print "Value for 'var': ", $t->param( 'var' );

# Show all parameters -- will only print 'var' value
# since 'foo' was skipped
my $params = $t->param();
while ( my ( $key, $value ) = each %{ $params } ) {
    print "$key = $value\n";
}

# overwrite
$t->param( var => 'a blue car' );

# clear (delete value and key)
$t->param_clear( 'var' );

# treat 'var' as multivalued
$t->param_add( 'var', 'a red car', 'with titanium radio' );

# get an arrayref back (scalar context)
my $value = $t->param( 'var' );

# get an array back
my @values = $t->param( 'var' );

DESCRIPTION

Simple base class for assigning and returning arbitrary parameters.

OBJECT METHODS

param( [ $key ], [ $value ] )

If neither $key nor $value given, return all parameters as a hashref.

If $key given, return its value. If $key has multiple values then the method will return an array in list context and an arrayref in scalar context.

If $value given, assign it to $key (overwriting any value previously set) and return its new value.

param_add( $key, @values )

Adds (rather than replaces) the values @values to the parameter $key. If there is a value already set for $key, or if you pass multiple values, it is turned into an array reference and @values pushed onto the end. If there is no value already set and you only pass a single value it acts like the call to param( $key, $value ).

This is useful for potential multivalued parameters, such as if you're collecting messages during a process for ultimately displaying to the user. For instance, say we want to collect error messages:

$foo->param( error_msg => "Ooops I..." );
$foo->param_add( error_msg => "did it again" );
my $full_msg = join( ' ', $foo->param( 'error_msg' ) );
# $full_msg = 'Ooops I... did it again'

$foo->param( error_msg => "Ooops I..." );          # Set to value
$foo->param_add( error_msg => "did it again" );    # ...add new value to existing
$foo->param( error_msg => 'and again' );           # ...replace the earlier values entirely
my $full_msg = join( ' ', $foo->param( 'error_msg' ) );
# $full_msg = 'and again'

$foo->param( error_msg => "Ooops I..." );
$foo->param_add( error_msg => "did it again" );
my $messages = $foo->param( 'error_msg' );
# $messages->[0] = 'Ooops I...'
# $messages->[1] = 'did it again'

Returns: Context senstive value in of $key

param_clear( $key )

Removes all parameter values defined by $key. This is the only way to remove a parameter -- using the following will not work:

$foo->param( myvar => undef );

Returns: value(s) previously set for the parameter $key, non-context sensitive.

param_assign( \%params )

Bulk assign \%params to the object. If you have keys in \%params you want to skip return them from get_skip_param() (below).

SUBCLASSING

get_skip_params()

Subclasses may define this to return a hash of parameter names that we should skip when bulk assigning them with param_assign(). The use case for this is in constructors where you can do something like:

my %PROPS = map { $_ => 1 } qw ( name address );

sub get_skip_params { return %PROPS }

sub new {
    my ( $class, %settings ) = @_;
    my $self = bless( {}, $class );
    $self->param_assign( \%settings );
    while ( my ( $key, $val ) = each %settings ) {
        next unless ( $PROPS{ $key } );
        $self->$key( $val );
    }
}

COPYRIGHT

Copyright (c) 2005 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>

cpanm OpenInteract2::URL

perl -MCPAN -e shell
install OpenInteract2::URL