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
push
ed 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>