/ 
SPOPS-0.37
River stage one • 2 direct dependents • 2 total dependents
/ SPOPS::Tie

NAME

SPOPS::Tie - Simple class implementing tied hash with some goodies

SYNOPSIS

# Create the tied hash
use SPOPS::Tie;
my ( %data );
my @fields = qw( first_name last_name login birth_date );
tie %data, 'SPOPS::Tie', $class, \@fields;

# Store some simple properties
$data{first_name} = 'Charles';
$data{last_name}  = 'Barkley';
$data{login}      = 'cb';
$data{birth_date} = '1957-01-19';

# Store a temporary property
$data{tmp_rebound_avg} = 11.3;

# Trigger a warning by trying to store a misspelled 
# or unknown property
$data{login_name}  = 'cb';  # 'login' is correct
$data{middle_name} = 'Amadeus'; # not in @fields list

while ( my ( $prop, $val ) = each %data ) {
 printf( "%-15s: %s\n", $prop, $val );
}

# Note that output does not include 'tmp_rebound_avg'
>first_name     : Charles
>login          : cb
>last_name      : Barkley
>birth_date     : 1957-01-19

DESCRIPTION

Stores data for a SPOPS object, and also some accompanying materials such as whether the object has been changed and any temporary variables.

Validating Object Properties

When you tie the hash, you also pass it a hashref of extra information. This can currently include the 'field' parameter.

The 'field' parameter specifies what keys may be used to access data in the hash. This is to ensure that when you set or retrieve a property it is properly spelled. For instance:

my ( %data );
my $class = 'SPOPS::User';
tie %data, 'SPOPS::Tie', $class, [ qw/ first_name last_name login / ];
$data{firstname} = 'Chucky';

would result in a message to STDERR, something like:

Error setting value for field (firstname): it is not a valid field
at my_tie.pl line 9

since you have misspelled the property, which should be 'first_name'.

If you do not pass this information, SPOPS::Tie will not do the checking for you.

Checking Changed State

You can check whether the data have changed since the last fetch by either calling the method of the SPOPS object (recommended) or asking for the '_changed' key:

# See if this object has changed
if ( $obj->{_changed} ) {
 ...do stuff...
}

# Tell the object that it has changed (force)
$obj->{_changed} = 1;

Note that this state is automatically tracked based on whether you set any property of the object, so you should never need to do this. See SPOPS for more information about the changed methods.

Tracking Temporary Variables

Note that this section only holds true if you have field-checking turned on (by passing an arrayref of fields in the 'field' key of the hashref passed as the second parameter in the tie call).

At times you might wish to keep information with the object that is only temporary and not supposed to be serialized with the object. However, the 'valid property' nature of the tied hash prevents you from storing information in properties with names other than those you pass into the initial call to tie(). What to do?

Have no fear! Simply prefix the property with 'tmp_' (or something else, see below) and SPOPS::Tie will keep the information at the ready for you:

my ( %data );
my $class = 'SPOPS::User';
tie %data, 'SPOPS::Tie', $class, [ qw/ first_name last_name login / ];
$data{first_name} = 'Chucky';
$data{last_name}  = 'Gordon';
$data{login}      = 'chuckg';
$data{tmp_inoculation} = 'Jan 16, 1981';

For as long as the hash %data is in scope, you can reference the property 'tmp_inoculation'. However, you can only reference it directly. You will not see the property if you iterate through hash using keys or each.

Storing Information for Internal Use

The final kind of information that can be stored in a SPOPS object is 'internal' information. This is similar to temporary variables, but is typically only used in the internal SPOPS mechanisms -- temporary variables are often used to store computed results or other information for display rather than internal use.

For example, the SPOPS::DBI module allows you to create validating subroutines to ensure that your data conform to some sort of specification:

push @{ $obj->{_internal_validate} }, \&ensure_consistent_date;

Most of the time you will not need to deal with this, but check the documentation for the object you are using.

METHODS

See Tie::Hash or perltie for details of what the different methods do.

TO DO

Benchmarking

We should probably benchmark this thing to see what it can do

BUGS

SEE ALSO

perltie

COPYRIGHT

Copyright (c) 2000 intes.net, inc.. 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>