NAME
   Class::PObject - Perl framework for programming persistent objects

SYNOPSIS
   After loading the Class::PObject with use, we can declare a pobject like
   so:

       pobject Person => {
           columns     => ['id', 'name', 'email'],
           datasource  => './data'
       };

   We can also declare the pobject in its own .pm file:

       package Person;
       use Class::PObject;
       pobject {
           columns     => ['id', 'name', 'email''
           datasource  => './data'
       };

   We can now create an instance of above Person, and fill it in with data,
   and store it into disk:

       $person = new Person();
       $person->name('Sherzod');
       $person->email('[email protected]');
       $new_id = $person->save()

   We can access the saved Person later, make necessary changes and save
   back:

       $person = Person->load($new_id);
       $person->name('Sherzod Ruzmetov (The Geek)');
       $person->save()

   We can load multiple objects as well:

       @people = Person->load();
       for ( $i = 0; $i < @people; $i++ ) {
           $person = $people[$i];
           printf("[%02d] %s <%s>\n", $person->id, $person->name, $person->email)
       }

   or we can load all the objects based on some criteria and sort the list
   by column name in descending order, and limit the results to only the
   first 3 objects:

       @people = Person->load(
                       {name => "Sherzod"},
                       {sort => "name", direction => "desc", limit=>3});

   We can also seek into a specific point of the result set:

       @people = Person->load(undef, {offset=>10, limit=>10});

WARNING
   This is 'alpha' release. I mainly want to hear some ideas, criticism and
   suggestions from people. Look at TODO section for more details.

DESCRIPTION
   Class::PObject is a class framework for programming persistent objects.
   Such objects can store themselves into disk, and recreate themselves
   from the disk.

   If it is easier for you, just think of a persistent object as a single
   record of a relational database:

     +-----+----------------+--------+----------+
     | id  | title          | artist | album_id |
     +-----+----------------+--------+----------+
     | 217 | Yagonam O'zing | Sevara |        1 |
     +-----+----------------+--------+----------+

   The above record of a song can be represented as a persistent object.
   Using Class::PObject, you can define a class to represent this object
   like so:

       pobject Song => {
           columns => ['id', 'title', 'artist', 'album_id']
       };

   Now you can create an instance of a Song with the following syntax:

       $song = new Song(title=>"Yagonam O'zing", artist=>"Sevara", album_id=>1);

   All the disk access is performed through its drivers, thus allowing your
   objects truly transparent database access. Currently supported drivers
   are mysql, file and csv. More drivers can be added, and I believe will
   be.

PROGRAMMING STYLE
   The style of Class::PObject is very similar to that of the Class::Struct
   manpage. Instead of exporting 'struct()', however, Class::PObject
   exports 'pobject()' function. Another visual difference is the way you
   declare the class. In Class::PObject, each property of the class is
   represented as a *column*.

 DEFINING OBJECTS

   Object can be created in several ways. You can create the object in its
   own .pm file with the following syntax:

       package Article;
       use Class::PObject;
       pobject {
           columns => ['id', 'title', 'date', 'author', 'source', 'text']
       };

   Or you can also create an in-line object - from within your programs
   with more explicit declaration:

       pobject Article => {
           columns => ['id', 'title', 'date', 'author', 'source', 'text']
       };

   Effect of the above two examples is identical - a class representing an
   Article. By default, Class::PObject will fall back to file driver if you
   do not specify any drivers. So the above Article object could also be
   redefined more explicitly like:

       pobject Article => {
           columns => \@columns,
           driver => 'file'
       };

   The above examples are creating temporary objects. These are the ones
   stored in your system's temporary location. If you want more *permanent*
   objects, you should also declare its datasource:

       pobject Article => {
           columns => \@columns,
           datasource => './data'
       };

   Now, the above article object will store its objects into data/article/
   folder. Since data storage is so dependant on the drivers, you should
   consult respective driver manuals for the details of data
   storage-related topics.

   Class declarations are tightly dependant to the type of driver being
   used, so we'll leave the rest of the declaration to specific drivers. In
   this document, we'll concentrate more on the user interface of the
   Class::PObject - something not dependant on the driver.

 CREATING NEW OBJECTS

   After you define a class using "pobject()", as shown above, now you can
   create instances of those objects. Objects are created with new() -
   constructor method. To create an instance of the above Article object,
   we do:

       $article = new Article()

   The above syntax will create an empty Article object. We can now fill
   *columns* of this object one by one:

     $article->title("Persistent Objects with Class::PObject");
     $article->date("Sunday, June 08, 2003"),
     $article->author("Sherzod B. Ruzmetov");
     $article->source("lost+found (http://author.handalak.com)");
     $article->text("CONTENTS OF THE ARTICLE GOES HERE");

   Another way of filling in objects, is by passing column values to the
   constructor - new():

       $article = new Article(title  =>  "Persistent Objects with Class::PObject",
                              date   =>  "Sunday, June 08, 2003",
                              author =>  "Sherzod Ruzmetov",
                              source =>  "lost+found (http://author.handalak.com" );

       $article->text("CONTENTS OF THE ARTICLE GO HERE");

   Notice, above example is initializing all the properties of the object
   except for *text* in the constructor, and initializing *text*
   separately. You can use any combination to fill in your objects.

 STORING OBJECTS

   Usually, when you create the objects and fill them with data, they are
   in-memory data structures, and not attached to disk. This means as soon
   as your program terminates, or your object instance exits its scope the
   data will be lost. It's when you call "save()" method on the object when
   they are stored in disk. To store the above Article, we could just say:

       $article->save();

   "save()" method returns newly created object *id* on success, undef on
   failure. So you may want to check its return value to see if it
   succeeded:

       $new_id = $article->save() or die $article->errstr;

   Note: we'll talk more about handling exceptions in later sections.

 LOADING OBJECTS

   No point of storing stuff if you can't retrieve them when you need them.
   PObjects support load() method which allows you to re-initialize your
   objects from the disk. You can retrieve objects in many ways. The
   easiest, and the most efficient way of loading an object from the disk
   is by its id:

       $article = Article->load(1251);

   the above code is retrieving an article with id 1251. You can now either
   display the article on your web page:

       printf("<h1>%s</h1>",  $article->title);
       printf("<div>By %s</div>", $article->author);
       printf("<div>Posted on %s</div>", $article->date);
       printf("<p>%s</p>", $article->text);

   or you can make some changes, say, change its title and save it back:

       $article->title("Persistent Objects in Perl made easy with Class::PObject");
       $article->save();

   Other ways of loading objects can be by passing column values, in which
   case the object will retrieve all the objects from the database matching
   your search criteria:

       @articles = Article->load({author=>"Sherzod Ruzmetov"});

   The above code will retrieve all the articles from the database written
   by "Sherzod Ruzmetov". You can specify more criteria to narrow your
   search down:

       @articles = Article->load({author=>"Sherzod Ruzmetov", source=>"lost+found"});

   The above will retrieve all the articles written by "Sherzod Ruzmetov"
   and with source "lost+found". We can of course, pass no arguments to
   load(), in which case all the objects of the same type will be returned.

   Elements of returned @array are instances of Article objects. We can
   generate the list of all the articles with the following syntax:

       @articles = Article->load();
       for my $article ( @articles ) {
           printf("[%02d] - %s - %s - %s\n",
                   $article->id, $article->title, $article->author, $article->date)
       }

   load() also supports second set of arguments used to do post-result
   filtering. Using these sets you can sort the results by any column,
   retrieve first *n* number of results, or do incremental retrievals. For
   example, to retrieve first 10 articles with the highest rating (assuming
   our Article object supports *rating* column):

       @favorites = Article->load(undef, {sort=>'rating', direction=>'desc', limit=>10});

   The above code is applying descending ordering on rating column, and
   limiting the search for first 10 objects. We could also do incremental
   retrievals. This method is best suited for web applications, where you
   can present "previous/next" navigation links and limit each listing to
   some *n* objects:

       @articles = Article->load(undef, {offset=>10, limit=>10});

   Above code retrieves records 10 through 20. The result set is not
   required to have a promising order. If you need a certain order, you
   have to specify *sort* argument with the name of the column you want to
   sort by.

       @articles = Article->load(undef, {sort=>'title', offset=>10, limit=>10});

   By default *sort* applies an ascending sort. You can override this
   behavior by defining *direction* attribute:

       @articles = Article->load(undef, {sort=>'title', direction=>'desc'});

   You can of course define both *terms* and *arguments* to load():

       @articles = Article->load({source=>'lost+found'}, {offset=>10, limit=>10, sort=>'title'});

   If you "load()" objects in array context as we've been doing above. In
   this case it returns array of objects regardless of the number of
   objects retrieved.

   If you call "load()" in scalar context, regardless of the number of
   matching objects in the disk, you will always retrieve the first object
   in the data set. For added efficiency, Class::PObject will add
   *limit=>1* argument even if it's missing.

 COUNTING OBJECTS

   Counting objects is very frequent task in many programs. You want to be
   able to display how many Articles are in a web site, or how many of
   those articles have 5 out of 5 rating.

   You can of course do it with a syntax similar to:

       @all_articles = Article->load();
       $count = scalar( @all_articles );

   But some database drivers may provide a more optimized way of retrieving
   this information using its meta-data. That's where "count()" method
   comes in:

       $count = Article->count();

   "count()" also can accept \%terms, just like above "load()" does as the
   first argument. Using \%terms you can define conditional way of counting
   objects:

       $favorites_count = Article->count({rating=>'5'});

   The above will retrieve a count of all the Articles with rating of '5'.

 REMOVING OBJECTS

   PObjects support "remove()" and "remove_all()" methods. "remove()" is an
   object method. It is used only to remove one object at a time.
   "remove_all()" is a class method, which removes all the objects of the
   same type, thus a little more scarier.

   To remove an article with *id* *1201*, we first need to create the
   object of that article by loading it:

       # we first need to load the article:
       my $article = Article->load(1201);
       $article->remove();

   remove() will return any true value indicating success, undef on
   failure.

       $article->remove() or die $article->errstr;

   "remove_all()" is invoked like so:

       Article->remove_all();

   Notice, it's a static class method.

   "remove_all()" can also be used for removing objects selectively without
   having to load them first. To do this, you can pass \%terms as the first
   argument to "remove_all()". These \%terms are the same as the ones we
   used for "load()":

       Article->remove_all({rating=>1});

 DEFINING METHODS OTHER THAN ACCESSORS

   In some cases you want to be able to extend the class with custom
   methods.

   For example, assume you have a User object, which needs to be
   authenticated before they can access certain parts of the web site. It
   may be a good idea to add "authenticate()" method into your User class,
   which either returns the User object if he/she is logged in properly, or
   returns undef, meaning the user isn't logged in yet.

   To do this we can simply define additional method, "authenticate()".
   Consider the following example:

       package User;

       pobject {
           columns     => ['id', 'login', 'psswd', 'email'],
           datasource  => 'data/users'
       };

       sub authenticate {
           my $class = shift;
           my ($cgi, $session) = @_;

           # if the user is already logged in, return the object:
           if ( $session->param('_logged_in') ) {
               return $class->load({id=>$session->param('_logged_in')})
           }

           # if we come this far, we'll try to initialize the object with CGI parameters:
           my $login     = $cgi->param('login')    or return 0;
           my $password  = $cgi->param('password') or return 0;

           # if we come this far, both 'login' and 'password' fields were submitted in the form:
           my $user = $class->load({login=>$login, psswd=>$password});

           # if the user could be loaded, we set the session parameter to his/her id
           if ( defined $user ) {
               $session->param('_logged_in', $user->id)
           }
           return $user
       }

   Now, we can check if the user is logged into our web site with the
   following code:

       use User;
       my $user = User->authenticate($cgi, $session);
       unless ( defined $user ) {
           die "You need to login to the web site before you can access this page!"
       }

       printf "<h2>Hello %s</h2>", $user->login;

   Notice, we're passing CGI and CGI::Session objects to "authenticate()".
   You can do it differently depending on the tools you're using.

 ERROR HANDLING

   *PObjects* try never to die(), and lets the programer to decide what to
   do on failure, (unless of course, you insult it with wrong syntax).

   Methods that may fail are the ones to do with disk access, namely,
   "save()", "load()", "remove()" and "remove_all()". So it's advised you
   check these methods' return values before you assume any success. If an
   error occurs, the above methods return undef. More verbose error message
   will be accessible through errstr() method. In addition, "save()" method
   should always return the object id on success:

       my $new_id = $article->save();
       unless ( defined $new_id ) {
           die "couldn't save the article: " . $article->errstr
       }

       Article->remove_all() or die "couldn't remove objects:" . Article->errstr;

MISCELLANEOUS METHODS
   In addition to the above described methods, *PObjects* also support the
   following few useful ones:

   *   "columns()" - returns hash-reference to all the columns of the
       object. Keys of the hash hold column names, and their values hold
       respective column values:

           my $columns = $article->columns();
           while ( my ($k, $v) = each %$columns ) {
               printf "%s => %s\n", $k, $v
           }

   *   "dump()" - dumps the object as a chunk of visually formatted data
       structure using standard Data::Dumper. This method is mainly useful
       for debugging.

   *   "errstr()" - class method. Returns the error message from last I/O
       operations, if any. This error message is also available through
       "$CLASS::errstr" global variable:

           $article->save() or die $article->errstr;
           # or
           $article->save() or  die $Article::errstr;

   *   "__props()" - returns *class properties*. Class properties are
       usually whatever was passed to "pobject()" as a hashref. This
       information is usually useful for driver authors only.

   *   "__driver()" - returns either already available driver object, or
       creates a new object and returns it. Although not recommended, you
       can use this driver object to access driver's low-level
       functionality, as long as you know what you are doing. For available
       driver methods consult with specific driver manual, or contact the
       vendor.

TODO
   Following are the lists of features and/or fixes that need to be applied
   before considering the library ready for production environment. The
   list is not exhaustive. Feel free to add your suggestions.

 MORE FLEXIBLE LOAD()

   load() will not be all we need until it supports at least simple
   *joins*. Something similar to the following may do:

       @articles = Article->load(join => ['ObjectName', \%terms, \%args]);

   I believe it's something to be supported by object drivers, that's where
   it can be performed more efficiently.

 GLOBAL DESCTRUCTOR

   PObjects try to cache the driver object for more extended periods than
   pobject's scope permits them to. So a *global desctuctor* should be
   applied to prevent unfavorable behaviors, especially under persistent
   environments, such as mod_perl or GUI.

   Global variables that *may* need to be cleaned up are:

   $Class::PObject::Driver::$drivername::__O
       Where "$drivername" is the name of the driver used. If more than one
       driver is used in your project, more of these variables may exist.
       This variable holds particular driver object.

   $PObjectName::props
       Holds the properties for this particular PObject named
       "$PObjectName". For example, if you created a pobject called
       *Article*, then it's properties are stored in global variable
       "$Aritlce::props".

   For example, if our objects were using just a mysql driver, in our main
   application we could've done something like:

       END {
           $Class::PObject::Driver::mysql::__O = undef;
       }

DRIVER SPECIFICATIONS
   the Class::PObject::Driver manpage, the Class::PObject::Driver::DBI
   manpage

SEE ALSO
   the Class::PObject manpage, the Class::PObject::Driver manpage, the
   Class::PObject::Driver::DBI manpage, the Class::PObject::Driver::csv
   manpage, the Class::PObject::Driver::mysql manpage, the
   Class::PObject::Driver::file manpage

AUTHOR
   Sherzod B. Ruzmetov, <[email protected]>, http://author.handalak.com/

COPYRIGHT AND LICENSE
   Copyright 2003 by Sherzod B. Ruzmetov.

   This library is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.