NAME

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

SYNOPSIS

use PApp::DataRef;

DESCRIPTION

You often want to store return values from HTML 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.
key           a string or arrayref containing the (primary) key fields.
id            a scalar or araryref giving the values for the key.

where         [deprecated but supported] 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. Implies C<cache => 1>.
database      the PApp::SQL::Database object to use. If not specified,
              the default database at the time of the new call is used.
insertid      when set to true, makes this object allocate sequences using
              sql_insertid.
sequence      (use insertid) when set to one and the (single) key id is C<undef>
              or C<zero>, use sql_insertid to allocate a new one (will be extended
              to handle the case where no id is given, in which case this parameter
              describes how to allocate a new id).
utf8          can be set to a boolean, an arrayref or hashref that decides
              wether to force the utf8 bit on or off for the selected fields.

$hd = new $dataref arg => value, ...

Instead of specifying all the same parameters again and again, you can create a partial DataRef object (e.g. one without an id) with default parameters and use this form of the method invocation to "specialise", e.g.

my $template = new PApp::DataRef 'DB_row', table => "message", key => "id";

for (1,2,3) {
   my $row = $template->new(id => $_);
   ...
}

$hd = new PApp::DataRef 'Scalar', fetch => ..., ...

Create a scalar reference that calls your callbacks when accessed. Valid arguments are:

fetch => coderef($self)          # ref not present
fetch => coderef($self, $value)  # ref present
  A coderef which is to be called for every read access

value => constant
  As an alternative to fetch, always return a constant on read accesses

ref => scalar-ref
  When present, this references the scalar that is passed to the fetch
  method or overwritten by the store method.

store => coderef($value, $value) # ref not present (first argument is DEPRECATED)
store => coderef($self, $value)  # ref present
  A coderef which is to be called with the new value for every write
  access. If ref is given, the new value should be returned from this
  callback. If the callback returns the empty list, the value won't be
  changed.

For read access, either fetch, value or ref must be present (they are checked in this order). If store is missing, stored values are thrown away.

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

Return a lvalue 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 = create_callback { "" };
my $pass_store = create_callback { crypt $_[1], <salt> };

$hd->{["password", fetch => $pass_fetch, store => $pass_store]};

Additional named parameters are:

fetch => $fetch_cb,
store => $store_cb,
   
   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 list context), the update is being skipped.

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

   PApp::DataRef::DB_row predefines some filter types (these functions
   return four elements, i.e. fetch => xxx, store => xxx, so that you
   can just cut & paste them).

      PApp::DataRef::DB_row::filter_sql_set
                converts strings of the form a,b,c into array-refs and
                vice versa.

      PApp::DataRef::DB_row::filter_password
                returns the empty string and crypt's the value if nonempty.

      PApp::DataRef::DB_row::filter_sfreeze_cr
                filters the data through Compress::LZF's sfreeze_cr and sthaw.

@key = $hd->id

Returns the key value(s) for the selected row, creating it if necessary.

$hd->flush

Flush all pending store operations. See HOW FLUSHES ARE IMPLEMENTED below to see how, well, flushes are implemented on the SQL-level.

$hd->dirty

Return true when there are store operations that are delayed. Call flush to execute these.

$hd->invalidate

Empties any internal caches. The next access will reload the values from the database again. Any dirty values will be discarded.

$hd->discard

Discard all pending store operations. Only sensible when delay is true.

$hd->delete

Delete the row from the database

How Flushes are Implemented

When a single value (delay => 0) is being read or written, DataRef creates a single access:

SELECT column FROM table WHERE id = ?
UPDATE table SET column = ? where id = ?

In other cases, DataRef reads and writes full rows:

SELECT * FROM table WHERE id = ?

When a row is being written and the id is undef or zero, DataRef uses the insertid callback to create a new insertion id followed by an INSERT (if insretid is 1, it uses an INSERT followed by sql_insertid, so your id volumn should better be defined as auto increment in your database). If the id is defined, the update is driver specific:

for mysql (if appropriate):

REPLACE INTO table (...) VALUES (...)

and for other databases:

INSERT INTO table (...) VALUES (...)
and, if the above commend fails,
UPDATE table SET ? = ?, ? = ?, ... WHERE id = ?

no checking wether the UPDATE succeeded is done (yet).

SEE ALSO

PApp.

AUTHOR

Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/