From: David Kamholz Date: Sun, 26 Mar 2006 00:15:00 +0000 (+0000) Subject: various small doc fixes X-Git-Tag: v0.06001~29 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=2053ab2a47d0cbf3db670003d01a9b4650bc46d6;p=dbsrgits%2FDBIx-Class.git various small doc fixes --- diff --git a/lib/DBIx/Class.pm b/lib/DBIx/Class.pm index f78aac8..1812b4d 100644 --- a/lib/DBIx/Class.pm +++ b/lib/DBIx/Class.pm @@ -38,7 +38,7 @@ DBIx::Class - Extensible and flexible object <-> relational mapper. =head1 SYNOPSIS -Create a base schema class called DB/Main.pm: +Create a schema class called DB/Main.pm: package DB::Main; use base qw/DBIx::Class::Schema/; @@ -47,7 +47,7 @@ Create a base schema class called DB/Main.pm: 1; -Create a class to represent artists, who have many CDs, in DB/Main/Artist.pm: +Create a table class to represent artists, who have many CDs, in DB/Main/Artist.pm: package DB::Main::Artist; use base qw/DBIx::Class/; @@ -56,51 +56,55 @@ Create a class to represent artists, who have many CDs, in DB/Main/Artist.pm: __PACKAGE__->table('artist'); __PACKAGE__->add_columns(qw/ artistid name /); __PACKAGE__->set_primary_key('artistid'); - __PACKAGE__->has_many('cds' => 'DB::Main::CD'); + __PACKAGE__->has_many(cds => 'DB::Main::CD'); 1; -A class to represent a CD, which belongs to an artist, in DB/Main/CD.pm: +A table class to represent a CD, which belongs to an artist, in DB/Main/CD.pm: package DB::Main::CD; use base qw/DBIx::Class/; __PACKAGE__->load_components(qw/PK::Auto Core/); __PACKAGE__->table('cd'); - __PACKAGE__->add_columns(qw/ cdid artist title year/); + __PACKAGE__->add_columns(qw/ cdid artist title year /); __PACKAGE__->set_primary_key('cdid'); - __PACKAGE__->belongs_to('artist' => 'DB::Main::Artist'); + __PACKAGE__->belongs_to(artist => 'DB::Main::Artist'); 1; Then you can use these classes in your application's code: # Connect to your database. - my $ds = DB::Main->connect(@dbi_dsn); + use DB::Main; + my $schema = DB::Main->connect($dbi_dsn, $user, $pass, \%dbi_params); # Query for all artists and put them in an array, # or retrieve them as a result set object. - my @all_artists = $ds->resultset('Artist')->all; - my $all_artists_rs = $ds->resultset('Artist'); + my @all_artists = $schema->resultset('Artist')->all; + my $all_artists_rs = $schema->resultset('Artist'); # Create a result set to search for artists. # This does not query the DB. - my $johns_rs = $ds->resultset('Artist')->search( - # Build your WHERE using an SQL::Abstract structure: - { 'name' => { 'like', 'John%' } } + my $johns_rs = $schema->resultset('Artist')->search( + # Build your WHERE using an L structure: + { name => { like => 'John%' } } ); - # This executes a joined query to get the cds + # Execute a joined query to get the cds. my @all_john_cds = $johns_rs->search_related('cds')->all; - # Queries but only fetches one row so far. + # Fetch only the next row. my $first_john = $johns_rs->next; + # Specify ORDER BY on the query. my $first_john_cds_by_title_rs = $first_john->cds( undef, { order_by => 'title' } ); + # Create a result set that will fetch the artist relationship + # at the same time as it fetches CDs, using only one query. my $millennium_cds_rs = $ds->resultset('CD')->search( { year => 2000 }, { prefetch => 'artist' } @@ -130,27 +134,26 @@ JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support. DBIx::Class can handle multi-column primary and foreign keys, complex queries and database-level paging, and does its best to only query the -database when it actually needs to in order to return something you've directly -asked for. If a resultset is used as an iterator it only fetches rows off -the statement handle as requested in order to minimise memory usage. It -has auto-increment support for SQLite, MySQL, PostgreSQL, Oracle, SQL -Server and DB2 and is known to be used in production on at least the first -four, and is fork- and thread-safe out of the box (although your DBD may not -be). +database in order to return something you've directly asked for. If a +resultset is used as an iterator it only fetches rows off the statement +handle as requested in order to minimise memory usage. It has auto-increment +support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is +known to be used in production on at least the first four, and is fork- +and thread-safe out of the box (although your DBD may not be). This project is still under rapid development, so features added in the -latest major release may not work 100% yet - check the Changes if you run +latest major release may not work 100% yet -- check the Changes if you run into trouble, and beware of anything explicitly marked EXPERIMENTAL. Failing test cases are *always* welcome and point releases are put out rapidly as bugs are found and fixed. Even so, we do our best to maintain full backwards compatibility for published -APIs since DBIx::Class is used in production in a number of organisations; -the test suite is now fairly substantial and several developer releases are +APIs, since DBIx::Class is used in production in a number of organisations. +The test suite is quite substantial, and several developer releases are generally made to CPAN before the -current branch is merged back to trunk for a major release. -The community can be found via - +The community can be found via: Mailing list: http://lists.rawmode.org/mailman/listinfo/dbix-class/ diff --git a/lib/DBIx/Class/CDBICompat.pm b/lib/DBIx/Class/CDBICompat.pm index dc4c8d2..830a0e6 100644 --- a/lib/DBIx/Class/CDBICompat.pm +++ b/lib/DBIx/Class/CDBICompat.pm @@ -68,7 +68,7 @@ provided it looks something like this: CDBICompat::MightHave /); -=head1 Components +=head1 COMPONENTS =over 4 @@ -94,12 +94,8 @@ Allows you to turn on automatic updates for column values. =item HasA -Responsible for HasA relationships. - =item HasMany -Responsible for HasMany relationships. - =item ImaDBI =item LazyLoading @@ -111,8 +107,6 @@ in the perl interpreter. =item MightHave -Responsible for MightHave relationships. - =item ObjIndexStubs =item ReadOnly @@ -125,8 +119,6 @@ Responsible for MightHave relationships. =item Triggers -This class implements the trigger functionality. - =item PassThrough =back diff --git a/lib/DBIx/Class/Core.pm b/lib/DBIx/Class/Core.pm index 0a319dc..c1b292c 100644 --- a/lib/DBIx/Class/Core.pm +++ b/lib/DBIx/Class/Core.pm @@ -35,6 +35,8 @@ The core modules currently are: =over 4 +=item L + =item L =item L diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm index 22e9129..bd6ede7 100644 --- a/lib/DBIx/Class/ResultSet.pm +++ b/lib/DBIx/Class/ResultSet.pm @@ -184,7 +184,7 @@ sub new { # year = 2005 OR year = 2004 If you need to pass in additional attributes but no additional condition, -call it as C. +call it as C. # "SELECT name, artistid FROM $artist_table" my @all_artists = $schema->resultset('Artist')->search(undef, { @@ -345,7 +345,7 @@ sub find { name => 'Emo-R-Us', }); -Search the specified relationship, optionally specify a condition and +Searches the specified relationship, optionally specifying a condition and attributes for matching records. See L for more information. =cut @@ -428,7 +428,7 @@ sub single { # WHERE title LIKE '%blue%' $cd_rs = $rs->search_like({ title => '%blue%'}); -Perform a search, but use C instead of C<=> as the condition. Note +Performs a search, but uses C instead of C<=> as the condition. Note that this is simply a convenience method. You most likely want to use L with specific operators. @@ -455,8 +455,8 @@ sub search_like { =back Returns a resultset or object list representing a subset of elements from the -resultset slice is called on. Indexes are from 0 - i.e. to get the first -three records, call +resultset slice is called on. Indexes are from 0, i.e., to get the first +three records, call: my ($one, $two, $three) = $rs->slice(0, 2); @@ -770,7 +770,7 @@ sub reset { =back Resets the resultset and returns an object for the first result (if the -resultset contains anything). +resultset returns anything). =cut @@ -813,8 +813,8 @@ sub update { =back -Fetches all objects and updates them one at a time. Note that C -will run cascade triggers while L will not. +Fetches all objects and updates them one at a time. Note that C +will run DBIC cascade triggers, while L will not. =cut @@ -839,7 +839,8 @@ sub update_all { =back Deletes the contents of the resultset from its result source. Note that this -will not run cascade triggers. See L if you need triggers to run. +will not run DBIC cascade triggers. See L if you need triggers +to run. =cut @@ -897,8 +898,8 @@ sub delete { =back -Fetches all objects and deletes them one at a time. Note that C -will run cascade triggers while L will not. +Fetches all objects and deletes them one at a time. Note that C +will run DBIC cascade triggers, while L will not. =cut @@ -945,7 +946,7 @@ sub pager { Returns a resultset for the $page_number page of the resultset on which page is called, where each page contains a number of rows equal to the 'rows' -attribute set on the resultset, or 10 by default +attribute set on the resultset (10 by default). =cut @@ -1067,9 +1068,9 @@ sub find_or_create { $class->update_or_create({ col => $val, ... }); -First, search for an existing row matching one of the unique constraints -(including the primary key) on the source of this resultset. If a row is -found, update it with the other given column values. Otherwise, create a new +First, searches for an existing row matching one of the unique constraints +(including the primary key) on the source of this resultset. If a row is +found, updates it with the other given column values. Otherwise, creates a new row. Takes an optional C attribute to search on a specific unique constraint. @@ -1088,7 +1089,7 @@ For example: If no C is specified, it searches on all unique constraints defined on the source, including the primary key. -If the C is specified as C, search only on the primary key. +If the C is specified as C, it searches only on the primary key. See also L and L. @@ -1138,7 +1139,7 @@ sub update_or_create { =back -Gets the contents of the cache for the resultset if the cache is set +Gets the contents of the cache for the resultset, if the cache is set. =cut diff --git a/lib/DBIx/Class/ResultSource.pm b/lib/DBIx/Class/ResultSource.pm index 6773ed4..700d01e 100644 --- a/lib/DBIx/Class/ResultSource.pm +++ b/lib/DBIx/Class/ResultSource.pm @@ -54,13 +54,12 @@ sub new { $table->add_columns('col1' => \%col1_info, 'col2' => \%col2_info, ...); -Adds columns to the result source. If supplied key => hashref pairs uses -the hashref as the column_info for that column. +Adds columns to the result source. If supplied key => hashref pairs, uses +the hashref as the column_info for that column. Repeated calls of this +method will add more columns, not replace them. -Repeated calls of this method will add more columns, not replace them. - -The contents of the column_info are not set in stone, the following -keys are currently recognised/used by DBIx::Class. +The contents of the column_info are not set in stone. The following +keys are currently recognised/used by DBIx::Class: =over 4 @@ -71,15 +70,15 @@ the name of the column will be used. =item data_type -This contains the column type, it is automatically filled by the +This contains the column type. It is automatically filled by the L producer, and the -L module. If you do not enter the +L module. If you do not enter a data_type, DBIx::Class will attempt to retrieve it from the -database for you, using Ls column_info method. The values of this +database for you, using L's column_info method. The values of this key are typically upper-cased. -Currently there is no standard set of values for the data_type, use -whatever your database(s) support. +Currently there is no standard set of values for the data_type. Use +whatever your database supports. =item size @@ -88,31 +87,32 @@ restriction. This is currently not used by DBIx::Class. =item is_nullable -If the column is allowed to contain NULL values, set a true value -(typically 1), here. This is currently not used by DBIx::Class. +Set this to a true value for a columns that is allowed to contain +NULL values. This is currently not used by DBIx::Class. =item is_auto_increment -Set this to a true value if this is a column that is somehow -automatically filled. This is used to determine which columns to empty +Set this to a true value for a column whose value is somehow +automatically set. This is used to determine which columns to empty when cloning objects using C. =item is_foreign_key -Set this to a true value if this column represents a key from a +Set this to a true value for a column that contains a key from a foreign table. This is currently not used by DBIx::Class. =item default_value -Set this to the default value which will be inserted into this column -by the database. Can contain either values or functions. This is +Set this to the default value which will be inserted into a column +by the database. Can contain either a value or a function. This is currently not used by DBIx::Class. =item sequence -Sets the name of the sequence to use to generate values. If not -specified, L will attempt to retrieve the -name of the sequence from the database automatically. +Set this on a primary key column to the name of the sequence used to +generate a new key value. If not specified, L +will attempt to retrieve the name of the sequence from the database +automatically. =back @@ -120,7 +120,7 @@ name of the sequence from the database automatically. $table->add_column('col' => \%info?); -Convenience alias to add_columns +Convenience alias to add_columns. =cut @@ -147,7 +147,7 @@ sub add_columns { if ($obj->has_column($col)) { ... } -Returns 1 if the source has a column of this name, 0 otherwise. +Returns true if the source has a column of this name, false otherwise. =cut @@ -193,7 +193,7 @@ sub column_info { my @column_names = $obj->columns; -Returns all column names in the order they were declared to add_columns +Returns all column names in the order they were declared to add_columns. =cut @@ -249,9 +249,8 @@ sub primary_columns { Declare a unique constraint on this source. Call once for each unique constraint. Unique constraints are used when you call C on a -L, only columns in the constraint are searched, - -e.g., +L. Only columns in the constraint are searched, +for example: # For UNIQUE (column1, column2) __PACKAGE__->add_unique_constraint( @@ -286,8 +285,8 @@ sub unique_constraints { =head2 from Returns an expression of the source to be supplied to storage to specify -retrieval from this source; in the case of a database the required FROM clause -contents. +retrieval from this source. In the case of a database, the required FROM +clause contents. =cut @@ -314,7 +313,7 @@ the current schema. For example: 'foreign.book_id' => 'self.id', }); -The condition C<$cond> needs to be an SQL::Abstract-style +The condition C<$cond> needs to be an L-style representation of the join between the tables. For example, if you're creating a rel from Author to Book, @@ -348,8 +347,8 @@ the main class. If, for example, you do the following: Then, assuming LinerNotes has an accessor named notes, you can do: my $cd = CD->find(1); - $cd->notes('Notes go here'); # set notes -- LinerNotes object is - # created if it doesn't exist + # set notes -- LinerNotes object is created if it doesn't exist + $cd->notes('Notes go here'); =item accessor @@ -408,7 +407,7 @@ sub add_relationship { =head2 relationships -Returns all valid relationship names for this source +Returns all relationship names for this source. =cut @@ -424,7 +423,8 @@ sub relationships { =back -Returns the relationship information for the specified relationship name +Returns a hash of relationship information for the specified relationship +name. =cut @@ -441,7 +441,7 @@ sub relationship_info { =back -Returns 1 if the source has a relationship of this name, 0 otherwise. +Returns true if the source has a relationship of this name, false otherwise. =cut @@ -458,7 +458,7 @@ sub has_relationship { =back -Returns the join structure required for the related result source +Returns the join structure required for the related result source. =cut @@ -645,7 +645,7 @@ sub resolve_prefetch { =back -Returns the result source object for the given relationship +Returns the result source object for the given relationship. =cut @@ -665,7 +665,7 @@ sub related_source { =back -Returns the class object for the given relationship +Returns the class name for objects in the given relationship. =cut @@ -713,7 +713,7 @@ sub resultset { =head2 throw_exception -See throw_exception in L. +See L. =cut @@ -726,7 +726,6 @@ sub throw_exception { } } - =head1 AUTHORS Matt S. Trout diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm index 9a6acca..e0cb8cc 100644 --- a/lib/DBIx/Class/Schema.pm +++ b/lib/DBIx/Class/Schema.pm @@ -50,7 +50,7 @@ use L and allows you to use more than one concurrent connection with your classes. NB: If you're used to L it's worth reading the L -carefully as DBIx::Class does things a little differently. Note in +carefully, as DBIx::Class does things a little differently. Note in particular which module inherits off which. =head1 METHODS @@ -64,7 +64,7 @@ particular which module inherits off which. =back Registers a class which isa L. Equivalent to -calling +calling: $schema->register_source($moniker, $component_class->result_source_instance); @@ -111,9 +111,7 @@ sub register_source { =back -Retrieves the result class name for the given moniker. - -e.g., +Retrieves the result class name for the given moniker. For example: my $class = $schema->class('CD'); @@ -161,8 +159,7 @@ sub source { =back Returns the source monikers of all source registrations on this schema. - -e.g., +For example: my @source_monikers = $schema->sources; @@ -203,11 +200,11 @@ With no arguments, this method uses L to find all classes under the schema's namespace. Otherwise, this method loads the classes you specify (using L), and registers them (using L). -It is possible to comment out classes with a leading '#', but note that perl -will think it's a mistake (trying to use a comment in a qw list) so you'll -need to add "no warnings 'qw';" before your load_classes call. +It is possible to comment out classes with a leading C<#>, but note that perl +will think it's a mistake (trying to use a comment in a qw list), so you'll +need to add C before your load_classes call. -e.g., +Example: My::Schema->load_classes(); # loads My::Schema::CD, My::Schema::Artist, # etc. (anything under the My::Schema namespace) @@ -292,10 +289,10 @@ sub load_classes { =back -Calls L to the target namespace, -calls L(@db_info) on the new schema, then -injects the L component and a resultset_instance -classdata entry on all the new classes in order to support +Calls L to the target namespace, +calls L with @db_info on the new schema, +then injects the L component and a +resultset_instance classdata entry on all the new classes, in order to support $target_namespaces::$class->search(...) method calls. This is primarily useful when you have a specific need for class method access @@ -365,13 +362,13 @@ new $schema object. If C<$additional_base_class> is given, the new composed classes will inherit from first the corresponding classe from the current schema then the base class. -e.g. (for a schema with My::Schema::CD and My::Schema::Artist classes), +For example, for a schema with My::Schema::CD and My::Schema::Artist classes, $schema->compose_namespace('My::DB', 'Base::Class'); print join (', ', @My::DB::CD::ISA) . "\n"; print join (', ', @My::DB::Artist::ISA) ."\n"; -Will produce the output +will produce the output My::Schema::CD, Base::Class My::Schema::Artist, Base::Class diff --git a/lib/DBIx/Class/Serialize/Storable.pm b/lib/DBIx/Class/Serialize/Storable.pm index c9f1314..45a8285 100644 --- a/lib/DBIx/Class/Serialize/Storable.pm +++ b/lib/DBIx/Class/Serialize/Storable.pm @@ -24,7 +24,6 @@ __END__ =head1 NAME DBIx::Class::Serialize::Storable - hooks for Storable freeze/thaw - (EXPERIMENTAL) =head1 SYNOPSIS @@ -33,16 +32,14 @@ __END__ # meanwhile, in a nearby piece of code my $cd = $schema->resultset('CD')->find(12); - $cache->set($cd->ID, $cd); # if the cache uses Storable, this - # will work automatically + # if the cache uses Storable, this will work automatically + $cache->set($cd->ID, $cd); =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. +the same as your table class, which is the normal situation. =head1 AUTHORS