OpenInteract2 Documentation: OpenInteract2::ParamContainer

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

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>

Generated from the OpenInteract 1.99_06 source.