From: David Kamholz Date: Sat, 10 Dec 2005 18:21:11 +0000 (+0000) Subject: more dob updates X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=958bcea5fcf02c0c13e934dd03103d8421dcc144;p=dbsrgits%2FDBIx-Class-Historic.git more dob updates --- diff --git a/lib/DBIx/Class.pm b/lib/DBIx/Class.pm index 463e4fb..bbfdc17 100644 --- a/lib/DBIx/Class.pm +++ b/lib/DBIx/Class.pm @@ -19,14 +19,14 @@ DBIx::Class - Extensible and flexible object <-> relational mapper. =head1 DESCRIPTION -This is a sql to oop mapper, inspired by the L framework, +This is an SQL to OO mapper, inspired by the L 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. @@ -42,13 +42,12 @@ The community can be found via - =head1 QUICKSTART -If you're using Class::DBI, and want an easy and fast way of migrating to -DBIx::Class look at L. +If you're using L, and want an easy and fast way of migrating to +DBIx::Class, take a look at L. -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: @@ -57,36 +56,42 @@ different databases with the same schema. =head1 Simple -First you need to create a base class all other classes inherit from. - -Look at L how to do this - -Next you need to create a class for every table you want to use with -DBIx::Class. - -Look at L how to do this. +First you need to create a base class which all other classes will inherit from. +See L 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 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 how to do this. +Look at L 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 - DBIC Core Classes -=head2 L - L Compat layer. +=head2 L - User's manual + +=head2 L - L Compat layer + +=head2 L - database-level methods + +=head2 L - table-level methods + +=head2 L - row-level methods + +=head2 L - primary key methods -=head2 L - User's manual. +=head2 L - relationships between tables =head1 AUTHOR diff --git a/lib/DBIx/Class/DB.pm b/lib/DBIx/Class/DB.pm index e9ff08a..469d051 100644 --- a/lib/DBIx/Class/DB.pm +++ b/lib/DBIx/Class/DB.pm @@ -24,7 +24,7 @@ DBIx::Class::DB - Simple DBIx::Class Database connection by class inheritance 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 ... diff --git a/lib/DBIx/Class/PK.pm b/lib/DBIx/Class/PK.pm index eb15f32..eb2540d 100644 --- a/lib/DBIx/Class/PK.pm +++ b/lib/DBIx/Class/PK.pm @@ -16,8 +16,8 @@ DBIx::Class::PK - Primary Key class =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 @@ -33,9 +33,10 @@ sub _ident_values { 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. =cut @@ -51,9 +52,9 @@ sub set_primary_key { $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 @@ -86,7 +87,8 @@ sub find { =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 @@ -106,7 +108,7 @@ sub discard_changes { =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 @@ -118,9 +120,10 @@ sub id { 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 @@ -128,6 +131,14 @@ sub primary_columns { return keys %{shift->_primaries}; } +=head2 ID + +Returns a unique id string identifying a row object by primary key. +Used by L and +L. + +=cut + sub ID { my ($self) = @_; $self->throw( "Can't call ID() as a class method" ) unless ref $self; diff --git a/lib/DBIx/Class/Row.pm b/lib/DBIx/Class/Row.pm index 3eab5b4..2354a7a 100644 --- a/lib/DBIx/Class/Row.pm +++ b/lib/DBIx/Class/Row.pm @@ -157,7 +157,9 @@ sub delete { 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 @@ -174,7 +176,7 @@ sub get_column { my %data = $obj->get_columns; -Fetch all column values at once. +Does C, for all column values at once. =cut @@ -187,8 +189,8 @@ sub get_columns { $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 @@ -205,7 +207,7 @@ sub set_column { my $copy = $orig->set_columns({ $col => $val, ... }); -Set more than one column value at once. +Sets more than one column value at once. =cut @@ -220,7 +222,7 @@ sub set_columns { my $copy = $orig->copy({ change => $to, ... }); -Insert a new row with the specified changes. +Inserts a new row with the specified changes. =cut @@ -228,7 +230,7 @@ Insert a new row with the specified changes. $obj->store_column($col => $val); -Sets a column value without marking it as dirty +Sets a column value without marking it as dirty. =cut @@ -261,7 +263,7 @@ sub copy { $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 diff --git a/lib/DBIx/Class/Table.pm b/lib/DBIx/Class/Table.pm index cc7a20d..e1bbe7d 100644 --- a/lib/DBIx/Class/Table.pm +++ b/lib/DBIx/Class/Table.pm @@ -26,8 +26,8 @@ DBIx::Class::Table - Basic table methods =head1 DESCRIPTION -This class is responsible for defining and doing basic operations on -L objects. +This class is responsible for defining and doing table-level operations on +L classes. =head1 METHODS @@ -49,7 +49,7 @@ sub _mk_column_accessors { __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 @@ -159,6 +159,8 @@ sub _select_columns { =head2 table __PACKAGE__->table('tbl_name'); + +Gets or sets the table name. =cut @@ -171,7 +173,7 @@ sub table { $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 @@ -186,7 +188,7 @@ sub find_or_create { 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 @@ -199,7 +201,7 @@ sub has_column { my $info = $obj->column_info($col); -Returns the column metadata hashref for the column +Returns the column metadata hashref for a column. =cut