From: Matt S Trout Date: Fri, 14 Sep 2007 20:56:27 +0000 (+0000) Subject: Merge 'trunk' into 'versioned_enhancements' X-Git-Tag: v0.08240~545^2~27 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=14ad95291d2a5fe439fdb19058f05a685bd0331e;hp=bcd1448c5b417d555c64fb0cf4cafcf4c8fa3474;p=dbsrgits%2FDBIx-Class.git Merge 'trunk' into 'versioned_enhancements' r11158@jules (orig r3684): jnapiorkowski | 2007-08-16 16:23:18 +0100 -- added some documentation to ->populate to warn people about the side effects of using wantarray versus void context. -- added some additional documentation to resultset->create r11194@jules (orig r3695): matthewt | 2007-08-21 19:24:53 +0100 r10460@jules (orig r3640): tomboh | 2007-08-01 12:27:38 +0100 Add an 'on_disconnect_do' argument to DBIx::Class::Storage::DBI::connect_info that, on disconnection, do what 'on_connect_do' does on connection. Currently, this only works if the code explicitly calls disconnect() on the Storage object. While I'm here, make both 'on_connect_do' and 'on_disconnect_do' accept code references as well as strings containing SQL statements. Finally, remove code to call compose_connection() from DBICTest.pm that never gets called any more. r11195@jules (orig r3696): matthewt | 2007-08-21 19:24:57 +0100 r11152@jules (orig r3678): tomboh | 2007-08-15 09:24:32 +0100 Restore code that I removed in revision 3640 that tests still need r11196@jules (orig r3697): matthewt | 2007-08-21 19:25:00 +0100 r11153@jules (orig r3679): tomboh | 2007-08-15 09:25:47 +0100 Let on_connect_do() and on_disconnect_do() take code references. Provide tests and documentation for this. r11197@jules (orig r3698): matthewt | 2007-08-21 19:25:33 +0100 r11199@jules (orig r3700): matthewt | 2007-08-21 19:50:00 +0100 arrayrefs for on_connect_do r11200@jules (orig r3701): matthewt | 2007-08-21 19:53:44 +0100 note on_connect_do changes r11201@jules (orig r3702): matthewt | 2007-08-21 20:17:22 +0100 oracle datetime inflator patch r11202@jules (orig r3703): matthewt | 2007-08-21 20:52:09 +0100 force CDBICompat deps for developers, fix tests to work with latest Class::Trigger r11217@jules (orig r3705): tomboh | 2007-08-22 11:28:58 +0100 Fix the behaviour of code refs within array refs for on_(dis)?connect_do and enhance tests to spot the previous mistake. r11218@jules (orig r3706): tomboh | 2007-08-22 11:57:14 +0100 Add myself to the list of contributors r11232@jules (orig r3709): gphat | 2007-08-24 18:11:46 +0100 Fix typos. r14025@jules (orig r3720): ilmari | 2007-09-04 17:44:41 +0100 Fix return value for DBIC::ResultSource::Table->table($table) r14026@jules (orig r3721): ash | 2007-09-04 20:14:02 +0100 Bump for New relase r14027@jules (orig r3722): semifor | 2007-09-05 04:49:46 +0100 r1185@titanic: mjm | 2007-09-04 20:11:07 -0700 Updated email address r14029@jules (orig r3723): castaway | 2007-09-06 21:07:52 +0100 Doc patch from wreis r14030@jules (orig r3724): castaway | 2007-09-06 22:35:49 +0100 Add more about accessors to doc r14031@jules (orig r3725): tomboh | 2007-09-07 17:54:00 +0100 Small POD fix r14032@jules (orig r3726): semifor | 2007-09-08 17:58:56 +0100 r1191@titanic: mjm | 2007-09-08 09:20:32 -0700 discard_changes is also "refresh from storage" r14035@jules (orig r3729): castaway | 2007-09-12 00:23:20 +0100 Much doch shuffling and more argument explanations (due to initself ;) --- diff --git a/Changes b/Changes index 2cae3a3..ccb5ded 100644 --- a/Changes +++ b/Changes @@ -1,5 +1,10 @@ Revision history for DBIx::Class +0.08007 2007-09-04 19:36:00 + - patch for Oracle datetime inflation (abram@arin.net) + - added on_disconnect_do + - on_connect_do and on_disconnect_do take coderefs and arrayrefs + 0.08006 2007-08-12 15:12:00 - Move to using Class::C3::Componentised - Remove warn statement from DBIx::Class::Row diff --git a/Makefile.PL b/Makefile.PL index 1e84a29..67326b5 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -29,9 +29,11 @@ install_script 'script/dbicadmin'; tests "t/*.t t/*/*.t"; -# re-build README if we're in an svk checkout -if( -e 'MANIFEST.SKIP' ) { - system('pod2text lib/DBIx/Class.pm > README'); +# re-build README and require CDBI modules for testing if we're in a checkout +if( -e 'inc/.author' ) { + build_requires 'DBIx::ContextualFetch'; + build_requires 'Class::Trigger'; + system('pod2text lib/DBIx/Class.pm > README'); } auto_provides; diff --git a/lib/DBIx/Class.pm b/lib/DBIx/Class.pm index 3f0fb8e..854df8e 100644 --- a/lib/DBIx/Class.pm +++ b/lib/DBIx/Class.pm @@ -23,7 +23,7 @@ sub component_base_class { 'DBIx::Class' } # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports # brain damage and presumably various other packaging systems too -$VERSION = '0.08006'; +$VERSION = '0.08007'; sub MODIFY_CODE_ATTRIBUTES { my ($class,$code,@attrs) = @_; @@ -265,6 +265,8 @@ sszabo: Stephan Szabo Todd Lipcon +Tom Hukins + typester: Daisuke Murase victori: Victor Igumnov diff --git a/lib/DBIx/Class/Manual/FAQ.pod b/lib/DBIx/Class/Manual/FAQ.pod index 39f4b99..d372115 100644 --- a/lib/DBIx/Class/Manual/FAQ.pod +++ b/lib/DBIx/Class/Manual/FAQ.pod @@ -285,6 +285,18 @@ Why slice instead of L or L. + + $row->discard_changes + +Discarding changes and refreshing from storage are two sides fo the same coin. When you +want to discard your local changes, just re-fetch the row from storage. When you want +to get a new, fresh copy of the row, just re-fetch the row from storage. +L does just that by re-fetching the row from storage +using the row's primary key. + =back =head2 Inserting and updating data @@ -398,6 +410,6 @@ you ask the resultset for an actual row object. particular column or group of columns (a-la cdbi Stringfy column group, or stringify_self method) ? -See L +See L =back diff --git a/lib/DBIx/Class/PK.pm b/lib/DBIx/Class/PK.pm index 9b9f8a4..2a68df5 100644 --- a/lib/DBIx/Class/PK.pm +++ b/lib/DBIx/Class/PK.pm @@ -30,6 +30,9 @@ sub _ident_values { Re-selects the row from the database, losing any changes that had been made. +This method can also be used to refresh from storage, retrieving any +changes made since the row was last read from storage. + =cut sub discard_changes { diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm index b95867f..3ee93ff 100644 --- a/lib/DBIx/Class/Relationship.pm +++ b/lib/DBIx/Class/Relationship.pm @@ -115,6 +115,44 @@ relationship attributes. =back +Creates a relationship where the calling class stores the foreign class's +primary key in one (or more) of its columns. This relationship defaults to +using C<$accessor_name> as the foreign key in C<$related_class> to resolve the +join, unless C<$foreign_key_column> specifies the foreign key column in +C<$related_class> or C<$cond> specifies a reference to a join condition hash. + +=over + +=item accessor_name + +This argument is the name of the method you can call on a +L object to retrieve the instance of the foreign +class matching this relationship. + +Use this accessor_name (relation name) in L +or L to join to the foreign table +indicated by this relationship. + +=item related_class + +This is the class name of the table referenced by the foreign key in +this class. + +=item foreign_key_column + +The column name on this class that contains the foreign key. + +OR + +=item cond + +A hashref where the keys are C and +the values are C. This is useful for +relations that are across multiple columns. + +=back + + # in a Book class (where Author has many Books) My::DBIC::Schema::Book->belongs_to( author => 'My::DBIC::Schema::Author' ); @@ -127,12 +165,6 @@ The above belongs_to relationship could also have been specified as, 'My::DBIC::Schema::Author', { 'foreign.author' => 'self.author' } ); -Creates a relationship where the calling class stores the foreign class's -primary key in one (or more) of its columns. This relationship defaults to -using C<$accessor_name> as the foreign key in C<$related_class> to resolve the -join, unless C<$foreign_key_column> specifies the foreign key column in -C<$related_class> or C<$cond> specifies a reference to a join condition hash. - If the relationship is optional -- i.e. the column containing the foreign key can be NULL -- then the belongs_to relationship does the right thing. Thus, in the example above C<$obj-Eauthor> would return C. However in this @@ -163,6 +195,45 @@ methods and valid relationship attributes. =back +Creates a one-to-many relationship, where the corresponding elements of the +foreign class store the calling class's primary key in one (or more) of its +columns. This relationship defaults to using C<$accessor_name> as the foreign +key in C<$related_class> to resolve the join, unless C<$foreign_key_column> +specifies the foreign key column in C<$related_class> or C<$cond> specifies a +reference to a join condition hash. + +=over + +=item accessor_name + +This argument is the name of the method you can call on a +L object to retrieve a resultset of the related +class restricted to the ones related to the row object. In list +context it returns the row objects. + +Use this accessor_name (relation name) in L +or L to join to the foreign table +indicated by this relationship. + +=item related_class + +This is the class name of the table which contains a foreign key +column containing PK values of this class. + +=item foreign_key_column + +The column name on the related class that contains the foreign key. + +OR + +=item cond + +A hashref where the keys are C and +the values are C. This is useful for +relations that are across multiple columns. + +=back + # in an Author class (where Author has_many Books) My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author'); @@ -184,13 +255,6 @@ explicit join condition: 'foreign.author' => 'self.author', }); -Creates a one-to-many relationship, where the corresponding elements of the -foreign class store the calling class's primary key in one (or more) of its -columns. This relationship defaults to using C<$accessor_name> as the foreign -key in C<$related_class> to resolve the join, unless C<$foreign_key_column> -specifies the foreign key column in C<$related_class> or C<$cond> specifies a -reference to a join condition hash. - Three methods are created when you create a has_many relationship. The first method is the expected accessor method, C<$accessor_name()>. The second is almost exactly the same as the accessor method but "_rs" is added to the end of @@ -217,6 +281,43 @@ methods and valid relationship attributes. =back +Creates an optional one-to-one relationship with a class. This relationship +defaults to using C<$accessor_name> as the foreign key in C<$related_class> to +resolve the join, unless C<$foreign_key_column> specifies the foreign key +column in C<$related_class> or C<$cond> specifies a reference to a join +condition hash. + +=over + +=item accessor_name + +This argument is the name of the method you can call on a +L object to retrieve the instance of the foreign +class matching this relationship. + +Use this accessor_name (relation name) in L +or L to join to the foreign table +indicated by this relationship. + +=item related_class + +This is the class name of the table which contains a foreign key +column containing PK values of this class. + +=item foreign_key_column + +The column name on the related class that contains the foreign key. + +OR + +=item cond + +A hashref where the keys are C and +the values are C. This is useful for +relations that are across multiple columns. + +=back + My::DBIC::Schema::Author->might_have( pseudonym => 'My::DBIC::Schema::Pseudonym' ); @@ -234,14 +335,6 @@ Or even: 'My::DBIC::Schema::Pseudonym', { 'foreign.author' => 'self.author' } ); -Assuming the Pseudonym table has - -Creates an optional one-to-one relationship with a class. This relationship -defaults to using C<$accessor_name> as the foreign key in C<$related_class> to -resolve the join, unless C<$foreign_key_column> specifies the foreign key -column in C<$related_class> or C<$cond> specifies a reference to a join -condition hash. - If you update or delete an object in a class with a C relationship, the related object will be updated or deleted as well. To turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr> @@ -287,6 +380,37 @@ methods and valid relationship attributes. =back +C is not strictly a relationship in its own right. Instead, it is +a bridge between two resultsets which provide the same kind of convenience +accessors as true relationships provide. Although the accessor will return a +resultset or collection of objects just like has_many does, you cannot call +C and similar methods which operate on true relationships. + +=over + +=item accessor_name + +This argument is the name of the method you can call on a +L object to retrieve the rows matching this +relationship. + +On a many_to_many, unlike other relationships, this cannot be used in +L to join tables. Use the relations +bridged across instead. + +=item link_rel_name + +This is the accessor_name from the has_many relationship we are +bridging from. + +=item foreign_rel_name + +This is the accessor_name of the belongs_to relationship in the link +table that we are bridging across (which gives us the table we are +bridging to). + +=back + To create a many_to_many relationship from Actor to Role: My::DBIC::Schema::Actor->has_many( actor_roles => @@ -313,12 +437,6 @@ actor_roles table: $actor->add_to_roles($role, { year => 1995 }); -Many_to_many is not strictly a relationship in its own right. Instead, it is -a bridge between two resultsets which provide the same kind of convenience -accessors as true relationships provide. Although the accessor will return a -resultset or collection of objects just like has_many does, you cannot call -C<$related_resultset> and similar methods which operate on true relationships. - In the above example, ActorRoles is the link table class, and Role is the foreign class. The C<$link_rel_name> parameter is the name of the accessor for the has_many relationship from this table to the link table, and the diff --git a/lib/DBIx/Class/ResultClass/HashRefInflator.pm b/lib/DBIx/Class/ResultClass/HashRefInflator.pm index 9a2c8eb..6ad22ad 100644 --- a/lib/DBIx/Class/ResultClass/HashRefInflator.pm +++ b/lib/DBIx/Class/ResultClass/HashRefInflator.pm @@ -23,13 +23,13 @@ There are two ways of using this class. =item * Specify C<< $rs->result_class >> on a specific resultset to affect only that -resultser (and any chained off of it); or +resultset (and any chained off of it); or =item * Specify C<< __PACKAGE__->result_class >> on your source object to force all uses of that result source to be inflated to hash-refs - this approach is not -recomended +recommended. =back diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm index a56166f..713bf14 100644 --- a/lib/DBIx/Class/ResultSet.pm +++ b/lib/DBIx/Class/ResultSet.pm @@ -1251,7 +1251,7 @@ Pass an arrayref of hashrefs. Each hashref should be a structure suitable for submitting to a $resultset->create(...) method. In void context, C in L is used -to insert the data, as this is a faster method. +to insert the data, as this is a faster method. Otherwise, each set of data is inserted into the database using L, and a arrayref of the resulting row @@ -1288,6 +1288,14 @@ Example: Assuming an Artist Class that has many CDs Classes relating: print $ArtistOne->name; ## response is 'Artist One' print $ArtistThree->cds->count ## reponse is '2' + +Please note an important effect on your data when choosing between void and +wantarray context. Since void context goes straight to C in +L this will skip any component that is overriding +c. So if you are using something like L to +create primary keys for you, you will find that your PKs are empty. In this +case you will have to use the wantarray context in order to create those +values. =cut @@ -1569,6 +1577,16 @@ L), will be inserted into their appropriate tables. Effectively a shortcut for C<< ->new_result(\%vals)->insert >>. +Example of creating a new row. + + $person_rs->create({ + name=>"Some Person", + email=>"somebody@someplace.com" + }); + +Example of creating a new row and also creating rows in a related C +or C resultset. Note Arrayref. + $artist_rs->create( { artistid => 4, name => 'Manufactured Crap', cds => [ { title => 'My First CD', year => 2006 }, @@ -1577,6 +1595,17 @@ Effectively a shortcut for C<< ->new_result(\%vals)->insert >>. }, ); +Example of creating a new row and also creating a row in a related +Cresultset. Note Hashref. + + $cd_rs->create({ + title=>"Music for Silly Walks", + year=>2000, + artist => { + name=>"Silly Musician", + } + }); + =cut sub create { @@ -2180,11 +2209,10 @@ Indicates additional column names for those added via L<+select>. =back -Indicates column names for object inflation. That is, c< as > +Indicates column names for object inflation. That is, C indicates the name that the column can be accessed as via the C method (or via the object accessor, B). It has nothing to do with the SQL code C< SELECT foo AS bar ->. +exists>). It has nothing to do with the SQL code C, usually when C