NAME
    ORMesque - Lightweight To-The-Point ORM

VERSION
    version 1.110422

SYNOPSIS
        my $db = ORMesque->new('dbi:mysql:foo', 'root');
        
    my $ta = $db->table_a
                ->page(1, 25)
                ->read({ column => 'value' });
        
    my $tb = $db->table_b
                ->page(1, 25)
                ->read({ column => 'value' });
        
    return $ta->join($tb); # returns an aggregated arrayref of hashefs

    ORMesque is a lightweight ORM supporting any database listed under
    ORMesque::SchemaLoader making it a great alternative when you don't have
    the time, need or desire to learn/utilize DBIx::Class or the like.
    ORMesque is an object relational mapper that provides a database
    connection to the database of your choice and automatically creates
    objects and accessors for that database and its tables and columns.
    ORMesque uses SQL::Abstract querying syntax. More usage examples...

        my $db = ORMesque->new($dsn);
        
    my $user = $db->users;
        
    # Grab the first record, not neccessary if operating on only one record
        
    $user->read;
        
    # SQL::Abstract where clause passed to the "read" method
        
    $user->read({
            'column' => 'query'
        });
        
    $user->first;
        $user->last;
        
    # How many records in collection
        
    $user->count
        
    for (0..$user->count) {
            print $user->column;
            $user->column('new stuff');
            $user->update($user->current, $user->id);
            $user->next;
        }
        
    # The database objects main accessors are CRUD (create, read, update, and delete)
        
    $user->create;
          $user->read;
            $user->update;
              $user->delete;
        
    # Also, need direct access to the resultset?
        
    $user->collection; # returns an array of hashrefs
        $user->current;    # return a hashref of the current row in the collection

    Occassionally you may want to create application Models using ORMesque
    and venture beyond the standard CRUD methods, creating classes for each
    table and extending its methods. The following is an example of how this
    should be done using ORMesque.

        package MyApp::Model;
        use base 'ORMesque';
        # create your base Model - lib/MyApp/Model.pm
        
    package MyApp::Model::Cd;
        use base 'MyApp::Model';
        # create your table specific Model - lib/MyApp/Model/Cd.pm
        # note the model should be named after the table, the naming is as follows:
        
    # Schema Table Classes are CamelCased for convention, all class names are
        # titlecased, and have dashed and underscores removed.
        
    # e.g. table 'user_workplace' would generate a class named 'UserWorkspace'
        
    # with no special characters. If package name is one of the auto-generated
        # classes, all relevant methods and settings will be set automatically.
        
    sub write_cd {
            $self = shift;
            ...
            $self->create({ ... });
            return $self;
        }
        
    ...
        
    1;

  namespace
        The namespace() method returns the classname being used in the auto-generated
        database table classes. 
        
    my $a = ORMesque->new(...);
        my $b = ThisApp->new(...);
        
    $a->namespace; # ORMesque
        $b->namespace; # ThisApp

  reset
        Once the reset() method analyzes the specified database, the schema is cached
        to for speed and performance. Occassionally you may want to re-read the
        database schema.
        
    my $db = ORMesque->new(...);
        $db->reset;

  next
        The next() method instructs the database object to continue to the next
        row if it exists.
        
    my $table = ORMesque->new(...)->table;
        
    while ($table->next) {
            ...
        }

  first
        The first() method instructs the database object to continue to return the first
        row in the resultset.
        
    my $table = ORMesque->new(...)->table;
        $table->first;

  last
        The last() method instructs the database object to continue to return the last
        row in the resultset.
        
    my $table = ORMesque->new(...)->table;
        $table->last;

  collection
        The collection() method return the raw resultset object.
        
    my $table = ORMesque->new(...)->table;
        $table->collection;

  current
        The current() method return the raw row resultset object of the position in
        the resultset collection.
        
    my $table = ORMesque->new(...)->table;
        $table->current;

  clear
        The clear() method empties all resultset containers. This method should be used
        when your ready to perform another operation (start over) without initializing
        a new object.
        
    my $table = ORMesque->new(...)->table;
        $table->clear;

  key
        The key() method finds the database objects primary key if its defined.
        
    my $table = ORMesque->new(...)->table;
        $table->key;

  select
        The select() method defines specific columns to be used in the generated
        SQL query. This useful for database tables that have lots of columns
        where only a few are actually needed.
        
    my $table = ORMesque->new(...)->table
        $table->select('foo', 'bar')->read();

  return
        The return() method queries the database for the last created object(s).
        It is important to note that while return() can be used in most cases
        like the last_insert_id() to fetch the recently last created entry,
        function, you should not use it that way unless you know exactly what
        this method does and what your database will return.
        
    my $new = ORMesque->new(...)->table;
        $new->create(...);
        $new->return();
        $new->column
        
    ..or..
        
    my $rec = $new->current; # current row

  count
        The count() method returns the number of items in the resultset of the
        object it's called on. Note! If you make changes to the database, you
        will need to call read() before calling count() to get an accurate
        count as count() operates on the current collection.
        
    my $db = ORMesque->new(...)->table;
        my $count = $db->read->count;
        
    Note! The count() method DOES NOT query the database, it merely counts
        the number of items in the existing resultset produced by read().
        Alternatively, to perform a type-of SQL COUNT() query you can use the
        count($where) syntax:
        
    my $db = ORMesque->new(...)->table;
        my $count = $db->count({ id => 12345});
        # notice there is no read() command

  create
        Caveat 1: The create method will remove the primary key if the column
        is marked as auto-incremented ...
        
    The create method creates a new entry in the datastore.
        takes 1 arg: hashref (SQL::Abstract fields parameter)
        
    ORMesque->new(...)->table->create({
            'column_a' => 'value_a',
        });
        
    # create a copy of an existing record
        my $user = ORMesque->new(...)->users;
        $user->read;
        $user->full_name_column('Copy of ' . $user->full_name);
        $user->user_name_column('foobarbaz');
        $user->create($user->current);

        # get newly created record
        $user->return;
        
    print $user->id; # new record id
        print $user->full_name;

  read
        The read method fetches records from the datastore.
        Takes 2 arg.
        
    arg 1: hashref (SQL::Abstract where parameter) or scalar
        arg 2: arrayref (SQL::Abstract order parameter) - optional
        
    ORMesque->new(...)->table->read({
            'column_a' => 'value_a',
        });
        
    .. or read by primary key ..
        
    ORMesque->new(...)->table->read(1);
        
    .. or read and limit the resultset ..
        
    ORMesque->new(...)->table->read({ 'column_a' => 'value_a' }, ['orderby_column_a'], $limit, $offset);
        
    .. or return a paged resultset ..
        
    ORMesque->new(...)->table->page(1, 25)->read;

  update
        The update method alters an existing record in the datastore.
        Takes 2 arg.
        
    arg 1: hashref (SQL::Abstract fields parameter)
        arg 2: arrayref (SQL::Abstract where parameter) or scalar - optional
        
    ORMesque->new(...)->table->update({
            'column_a' => 'value_a',
        },{
            'where_column_a' => '...'
        });
        
    or
        
    ORMesque->new(...)->table->update({
            'column_a' => 'value_a',
        }, 1);

  delete
        The delete method is prohibited from deleting an entire database table and
        thus requires a where clause. If you intentionally desire to empty the entire
        database then you may use the delete_all method.
        
    ORMesque->new(...)->table->delete({
            'column_a' => 'value_a',
        });
        
    or
        
    ORMesque->new(...)->table->delete(1);

  delete_all
        The delete_all method is use to intentionally empty the entire database table.
        
    ORMesque->new(...)->table->delete_all;

  join
    If you have used ORMesque with a project of any sophistication you will
    have undoubtedly noticed that the is no mechanism for specifying joins
    and this is intentional. ORMesque is an ORM, and object relational
    mapper and that is its purpose, it is not a SQL substitute. Joins are
    neccessary in SQL as they are the only means of gathering related data.
    Such is not the case with Perl code, however, even in code the need to
    join related datasets exists and that is the need we address. The join
    method "Does Not Execute Any SQL", in-fact the join method is meant to
    be called after the desired resultsets have be gathered. The join method
    is merely an aggregator of result sets.

        my ($cd, $artist) = (ORMesque->new(...)->cd, ORMesque->new(...)->artist);

        $artist->read({ id => $aid });
        $cd->read({ artist => $aid });

    Always use the larger dataset to initiate the join, in the following
    example, the list we want is "the list of cds" and we want to include
    the artist information with every "cd" entry so we use the persist
    option.

        my $resultset = $cd->join($artist, {
            persist => 1
        });

    The join configuration option "persist" when set true will instruct the
    aggregator to include the first entry of the associated table with each
    entry in the primary list which is the list (collection) within the
    object that initiated the join. Every table object may be passed an
    options join configuration object as follows:

        my $resultset = $cd->join($artist, {
            persist => 1
        });
        
    .. which is the same as ..
        
    my $resultset = $cd->join({
        }, $artist, {
            persist => 1
        });
        
    .. more complexity ..
        
    my $resultset = $track->join($cd, {
            persist => 1
        }, $artist, {
            persist => 1
        });

    By default, a joined resultset is returned as an arrayref of hashrefs
    with all table columns as keys which are in $table_$columnName format.
    This is not always ideal and so the "columns" join configuration option
    allows you to specify exactly which columns to include as well as supply
    an alias if desired. The following is an example of that:

        my $resultset = $track->join({
            columns => {
                track_name => 'track',
            }
        }, $cd, {
            persist => 1
            columns => {
                cd_name => 'cd',
            }
        }, $artist, {
            persist => 1,
            columns => {
                artist_name => 'artist'
            }
        });

  page
        The page method creates a paged resultset and instructs the read() method to
        only return the resultset of the desired page.
        
    my $page = 1; # page of data to be returned
        my $rows = 100; # number of rows to return
        
    ORMesque->new(...)->table->page($page, $rows)->read;

  pager
        The pager method provides access to the Data::Page object used in pagination.
        Please see L<Data::Page> for more details...
        
    $pager = ORMesque->new(...)->table->pager;
        
    $pager->first_page;
        $pager->last_page;

RESULTSET METHODS
    ORMesque provides columns accessors to the current record in the
    resultset object which is accessible via current() by default,
    collection() returns an arrayref of hashrefs based on the last read()
    call. Alternatively you may use the following methods to further
    transform and manipulate the returned resultset.

  columns
        Returns a list of column names. In scalar context, returns an array reference.
        Column names are lower cased if lc_columns was true when the query was executed.

  into
        Binds the columns returned from the query to variable(s)
        
    ORMesque->new(...)->table->read(1)->into(my ($foo, $bar));

  list
        Fetches a single row and returns a list of values. In scalar context,
        returns only the last value.
        
    my @values = ORMesque->new(...)->table->read(1)->list;

  array
        Fetches a single row and returns an array reference.
        
    my $row = ORMesque->new(...)->table->read(1)->array;
        print $row->[0];

  hash
        Fetches a single row and returns a hash reference.
        Keys are lower cased if lc_columns was true when the query was executed.
        
    my $row = ORMesque->new(...)->table->read(1)->hash;
        print $row->{id};

  flat
        Fetches all remaining rows and returns a flattened list.
        In scalar context, returns an array reference.
        
    my @records = ORMesque->new(...)->table->read(1)->flat;
        print $records[0];

  arrays
        Fetches all remaining rows and returns a list of array references.
        In scalar context, returns an array reference.
        
    my $rows = ORMesque->new(...)->table->read(1)->arrays;
        print $rows->[0];

  hashes
        Fetches all remaining rows and returns a list of hash references.
        In scalar context, returns an array reference.
        Keys are lower cased if lc_columns was true when the query was executed.
        
    my $rows = ORMesque->new(...)->table->read(1)->hashes;
        print $rows->[0]->{id};

  map_hashes
        Constructs a hash of hash references keyed by the values in the chosen column.
        In scalar context, returns a hash reference.
        In list context, returns interleaved keys and values.
        
    my $customer = ORMesque->new(...)->table->read->map_hashes('id');
        # $customers = { $id => { name => $name, location => $location } }

  map_arrays
        Constructs a hash of array references keyed by the values in the chosen column.
        In scalar context, returns a hash reference.
        In list context, returns interleaved keys and values.
        
    my $customer = ORMesque->new(...)->table->read->map_arrays(0);
        # $customers = { $id => [ $name, $location ] }

  rows
        Returns the number of rows affected by the last row affecting command,
        or -1 if the number of rows is not known or not available.
        For SELECT statements, it is generally not possible to know how many
        rows are returned. MySQL does provide this information. See DBI for a
        detailed explanation.
        
    my $changes = ORMesque->new(...)->table->insert(ORMesque->new(...)->table->current)->rows;

UTILITIES
    ORMesque has as its sub-classes DBIx::Simple and SQL::Abstract as its
    querying language, it also provides access to SQL::Interp for good
    measure. For an in-depth look at what you can do with these utilities,
    please check out DBIx::Simple::Examples.

  error
    The error function is used to access the $DBI::errstr variable.

  query
    The query function provides a simplified interface to DBI, Perl's
    powerful database interfacing module. This function provides
    auto-escaping/interpolation as well as resultset abstraction.

        $db->query('DELETE FROM foo WHERE id = ?', $id);
        $db->query('SELECT 1 + 1')->into(my $two);
        $db->query('SELECT 3, 2 + 2')->into(my ($three, $four));

        $db->query(
            'SELECT name, email FROM people WHERE email = ? LIMIT 1',
            $mail
        )->into(my ($name, $email));
        
    # One big flattened list (primarily for single column queries)
        
    my @names = $db->query('SELECT name FROM people WHERE id > 5')->flat;
        
    # Rows as array references
        
    for my $row ($db->query('SELECT name, email FROM people')->arrays) {
            print "Name: $row->[0], Email: $row->[1]\n";
        }

  iquery
    The iquery function is used to interpolate Perl variables into SQL
    statements, it converts a list of intermixed SQL fragments and variable
    references into a conventional SQL string and list of bind values
    suitable for passing onto DBI

        my $result = $db->iquery('INSERT INTO table', \%item);
        my $result = $db->iquery('UPDATE table SET', \%item, 'WHERE y <> ', \2);
        my $result = $db->iquery('DELETE FROM table WHERE y = ', \2);

        # These two select syntax produce the same result
        my $result = $db->iquery('SELECT * FROM table WHERE x = ', \$s, 'AND y IN', \@v);
        my $result = $db->iquery('SELECT * FROM table WHERE', {x => $s, y => \@v});

        my $first_record = $result->hash;
        for ($result->hashes) { ... }

  dbix
    Access to the underlying DBIx::Simple object.

  dbi
    Access to the underlying DBI object.

  connected
    Determine whether a database connection exists. Returns true or false.

AUTHOR
    Al Newkirk <awncorp@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2010 by awncorp.

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