NAME

Persistence::Object::Simple - Object Persistence with Data::Dumper.

SYNOPSIS

  use Persistence::Object::Simple; 
  my $perobj = new Persistence::Object::Simple ( __Fn   => $filename ); 
  my $perobj = new Persistence::Object::Simple ( __Dope => $directory ); 
  my $perobj = new Persistence::Object; 
  my $perobj->commit (); 

DESCRIPTION

The Class provides persistence to its objects. Object definitions are stored as stringified Perl data structures generated with Data::Dumper. These definitions are suitable for manual editing, network transfers, as well external processing of object data. (from outside the class interface.)

The Class provides persistence to a blessed hash container that holds the object data. (This may change later if I decide to attach object data to the reference using '~' magic.) The associative array container can store objects based on other data structures as well. See "Inheriting Persistence::Object::Simple", "Non-OO Usage" and the Persistent list class example (examples/Plist.pm).

CONSTRUCTOR

new()

Creates a new Persistent Object or retrieves an existing object. Takes a hash argument with following possible keys:

__Fn

Pathname of the file that contains the persistent object definition. This filename is also the object identifier and required at object retrieval.

__Dope

The Directory of Persistent Entities. If a directory name is provided new() generates a filename of the object and prepends this directory name to it. The pathname is the identifier of this new object. This argument is ignored if __Fn is present.

• When new() is invoked without any arguments it uses the default directory, "/tmp", to store the object definition. The default directory can be set with the dope() method. When the __Fn value is not provided, new() generates a unique filename in the specified/default directory of persistence.

   $po = new Persistence::Object::Simple 
         ( __Fn => "/tmp/codd/suse5.2.codd" ); 
  
   # -- generates a unique filename  in /tmp/codd
   $po  = new Persistence::Object::Simple
         ( __Dope => "/tmp/codd" );     
   print $po->{ __Fn }; 
  
   # -- generates a unique filename in defalt dope (/tmp)
   $po  = new Persistence::Object::Simple; 
   print $po->{ __Fn }; 
         

METHODS

commit()

Commits the object to disk. Like new() it takes __Fn and __Dope arguments, but __Dope takes precedence. When a __Dope argument is provided, the directory portion of the object filename is ignored and the object is stored in the specified directory.

    $perobj->commit (); 
    $perobj->commit (  __Fn   => $foo ); 
    $perobj->commit (  __Dope => $bar ); 

Commit() can also store non-object data refs. See "Non-OO Usage".

expire()

Irrevocably destructs the object. Removes the persistent entry from the DOPE.

    $perobj->expire (); 

If you want to keep a backup of the object before destroying it, use commit() to store in a different location. Undefing $obj->{ __Fn } before committing will force commit() to generate a unique filename in the new directory for storing the definition.

    $perobj->{ __Fn } = undef; 
    $perobj->commit ( __Dope => "/tmp/dead" ); 
    $perobj->expire (); 

move()

Move the object to a different directory.

    $perobj->move ( __Dope => "/some/place/else" ); 

lock()

Get an exclusive lock. The owner of the lock can commit() without unlocking.

    $perobj->lock (); 

unlock()

Release the lock.

    $perobj->unlock ();

dumper()

Returns the Data::Dumper instance bound to the object. Should be called before commit() to change Data::Dumper behavior.

    my $dd = $perobj->dumper (); 
    $dd->purity (1); 
    $dd->terse  (1);  # -- smaller dumps. 
    $perobj->commit (); 

See Data::Dumper.

load()

Class method that retrieves and builds the object. Takes a filename argument. Don't call this directly, use new () for object retrieval.

    Persistence::Object::Simple->load ( 
        __Fn => '/tmp/dope/myobject' 
    ); 

Inheriting Persistence::Object::Simple

In most cases you would want to inherit this module. It does not provide instance data methods so the object data functionality must be entirely provided by the inheriting module. Moreover, if you use your objects to store refs to class data, you'd need to bind and detach these refs at load() and commit(). Otherwise, you'll end up with a separate copy of class data with every object which will eventually break your code. See perlobj, perlbot, and perltoot, on why you should use objects to access class data.

Persistence::Database inherits this module to provide a transparently persistent database class. It overrides new(), load() and commit() methods. There is no class data to bind/detach, but load() and commit() are overridden to serve as examples/templates for derived classes. Data instance methods, AUTOLOADed at runtime, automatically commit() when data is stored in Instance Variables. For more details, Read The Fine Sources.

Non-OO Usage

load() and commit() can be used for storing non-object references. Here's a section from examples/pdataref:

 @list = 0..100; 
 Persistence::Object::Simple::commit 
  ( undef, __Fn => '/tmp/datarefs/numbers', 
    Data => \@list; 
  ); 

 $list = Persistence::Object::Simple::load 
  ( undef, __Fn => '/tmp/datarefs/numbers' ); 

 $" = "\n"; print "@$list"; 

SEE ALSO

Data::Dumper(3), Persistence::User(3), perl(1).

AUTHOR

Vipul Ved Prakash, mail@vipul.net

COPYRIGHT

Copyright (c) 1998, Vipul Ved Prakash. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.