=head1 NAME

  Class::DBI - Simple SQL-based object persistance


=head1 SYNOPSIS

  package Film;
  use base qw(Class::DBI);
  use public qw( Title Director Rating NumExplodingSheep );

  # Tell Class::DBI a little about yourself.
  Film->table('Movies');
  Film->columns('Primary', 'Title');
  Film->set_db('Main', 'dbi:mysql', 'me', 'noneofyourgoddamnedbusiness');


  #-- Meanwhile, in a nearby piece of code! --#
  use Film;

  # Create a new film entry for Bad Taste.
  $btaste = Film->new({ Title       => 'Bad Taste',
                        Director    => 'Peter Jackson',
                        Rating      => 'R',
                        NumExplodingSheep   => 1
                      });
  
  # Retrieve the 'Gone With The Wind' entry from the database.
  my $gone = Film->retrieve('Gone With The Wind');
  
  # Shocking new footage found reveals bizarre Scarlet/sheep scene!
  $gone->NumExplodingSheep(5);
  $gone->Rating('NC-17');
  $gone->commit;

  # Grab the 'Bladerunner' entry.
  my $blrunner = Film->retrieve('Bladerunner');

  # Make a copy of 'Bladerunner' and create an entry of the director's
  # cut from it.
  my $blrunner_dc = $blrunner->copy("Bladerunner: Director's Cut");

  # Ishtar doesn't deserve an entry anymore.
  Film->retrieve('Ishtar')->delete;

  # Find all films which have a rating of PG.
  @films = Film->search('Rating', 'PG');

  # Find all films which were directed by Bob
  @films = Film->search_like('Director', 'Bob %');


=head1 DESCRIPTION

I hate SQL.  You hate SQL.  We all hate SQL.  Alas, we often find the
need to make our objects persistant and like it or not an SQL database
is usually the most flexible solution.

This module is for setting up a reasonably efficient, reasonably
simple, reasonably extendable persistant object with as little SQL and
DBI knowledge as possible.

Its a subclass of Class::Accessor and uses that scheme to
automatically set up accessors for each public data field in your
class.  These accessors control access to the underlying database.

=head2 How to set it up

Here's a fairly quick set of steps on how to make your class
persistant.  More details about individual methods will follow.

=over 4

=item I<Set up a database.>

You must have an existing database set up, have DBI.pm installed and
the necessary DBD:: driver module for that database.  See L<DBI> and
the documentation of your particular database for details.

=item I<Set up a table for your objects to be stored in.>

Class::DBI works on a simple one class/one table model.  It is
your responsibility to set up that table, automating the process would
introduce too many complications.

Using our Film example, you might declare a table something like this:

  CREATE TABLE Movies (
         Title      VARCHAR(255)    PRIMARY KEY,
         Director   VARCHAR(80),
         Rating     CHAR(5),    /* to fit at least 'NC-17' */
         NumExplodingSheep      INTEGER
  )

=item I<Inherit from Class::DBI.>

It is prefered that you use base.pm to do this rather than appending
directly to @ISA as your class may have to inherit some protected data
fields from Class::DBI and this is important if you're using
pseudohashes.

  package Film;
  use base qw(Class::DBI);

=item I<Declare your public data members.>

This can be done using fields.pm or public.pm.  The names of your
fields should match the columns in your database, one to one.
Class::DBI (via Class::Accessor) will use this
information to determine how to create accessors.

  use public qw( Title Director Rating NumExplodingSheep );

=item I<Declare the name of your table>

Inform Class::DBI what table you will be storing your objects
in.  This is the table you set up eariler.

  Film->table('Movies');

=item I<Declare which field is your primary key>

One of your fields must be a unique identifier for each object.  This
will be the primary key in your database.  Class::DBI needs
this piece of information in order to construct the proper SQL
statements to access your stored objects.

  Film->columns('Primary', 'Title');

=item I<Declare a database connection>

Class::DBI needs to know how to access the database.  It does
this through a DBI connection which you set up.  Set up is by calling
the set_db() method and declaring a database connection named 'Main'.

  Film->set_db('Main', 'dbi:mysql', 'user', 'password');

set_db() is inherited from Ima::DBI.  See that module's man page for
details.

=item I<Done.>

All set!  You can now use the constructors (new(), copy() and
retrieve()) destructors (delete()) and all the accessors and other
garbage provided by Class::DBI.  Make some new objects and
muck around a bit.  Watch the table in your database as your object
does its thing and see things being stored, changed and deleted.

=back

Is it not nifty?  Worship the module.


=head1 AUTHOR

Michael G Schwern <schwern@pobox.com> with much late-night help from
Uri Gutman

WHAT IS THIS?

This is Class::DBI, a perl module.  Please see the README that comes with
this distribution.

HOW DO I INSTALL IT?

To install this module, cd to the directory that contains this README
file and type the following:

   perl Makefile.PL
   make
   make test
   make install

To install this module into a specific directory, do:
   perl Makefile.PL PREFIX=/name/of/the/directory
   ...the rest is the same...

Please also read the perlmodinstall man page, if available.