NAME

PApp::DataRef - reference data stored in scalars, databases...

SYNOPSIS

use PApp::DataRef;

DESCRIPTION

You often want to store return values from forms (e.g. "editform" in macro) or other "action at a distance" events in your state variable or in a database (e.g. after updates). The DBIx::Recordset provides similar functionality.

PApp::DataRef provides the means to create "handles" that can act like normal perl references. When accessed they fetch/store data from the underlying storage.

All of the generated references and handles can be serialized.

$hd = new PApp::DataRef 'DB_row', table => $table, where => [key, value], ...;

Create a new handle to a table in a SQL database. table is the name (view) of the database table. The handle will act like a reference to a hash. Accessing the hash returns references to tied scalars that can be read or set (or serialized).

my $hd = new PApp::DataRef 'DB_row', table => env, where => [name => 'TT_LIBDIR'];
print ${ $hd->{value} }, "\n";
${ $hd->{value} } = "new libdir value";

The default database handle ($PApp::SQL::DBH) is used for all sql accesses. (Future versions might be more intelligent).

As a special case, if the value part of the where agruments is undef, it will be replaced by some valid (newly created) id on the first STORE operation. This currently only works for mysql ;*)

Parameters

table         the database table to use
where         a array-ref with the primary key fieldname and primary key
              value

autocommit    if set to one (default) automatically store the contents
              when necessary or when the object gets destroyed
delay         if set, do not write the table for each update
              (delay implies caching of stored values(!))
cache         if set, cache values that were read
preload       if set to a true value, preloads the values from the table on
              object creation. If set to an array reference, only the mentioned
              fields are being cached.

$hd = new PApp::DataRef 'File', path => ..., perm => ...;

Create a new handle that fetches and stores a file. NYI.

$hd->{fieldname} or $hd->{[fieldname, extra-args]}

Return a reference to the given field of the row. The optional arguments fetch and store can be given code-references that are called at every fetch and store, and should return their first argument (possibly modified), e.g. to fetch and store a crypt'ed password field:

my $pass_fetch = register_callback { "" };
my $pass_store = register_callback { crypt $_[1], <salt> };

$hd->refer("password", fetch => $pass_fetch->(), store => $pass_store->());

Additional named parameters are:

fetch => coderef($self, $value) => value
store => coderef($self, $value) => value

   Functions that should be called with the fetched/to-be-stored value
   as second argument that should be returned, probably after some
   transformations have been used on it. This can be used to convert
   sql-sets or password fields from/to their internal database format.

   If the store function returns nothing (an empty 'list', as it is
   called in lsit context), the update is being skipped.

   L<PApp::Callback> for a way to create serializable code references.

filter => <predefined filter name>
   
   PApp::DataRef::DB_row predefines some filter types:

      sql_set   converts strings of the form a,b,c into array-refs and
                vice versa.

      password  returns the empty string and crypt's the value if nonempty.

$hd->flush

Flush all pending store operations.

$hd->discard

Discard all pending store operations. Only sensible when delay = 1>.

BUGS

- requires mysql auto_increment feature for auto-insertions.

SEE ALSO

PApp.

AUTHOR

Marc Lehmann <pcg@goof.com>
http://www.goof.com/pcg/marc/