From: Justin Guenther Date: Tue, 21 Mar 2006 12:03:55 +0000 (+0000) Subject: changed Foo/Bar in docs to more meaningful names X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=24d67825c6b2e604a349ccd5de0df1956c0d98dc;p=dbsrgits%2FDBIx-Class-Historic.git changed Foo/Bar in docs to more meaningful names --- diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm index da9dced..b5bad6a 100644 --- a/lib/DBIx/Class/ResultSet.pm +++ b/lib/DBIx/Class/ResultSet.pm @@ -21,7 +21,7 @@ DBIx::Class::ResultSet - Responsible for fetching and creating resultset. =head1 SYNOPSIS my $rs = $schema->resultset('User')->search(registered => 1); - my @rows = $schema->resultset('Foo')->search(bar => 'baz'); + my @rows = $schema->resultset('CD')->search(year => 2005); =head1 DESCRIPTION @@ -151,14 +151,16 @@ sub new { =head2 search - my @obj = $rs->search({ foo => 3 }); # "... WHERE foo = 3" - my $new_rs = $rs->search({ foo => 3 }); + my @cds = $rs->search({ year => 2001 }); # "... WHERE year = 2001" + my $new_rs = $rs->search({ year => 2005 }); If you need to pass in additional attributes but no additional condition, call it as C. - # "SELECT foo, bar FROM $class_table" - my @all = $class->search(undef, { columns => [qw/foo bar/] }); + # "SELECT name, artistid FROM $artist_table" + my @all_artists = $schema->resultset('Artist')->search(undef, { + columns => [qw/name artistid/], + }); =cut @@ -924,7 +926,7 @@ sub clear_cache { Returns a related resultset for the supplied relationship name. - $rs = $rs->related_resultset('foo'); + $artist_rs = $schema->resultset('CD')->related_resultset('Artist'); =cut @@ -973,8 +975,9 @@ overview of them: =head2 order_by -Which column(s) to order the results by. This is currently passed through -directly to SQL, so you can give e.g. C for a descending order. +Which column(s) to order the results by. This is currently passed +through directly to SQL, so you can give e.g. C for a +descending order on the column `year'. =head2 columns @@ -991,9 +994,13 @@ use the C attribute, as in earlier versions of DBIC.) Shortcut to include additional columns in the returned results - for example - { include_columns => ['foo.name'], join => ['foo'] } + $schema->resultset('CD')->search(undef, { + include_columns => ['artist.name'], + join => ['artist'] + }); -would add a 'name' column to the information passed to object inflation +would return all CDs and include a 'name' column to the information +passed to object inflation =head2 select @@ -1003,20 +1010,17 @@ Indicates which columns should be selected from the storage. You can use column names, or in the case of RDBMS back ends, function or stored procedure names: - $rs = $schema->resultset('Foo')->search( - undef, - { - select => [ - 'column_name', - { count => 'column_to_count' }, - { sum => 'column_to_sum' } - ] - } - ); + $rs = $schema->resultset('Employee')->search(undef, { + select => [ + 'name', + { count => 'employeeid' }, + { sum => 'salary' } + ] + }); When you use function/stored procedure names and do not supply an C attribute, the column names returned are storage-dependent. E.g. MySQL would -return a column named C in the above example. +return a column named C in the above example. =head2 as @@ -1026,29 +1030,26 @@ Indicates column names for object inflation. This is used in conjunction with C contains one or more function or stored procedure names: - $rs = $schema->resultset('Foo')->search( - undef, - { - select => [ - 'column1', - { count => 'column2' } - ], - as => [qw/ column1 column2_count /] - } - ); + $rs = $schema->resultset('Employee')->search(undef, { + select => [ + 'name', + { count => 'employeeid' } + ], + as => ['Employee Name', 'employee_count'], + }); - my $foo = $rs->first(); # get the first Foo + my $employee = $rs->first(); # get the first Employee If the object against which the search is performed already has an accessor matching a column name specified in C, the value can be retrieved using the accessor as normal: - my $column1 = $foo->column1(); + my $name = $employee->name(); If on the other hand an accessor does not exist in the object, you need to use C instead: - my $column2_count = $foo->get_column('column2_count'); + my $employee_count = $employee->get_column('employee_count'); You can create your own accessors if required - see L for details. @@ -1087,13 +1088,15 @@ For example: If the same join is supplied twice, it will be aliased to _2 (and similarly for a third time). For e.g. - my $rs = $schema->resultset('Artist')->search( - { 'cds.title' => 'Foo', - 'cds_2.title' => 'Bar' }, - { join => [ qw/cds cds/ ] }); + my $rs = $schema->resultset('Artist')->search({ + 'cds.title' => 'Down to Earth', + 'cds_2.title' => 'Popular', + }, { + join => [ qw/cds cds/ ], + }); -will return a set of all artists that have both a cd with title Foo and a cd -with title Bar. +will return a set of all artists that have both a cd with title 'Down +to Earth' and a cd with title 'Popular'. If you want to fetch related objects from other tables as well, see C below. diff --git a/lib/DBIx/Class/ResultSetManager.pm b/lib/DBIx/Class/ResultSetManager.pm index 476e8e1..eb18437 100644 --- a/lib/DBIx/Class/ResultSetManager.pm +++ b/lib/DBIx/Class/ResultSetManager.pm @@ -3,7 +3,8 @@ use strict; use base 'DBIx::Class'; use Class::Inspector; -__PACKAGE__->mk_classdata($_) for qw/ base_resultset_class table_resultset_class_suffix /; +__PACKAGE__->mk_classdata($_) + for qw/ base_resultset_class table_resultset_class_suffix /; __PACKAGE__->base_resultset_class('DBIx::Class::ResultSet'); __PACKAGE__->table_resultset_class_suffix('::_resultset'); @@ -55,9 +56,10 @@ sub _register_resultset_class { my $resultset_class = $self . $self->table_resultset_class_suffix; no strict 'refs'; if (@{"$resultset_class\::ISA"}) { - $self->result_source_instance->resultset_class($resultset_class); + $self->result_source_instance->resultset_class($resultset_class); } else { - $self->result_source_instance->resultset_class($self->base_resultset_class); + $self->result_source_instance->resultset_class + ($self->base_resultset_class); } } @@ -67,25 +69,37 @@ __END__ =head1 NAME - DBIx::Class::ResultSetManager - helpful methods for managing resultset classes (EXPERIMENTAL) + DBIx::Class::ResultSetManager - helpful methods for managing + resultset classes (EXPERIMENTAL) =head1 SYNOPSIS - # in a table class - __PACKAGE__->load_components(qw/ResultSetManager Core/); # note order! - __PACKAGE__->load_resultset_components(qw/AlwaysRS/); + # in a table class + __PACKAGE__->load_components(qw/ResultSetManager Core/); # note order! + __PACKAGE__->load_resultset_components(qw/AlwaysRS/); - # will be removed from the table class and inserted into a table-specific resultset class - sub foo : ResultSet { ... } + # will be removed from the table class and inserted into a + # table-specific resultset class + sub search_by_year_desc : ResultSet { + my $self = shift; + my $cond = shift; + my $attrs = shift || {}; + $attrs->{order_by} = 'year DESC'; + $self->next::method($cond, $attrs); + } + + $rs = $schema->resultset('CD')->search_by_year_desc({ artist => 'Tool' }); =head1 DESCRIPTION -This package implements two useful features for customizing resultset classes. -C loads components in addition to C -(or whatever you set as C). Any methods tagged with the C -attribute will be moved into a table-specific resultset class (by default called -C, but configurable via C). -Most of the magic is done when you call C<< __PACKAGE__->table >>. +This package implements two useful features for customizing resultset +classes. C loads components in addition to +C (or whatever you set as +C). Any methods tagged with the C +attribute will be moved into a table-specific resultset class (by +default called C, but configurable via +C). Most of the magic is done when you +call C<< __PACKAGE__->table >>. =head1 AUTHORS diff --git a/lib/DBIx/Class/ResultSource.pm b/lib/DBIx/Class/ResultSource.pm index 4331a15..e4ba46f 100644 --- a/lib/DBIx/Class/ResultSource.pm +++ b/lib/DBIx/Class/ResultSource.pm @@ -293,13 +293,18 @@ sub storage { shift->schema->storage; } $source->add_relationship('relname', 'related_source', $cond, $attrs); -The relation name can be arbitrary, but must be unique for each relationship -attached to this result source. 'related_source' should be the name with -which the related result source was registered with the current schema -(for simple schemas this is usally either Some::Namespace::Foo or just Foo) +The relationship name can be arbitrary, but must be unique for each +relationship attached to this result source. 'related_source' should +be the name with which the related result source was registered with +the current schema. For example: -The condition needs to be an SQL::Abstract-style representation of the join -between the tables. For example, if you're creating a rel from Author to Book, + $schema->source('Book')->add_relationship('reviews', 'Review', { + 'foreign.book_id' => 'self.id', + }); + +The condition C<$cond> needs to be an SQL::Abstract-style +representation of the join between the tables. For example, if you're +creating a rel from Author to Book, { 'foreign.author_id' => 'self.id' } @@ -321,15 +326,18 @@ the SQL command immediately before C. =item proxy -An arrayref containing a list of accessors in the foreign class to -proxy in the main class. If, for example, you do the following: - - __PACKAGE__->might_have(bar => 'Bar', undef, { proxy => [ qw/margle/] }); - -Then, assuming Bar has an accessor named margle, you can do: +An arrayref containing a list of accessors in the foreign class to proxy in +the main class. If, for example, you do the following: + + CD->might_have(liner_notes => 'LinerNotes', undef, { + proxy => [ qw/notes/ ], + }); + +Then, assuming LinerNotes has an accessor named notes, you can do: - my $obj = Foo->find(1); - $obj->margle(10); # set margle; Bar object is created if it doesn't exist + my $cd = CD->find(1); + $cd->notes('Notes go here'); # set notes -- LinerNotes object is + # created if it doesn't exist =item accessor diff --git a/lib/DBIx/Class/ResultSourceProxy/Table.pm b/lib/DBIx/Class/ResultSourceProxy/Table.pm index 0d76f3f..1c93aed 100644 --- a/lib/DBIx/Class/ResultSourceProxy/Table.pm +++ b/lib/DBIx/Class/ResultSourceProxy/Table.pm @@ -9,23 +9,25 @@ __PACKAGE__->load_components(qw/AccessorGroup/); __PACKAGE__->mk_group_accessors('component_class' => 'table_class'); __PACKAGE__->table_class('DBIx::Class::ResultSource::Table'); -__PACKAGE__->mk_classdata('table_alias'); # FIXME: Doesn't actually do anything yet! +__PACKAGE__->mk_classdata('table_alias'); # FIXME: Doesn't actually do + # anything yet! =head1 NAME -DBIx::Class::ResultSourceProxy::Table - provides a classdata table object and method proxies +DBIx::Class::ResultSourceProxy::Table - provides a classdata table +object and method proxies =head1 SYNOPSIS - __PACKAGE__->table('foo'); - __PACKAGE__->add_columns(qw/id bar baz/); - __PACKAGE__->set_primary_key('id'); + __PACKAGE__->table('cd'); + __PACKAGE__->add_columns(qw/cdid artist title year/); + __PACKAGE__->set_primary_key('cdid'); =head1 METHODS =head2 add_columns - __PACKAGE__->add_columns(qw/col1 col2 col3/); + __PACKAGE__->add_columns(qw/cdid artist title year/); Adds columns to the current class and creates accessors for them. @@ -44,7 +46,8 @@ sub table { return $class->result_source_instance->name unless $table; unless (ref $table) { $table = $class->table_class->new({ - $class->can('result_source_instance') ? %{$class->result_source_instance} : (), + $class->can('result_source_instance') ? + %{$class->result_source_instance} : (), name => $table, result_class => $class, }); diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm index 114c04b..19b49c3 100644 --- a/lib/DBIx/Class/Schema.pm +++ b/lib/DBIx/Class/Schema.pm @@ -18,30 +18,30 @@ DBIx::Class::Schema - composable schemas =head1 SYNOPSIS - package My::Schema; + package Library::Schema; use base qw/DBIx::Class::Schema/; - # load My::Schema::Foo, My::Schema::Bar, My::Schema::Baz - __PACKAGE__->load_classes(qw/Foo Bar Baz/); + # load Library::Schema::CD, Library::Schema::Book, Library::Schema::DVD + __PACKAGE__->load_classes(qw/CD Book DVD/); - package My::Schema::Foo; + package Library::Schema::CD; use base qw/DBIx::Class/; __PACKAGE__->load_components(qw/PK::Auto::Pg Core/); # for example - __PACKAGE__->table('foo'); + __PACKAGE__->table('cd'); # Elsewhere in your code: - my $schema1 = My::Schema->connect( + my $schema1 = Library::Schema->connect( $dsn, $user, $password, - $attrs + { AutoCommit => 0 }, ); - my $schema2 = My::Schema->connect($coderef_returning_dbh); + my $schema2 = Library::Schema->connect($coderef_returning_dbh); - # fetch objects using My::Schema::Foo - my $resultset = $schema1->resultset('Foo')->search( ... ); - my @objects = $schema2->resultset('Foo')->search( ... ); + # fetch objects using Library::Schema::DVD + my $resultset = $schema1->resultset('DVD')->search( ... ); + my @dvd_objects = $schema2->resultset('DVD')->search( ... ); =head1 DESCRIPTION @@ -93,7 +93,7 @@ sub register_source { =head2 class - my $class = $schema->class('Foo'); + my $class = $schema->class('CD'); Retrieves the result class name for a given result source @@ -106,7 +106,7 @@ sub class { =head2 source - my $source = $schema->source('Foo'); + my $source = $schema->source('Book'); Returns the result source object for the registered name @@ -136,7 +136,7 @@ sub sources { return keys %{shift->source_registrations}; } =head2 resultset - my $rs = $schema->resultset('Foo'); + my $rs = $schema->resultset('DVD'); Returns the resultset for the registered moniker @@ -233,8 +233,8 @@ this connection. It will also setup a ->class method on the target class, which lets you resolve database classes based on the schema component name, for example - MyApp::DB->class('Foo') # returns MyApp::DB::Foo, - # which ISA MyApp::Schema::Foo + Library::Model::DB->class('Book') # returns Library::Model::Book, + # which ISA Library::Schema::Book This is the recommended API for accessing Schema generated classes, and using it might give you instant advantages with future versions of DBIC. @@ -401,22 +401,22 @@ includes a "Rollback failed" message. For example, - my $foo = $schema->resultset('foo')->find(1); + my $author_rs = $schema->resultset('Author')->find(1); my $coderef = sub { - my ($foo, @bars) = @_; + my ($author, @titles) = @_; # If any one of these fails, the entire transaction fails - $foo->create_related('bars', { - col => $_ - }) foreach (@bars); + $author->create_related('books', { + title => $_ + }) foreach (@titles); - return $foo->bars; + return $author->books; }; my $rs; eval { - $rs = $schema->txn_do($coderef, $foo, qw/foo bar baz/); + $rs = $schema->txn_do($coderef, $author_rs, qw/Night Day It/); }; if ($@) { @@ -425,12 +425,13 @@ For example, die "something terrible has happened!"; } else { deal_with_failed_transaction(); - die $error; } } Nested transactions work as expected (i.e. only the outermost -transaction will issue a txn_commit on the Schema's storage) +transaction will issue a txn_commit on the Schema's storage), and +txn_do() can be called in void, scalar and list context and it will +behave as expected. =cut @@ -449,8 +450,8 @@ sub txn_do { my $wantarray = wantarray; # Need to save this since it's reset in eval{} eval { - # Need to differentiate between scalar/list context to allow for returning - # a list in scalar context to get the size of the list + # Need to differentiate between scalar/list context to allow for + # returning a list in scalar context to get the size of the list if ($wantarray) { # list context @@ -514,10 +515,10 @@ Populates the source registered with the given moniker with the supplied data. @data should be a list of listrefs, the first containing column names, the second matching values - i.e. - $schema->populate('Foo', [ - [ qw/foo_id foo_string/ ], - [ 1, 'One' ], - [ 2, 'Two' ], + $schema->populate('Artist', [ + [ qw/artistid name/ ], + [ 1, 'Popular Band' ], + [ 2, 'Indie Band' ], ... ]); diff --git a/lib/DBIx/Class/Serialize/Storable.pm b/lib/DBIx/Class/Serialize/Storable.pm index 8066337..fc94fa2 100644 --- a/lib/DBIx/Class/Serialize/Storable.pm +++ b/lib/DBIx/Class/Serialize/Storable.pm @@ -12,7 +12,8 @@ sub STORABLE_freeze { sub STORABLE_thaw { my ($self,$cloning,$serialized) = @_; %$self = %{ Storable::thaw($serialized) }; - $self->result_source($self->result_source_instance) if $self->can('result_source_instance'); + $self->result_source($self->result_source_instance) + if $self->can('result_source_instance'); } 1; @@ -21,7 +22,8 @@ __END__ =head1 NAME - DBIx::Class::Serialize::Storable - hooks for Storable freeze/thaw (EXPERIMENTAL) + DBIx::Class::Serialize::Storable - hooks for Storable freeze/thaw + (EXPERIMENTAL) =head1 SYNOPSIS @@ -29,14 +31,17 @@ __END__ __PACKAGE__->load_components(qw/Serialize::Storable/); # meanwhile, in a nearby piece of code - my $obj = $schema->resultset('Foo')->find(12); - $cache->set($obj->ID, $obj); # if the cache uses Storable, this will work automatically + my $cd = $schema->resultset('CD')->find(12); + $cache->set($cd->ID, $cd); # if the cache uses Storable, this + # will work automatically =head1 DESCRIPTION -This component adds hooks for Storable so that row objects can be serialized. It assumes that -your row object class (C) is the same as your table class, which is the normal -situation. However, this code is not yet well tested, and so should be considered experimental. +This component adds hooks for Storable so that row objects can be +serialized. It assumes that your row object class (C) is +the same as your table class, which is the normal situation. However, +this code is not yet well tested, and so should be considered +experimental. =head1 AUTHORS