=head1 DESCRIPTION
-This is a sql to oop mapper, inspired by the L<Class::DBI> framework,
+This is an SQL to OO mapper, inspired by the L<Class::DBI> framework,
and meant to support compability with it, while restructuring the
-insides, and making it possible to support some new features like
+internals and making it possible to support some new features like
self-joins, distinct, group bys and more.
-This project is still at an early stage so the maintainers don't make
+This project is still at an early stage, so the maintainers don't make
any absolute promise that full backwards-compatibility will be supported;
-however if we can without compromising the improvements we're trying to
+however, if we can without compromising the improvements we're trying to
make, we will, and any non-compatible changes will merit a full justification
on the mailing list and a CPAN developer release for people to test against.
=head1 QUICKSTART
-If you're using Class::DBI, and want an easy and fast way of migrating to
-DBIx::Class look at L<DBIx::Class::CDBICompat>.
+If you're using L<Class::DBI>, and want an easy and fast way of migrating to
+DBIx::Class, take a look at L<DBIx::Class::CDBICompat>.
-There are two ways of using DBIx::Class, the 'simple' and the 'schema' one.
-
-The 'simple' way of using DBIx::Class needs less classes than the 'schema'
-way but doesn't give you the ability to use different database connections.
+There are two ways of using DBIx::Class, the "simple" way and the "schema" way.
+The "simple" way of using DBIx::Class needs less classes than the "schema"
+way but doesn't give you the ability to easily use different database connections.
Some examples where different database connections are useful are:
=head1 Simple
-First you need to create a base class all other classes inherit from.
-
-Look at L<DBIx::Class::DB> how to do this
-
-Next you need to create a class for every table you want to use with
-DBIx::Class.
-
-Look at L<DBIx::Class::Table> how to do this.
+First you need to create a base class which all other classes will inherit from.
+See L<DBIx::Class::DB> for information on how to do this.
+Then you need to create a class for every table you want to use with DBIx::Class.
+See L<DBIx::Class::Table> for information on how to do this.
=head2 Schema
-With this approach the table classes inherit directly from DBIx::Class::Core,
-although it might be a good idea to create a 'parent' class for all table
-classes which inherits from DBIx::Class::Core and adds additional methods
-needed by all table classes, e.g. reading a config file, loading auto primary
+With this approach, the table classes inherit directly from DBIx::Class::Core,
+although it might be a good idea to create a "parent" class for all table
+classes that inherits from DBIx::Class::Core and adds additional methods
+needed by all table classes, e.g. reading a config file or loading auto primary
key support.
-Look at L<DBIx::Class::Schema> how to do this.
+Look at L<DBIx::Class::Schema> for information on how to do this.
-If you need more hand-holding, check out the introduction in the
+If you need more help, check out the introduction in the
manual below.
=head1 SEE ALSO
=head2 L<DBIx::Class::Core> - DBIC Core Classes
-=head2 L<DBIx::Class::CDBICompat> - L<Class::DBI> Compat layer.
+=head2 L<DBIx::Class::Manual> - User's manual
+
+=head2 L<DBIx::Class::CDBICompat> - L<Class::DBI> Compat layer
+
+=head2 L<DBIx::Class::DB> - database-level methods
+
+=head2 L<DBIx::Class::Table> - table-level methods
+
+=head2 L<DBIx::Class::Row> - row-level methods
+
+=head2 L<DBIx::Class::PK> - primary key methods
-=head2 L<DBIx::Class::Manual> - User's manual.
+=head2 L<DBIx::Class::Relationship> - relationships between tables
=head1 AUTHOR
package MyDB::MyTable;
use base qw/MyDB/;
- __PACKAGE__->load_components('Core');
+ __PACKAGE__->load_components('Core'); # just load this in MyDB if it will always be there
...
=head1 DESCRIPTION
-This class represents methods handling primary keys
-and depending on them.
+This class contains methods for handling primary keys and methods
+depending on them.
=head1 METHODS
return (map { $self->{_column_data}{$_} } keys %{$self->_primaries});
}
-=head2 set_primary_key <@cols>
+=head2 set_primary_key(@cols)
-define one or more columns as primary key for this class
+Defines one or more columns as primary key for this class. Should be
+called after C<columns>.
=cut
$class->_primaries(\%pri);
}
-=head2 find
+=head2 find(@colvalues), find(\%cols)
-Finds columns based on the primary key(s).
+Finds a row based on its primary key(s).
=cut
=head2 discard_changes
-Roll back changes that hasn't been comitted to the database.
+Re-selects the row from the database, losing any changes that had
+been made.
=cut
=head2 id
-returns the primary key(s) for the current row. Can't be called as
+Returns the primary key(s) for a row. Can't be called as
a class method.
=cut
return (wantarray ? @pk : $pk[0]);
}
-=head2 primary_columns
+=head2 primary_columns
-read-only accessor which returns a list of primary keys.
+Read-only accessor which returns the list of primary keys for a class
+(in scalar context, only returns the first primary key).
=cut
return keys %{shift->_primaries};
}
+=head2 ID
+
+Returns a unique id string identifying a row object by primary key.
+Used by L<DBIx::Class::CDBICompat::LiveObjectIndex> and
+L<DBIx::Class::ObjectCache>.
+
+=cut
+
sub ID {
my ($self) = @_;
$self->throw( "Can't call ID() as a class method" ) unless ref $self;
my $val = $obj->get_column($col);
-Fetches a column value
+Gets a column value from a row object. Currently, does not do
+any queries; the column must have already been fetched from
+the database and stored in the object.
=cut
my %data = $obj->get_columns;
-Fetch all column values at once.
+Does C<get_column>, for all column values at once.
=cut
$obj->set_column($col => $val);
-Sets a column value; if the new value is different to the old the column
-is marked as dirty for when you next call $obj->update
+Sets a column value. If the new value is different from the old one,
+the column is marked as dirty for when you next call $obj->update.
=cut
my $copy = $orig->set_columns({ $col => $val, ... });
-Set more than one column value at once.
+Sets more than one column value at once.
=cut
my $copy = $orig->copy({ change => $to, ... });
-Insert a new row with the specified changes.
+Inserts a new row with the specified changes.
=cut
$obj->store_column($col => $val);
-Sets a column value without marking it as dirty
+Sets a column value without marking it as dirty.
=cut
$obj->insert_or_update
-Updates the object if it's already in the db, else inserts it
+Updates the object if it's already in the db, else inserts it.
=cut
=head1 DESCRIPTION
-This class is responsible for defining and doing basic operations on
-L<DBIx::Class> objects.
+This class is responsible for defining and doing table-level operations on
+L<DBIx::Class> classes.
=head1 METHODS
__PACKAGE__->add_columns(qw/col1 col2 col3/);
-Adds columns to the current package, and creates accessors for them
+Adds columns to the current class and creates accessors for them.
=cut
=head2 table
__PACKAGE__->table('tbl_name');
+
+Gets or sets the table name.
=cut
$class->find_or_create({ key => $val, ... });
Searches for a record matching the search condition; if it doesn't find one,
-creates one and returns that instead
+creates one and returns that instead.
=cut
if ($obj->has_column($col)) { ... }
-Returns 1 if the object has a column of this name, 0 otherwise
+Returns 1 if the class has a column of this name, 0 otherwise.
=cut
my $info = $obj->column_info($col);
-Returns the column metadata hashref for the column
+Returns the column metadata hashref for a column.
=cut
projects / dbsrgits/DBIx-Class.git / commitdiff