From: Justin Guenther <jguenther@cpan.org>
Date: Tue, 21 Mar 2006 12:03:55 +0000 (+0000)
Subject: changed Foo/Bar in docs to more meaningful names
X-Git-Tag: v0.06000~50
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=24d67825c6b2e604a349ccd5de0df1956c0d98dc;p=dbsrgits%2FDBIx-Class.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<search(undef, \%attrs);>.
 
-  # "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<foo DESC> 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<year DESC> for a
+descending order on the column `year'.
 
 =head2 columns
 
@@ -991,9 +994,13 @@ use the C<cols> 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<as>
 attribute, the column names returned are storage-dependent. E.g. MySQL would
-return a column named C<count(column_to_count)> in the above example.
+return a column named C<count(employeeid)> in the above example.
 
 =head2 as
 
@@ -1026,29 +1030,26 @@ Indicates column names for object inflation. This is used in conjunction with
 C<select>, usually when C<select> 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<as>, 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<get_column> 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<DBIx::Class::Manual::Cookbook> for details.
@@ -1087,13 +1088,15 @@ For example:
 If the same join is supplied twice, it will be aliased to <rel>_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<prefetch>
 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<load_resultset_components> loads components in addition to C<DBIx::Class::ResultSet>
-(or whatever you set as C<base_resultset_class>). Any methods tagged with the C<ResultSet>
-attribute will be moved into a table-specific resultset class (by default called
-C<Class::_resultset>, but configurable via C<table_resultset_class_suffix>). 
-Most of the magic is done when you call C<< __PACKAGE__->table >>.  
+This package implements two useful features for customizing resultset
+classes.  C<load_resultset_components> loads components in addition to
+C<DBIx::Class::ResultSet> (or whatever you set as
+C<base_resultset_class>). Any methods tagged with the C<ResultSet>
+attribute will be moved into a table-specific resultset class (by
+default called C<Class::_resultset>, but configurable via
+C<table_resultset_class_suffix>).  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<JOIN>.
 
 =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<result_class>) 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<result_class>) 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