From: Brendan Byrd Date: Thu, 14 Mar 2013 22:26:21 +0000 (-0400) Subject: Clean up of "DBIx::Class" references to "DBIC" X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=784b08baaf54257b9ba914edab2ec827337315bd;p=dbsrgits%2FDBIx-Class.git Clean up of "DBIx::Class" references to "DBIC" --- diff --git a/lib/DBIx/Class.pm b/lib/DBIx/Class.pm index 630230b..eef586d 100644 --- a/lib/DBIx/Class.pm +++ b/lib/DBIx/Class.pm @@ -265,7 +265,7 @@ Then you can use these classes in your application's code: =head1 DESCRIPTION -This is an SQL to OO mapper with an object API inspired by L +DBIx::Class (aka DBIC) is an SQL to OO mapper with an object API inspired by L (with a compatibility layer as a springboard for porting) and a resultset API that allows abstract encapsulation of database operations. It aims to make representing queries in your code as perl-ish as possible while still @@ -273,7 +273,7 @@ providing access to as many of the capabilities of the database as possible, including retrieving related records from multiple tables in a single query, JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support. -DBIx::Class can handle multi-column primary and foreign keys, complex +DBIC can handle multi-column primary and foreign keys, complex queries and database-level paging, and does its best to only query the 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 @@ -289,7 +289,7 @@ Failing test cases are *always* welcome and point releases are put out rapidly as bugs are found and fixed. We do our best to maintain full backwards compatibility for published -APIs, since DBIx::Class is used in production in many organisations, +APIs, since DBIC is used in production in many organisations, and even backwards incompatible changes to non-published APIs will be fixed if they're reported and doing so doesn't cost the codebase anything. @@ -556,7 +556,7 @@ zamolxes: Bogdan Lucaciu =head1 COPYRIGHT -Copyright (c) 2005 - 2011 the DBIx::Class L and L +Copyright (c) 2005 - 2012 the DBIC L and L as listed above. =head1 LICENSE diff --git a/lib/DBIx/Class/Admin.pm b/lib/DBIx/Class/Admin.pm index b0d76b8..955da94 100644 --- a/lib/DBIx/Class/Admin.pm +++ b/lib/DBIx/Class/Admin.pm @@ -56,7 +56,7 @@ DBIx::Class::Admin - Administration object for schemas =head1 REQUIREMENTS The Admin interface has additional requirements not currently part of -L. See L for more details. +L. See L for more details. =head1 ATTRIBUTES @@ -297,7 +297,7 @@ has '_confirm' => ( =head2 trace -Toggle DBIx::Class debug output +Toggle L debug output =cut @@ -583,13 +583,13 @@ sub _find_stanza { return $cfg; } -=head1 AUTHOR +=head1 AUTHOR AND CONTRIBUTORS -See L. +See L and L in DBIx::Class =head1 LICENSE -You may distribute this code under the same terms as Perl itself +You may distribute this code under the same terms as Perl itself. =cut diff --git a/lib/DBIx/Class/CDBICompat.pm b/lib/DBIx/Class/CDBICompat.pm index ee983fd..bd00b2f 100644 --- a/lib/DBIx/Class/CDBICompat.pm +++ b/lib/DBIx/Class/CDBICompat.pm @@ -61,19 +61,21 @@ DBIx::Class::CDBICompat - Class::DBI Compatibility layer. =head1 DESCRIPTION -DBIx::Class features a fully featured compatibility layer with L +L features a fully featured compatibility layer with L and some common plugins to ease transition for existing CDBI users. -This is not a wrapper or subclass of DBIx::Class but rather a series of plugins. The result being that even though you're using the Class::DBI emulation layer you are still getting DBIx::Class objects. You can use all DBIx::Class features and methods via CDBICompat. This allows you to take advantage of DBIx::Class features without having to rewrite your CDBI code. +This is not a wrapper or subclass of L but rather a series of plugins. The result being that even though you're using the +L emulation layer you are still getting L objects. You can use all L features and methods +via CDBICompat. This allows you to take advantage of L features without having to rewrite your L code. =head2 Plugins -CDBICompat is good enough that many CDBI plugins will work with CDBICompat, but many of the plugin features are better done with DBIx::Class methods. +CDBICompat is good enough that many CDBI plugins will work with CDBICompat, but many of the plugin features are better done with L methods. =head3 Class::DBI::AbstractSearch -C is fully emulated using DBIC's search. Aside from emulation there's no reason to use C. +C is fully emulated using L's search. Aside from emulation there's no reason to use C. =head3 Class::DBI::Plugin::NoCache @@ -81,11 +83,12 @@ C is fully emulated. =head3 Class::DBI::Sweet -The features of CDBI::Sweet are better done using DBIC methods which are almost exactly the same. It even uses L. +The features of CDBI::Sweet are better done using L methods which are almost exactly the same. It even uses L. =head3 Class::DBI::Plugin::DeepAbstractSearch -This plugin will work, but it is more efficiently done using DBIC's native search facilities. The major difference is that DBIC will not infer the join for you, you have to tell it the join tables. +This plugin will work, but it is more efficiently done using L's native search facilities. The major difference is that +L will not infer the join for you, you have to tell it the join tables. =head2 Choosing Features diff --git a/lib/DBIx/Class/CDBICompat/Iterator.pm b/lib/DBIx/Class/CDBICompat/Iterator.pm index eb60177..c442b92 100644 --- a/lib/DBIx/Class/CDBICompat/Iterator.pm +++ b/lib/DBIx/Class/CDBICompat/Iterator.pm @@ -16,7 +16,7 @@ See DBIx::Class::CDBICompat for usage directions. Emulates the extra behaviors of the Class::DBI search iterator. -=head2 Differences from DBIx::Class result set +=head2 Differences from DBIC result set The CDBI iterator returns true if there were any results, false otherwise. The DBIC result set always returns true. diff --git a/lib/DBIx/Class/Carp.pm b/lib/DBIx/Class/Carp.pm index d27df5d..3ce678e 100644 --- a/lib/DBIx/Class/Carp.pm +++ b/lib/DBIx/Class/Carp.pm @@ -126,7 +126,7 @@ sub unimport { =head1 NAME -DBIx::Class::Carp - Provides advanced Carp::Clan-like warning functions for DBIx::Class internals +DBIx::Class::Carp - Provides advanced Carp::Clan-like warning functions for DBIC internals =head1 DESCRIPTION diff --git a/lib/DBIx/Class/Core.pm b/lib/DBIx/Class/Core.pm index 39407dc..28be6df 100644 --- a/lib/DBIx/Class/Core.pm +++ b/lib/DBIx/Class/Core.pm @@ -18,7 +18,7 @@ __PACKAGE__->load_components(qw/ =head1 NAME -DBIx::Class::Core - Core set of DBIx::Class modules +DBIx::Class::Core - Core set of DBIC modules =head1 SYNOPSIS @@ -28,7 +28,7 @@ DBIx::Class::Core - Core set of DBIx::Class modules =head1 DESCRIPTION This class just inherits from the various modules that make up the -L core features. You almost certainly want these. +L core features. You almost certainly want these. The core modules currently are: diff --git a/lib/DBIx/Class/Exception.pm b/lib/DBIx/Class/Exception.pm index 1f56cb5..37427ef 100644 --- a/lib/DBIx/Class/Exception.pm +++ b/lib/DBIx/Class/Exception.pm @@ -32,7 +32,7 @@ overload fallback to give natural boolean/numeric values. =back -This is meant for internal use by L's C +This is meant for internal use by L's C code, and shouldn't be used directly elsewhere. Expects a scalar exception message. The optional argument diff --git a/lib/DBIx/Class/InflateColumn.pm b/lib/DBIx/Class/InflateColumn.pm index 9214582..5675c8c 100644 --- a/lib/DBIx/Class/InflateColumn.pm +++ b/lib/DBIx/Class/InflateColumn.pm @@ -48,7 +48,7 @@ something else, see L. =head2 inflate_column -Instruct L to inflate the given column. +Instruct L to inflate the given column. In addition to the column name, you must provide C and C methods. The C method is called when you access @@ -196,7 +196,7 @@ sub store_inflated_column { =over 4 =item L - This component is loaded as part of the - C L components; generally there is no need to + C L components; generally there is no need to load it directly =back diff --git a/lib/DBIx/Class/InflateColumn/File.pm b/lib/DBIx/Class/InflateColumn/File.pm index aa06dbc..140e696 100644 --- a/lib/DBIx/Class/InflateColumn/File.pm +++ b/lib/DBIx/Class/InflateColumn/File.pm @@ -135,7 +135,7 @@ DBIx::Class::InflateColumn::File - DEPRECATED (superseded by DBIx::Class::Infla =head1 SYNOPSIS -In your L table class: +In your L table class: use base 'DBIx::Class::Core'; diff --git a/lib/DBIx/Class/Manual.pod b/lib/DBIx/Class/Manual.pod index 60cced0..85883c2 100644 --- a/lib/DBIx/Class/Manual.pod +++ b/lib/DBIx/Class/Manual.pod @@ -4,9 +4,9 @@ DBIx::Class::Manual - Index of the Manual =head1 DESCRIPTION -This is the L users manual. DBIx::Class is a SQL->OOP mapper. -This means that it can represent your SQL tables as perl classes, and give -you convenient accessors and methods for retrieving and updating information +This is the L users manual. L is a SQL->OOP +mapper. This means that it can represent your SQL tables as perl classes, and +give you convenient accessors and methods for retrieving and updating information from your SQL database. =head1 SECTIONS diff --git a/lib/DBIx/Class/Manual/Component.pod b/lib/DBIx/Class/Manual/Component.pod index 46170f9..53edfca 100644 --- a/lib/DBIx/Class/Manual/Component.pod +++ b/lib/DBIx/Class/Manual/Component.pod @@ -1,11 +1,11 @@ =head1 NAME -DBIx::Class::Manual::Component - Developing DBIx::Class Components +DBIx::Class::Manual::Component - Developing DBIC Components =head1 WHAT IS A COMPONENT -A component is a module that can be added in to your DBIx::Class +A component is a module that can be added in to your L classes to provide extra functionality. A good example is the PK::Auto component which automatically retrieves primary keys that the database itself creates, after the insert has happened. @@ -13,14 +13,14 @@ itself creates, after the insert has happened. =head1 USING Components are loaded using the load_components() method within your -DBIx::Class classes. +L classes. package My::Thing; use base qw( DBIx::Class::Core ); __PACKAGE__->load_components(qw/InflateColumn::DateTime TimeStamp/); Generally you do not want to specify the full package name -of a component, instead take off the DBIx::Class:: part of +of a component, instead take off the C part of it and just include the rest. If you do want to load a component outside of the normal namespace you can do so by prepending the component name with a +. @@ -132,6 +132,6 @@ L - Basic row methods. L -=head1 AUTHOR +=head1 AUTHOR AND CONTRIBUTORS -Aran Clary Deltac +See L and L in DBIx::Class diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod index 21d720e..3fcc0a9 100644 --- a/lib/DBIx/Class/Manual/Cookbook.pod +++ b/lib/DBIx/Class/Manual/Cookbook.pod @@ -6,7 +6,7 @@ DBIx::Class::Manual::Cookbook - Miscellaneous recipes =head2 Paged results -When you expect a large number of results, you can ask L for a +When you expect a large number of results, you can ask L for a paged resultset, which will fetch only a defined number of records at a time: my $rs = $schema->resultset('Artist')->search( @@ -301,7 +301,7 @@ See also L. =head2 Grouping results -L supports C as follows: +L supports C as follows: my $rs = $schema->resultset('Artist')->search( {}, @@ -396,7 +396,7 @@ into the C directory next to your C directory, and it will be automatically loaded. If however you are still using L, first tell -DBIx::Class to create an instance of the ResultSet class for you, in your +L to create an instance of the ResultSet class for you, in your My::DBIC::Schema::CD class: # class definition as normal @@ -418,7 +418,7 @@ Using SQL functions on the left hand side of a comparison is generally not a good idea since it requires a scan of the entire table. (Unless your RDBMS supports indexes on expressions - including return values of functions - and you create an index on the return value of the function in question.) However, -it can be accomplished with C when necessary by resorting to +it can be accomplished with L when necessary by resorting to literal SQL: $rs->search(\[ 'YEAR(date_of_birth) = ?', [ plain_value => 1979 ] ]); @@ -481,7 +481,8 @@ cause instability on your server at worst, beware! You can use the C attribute to allow searching on, or sorting your results by, one or more columns in a related table. -This requires that you have defined the L. For example : +This requires that you have defined the L. +For example: My::Schema::CD->has_many( artists => 'My::Schema::Artist', 'artist_id'); @@ -536,7 +537,7 @@ artist. The following will work fine: There is a problem however. We have searched both the C and C tables in our main query, but we have only returned data from the C table. To get -the artist name for any of the CD objects returned, L will go back +the artist name for any of the CD objects returned, L will go back to the database: SELECT artist.* FROM artist WHERE artist.id = ? @@ -545,7 +546,7 @@ A statement like the one above will run for each and every CD returned by our main query. Five CDs, five extra queries. A hundred CDs, one hundred extra queries! -Thankfully, L has a C attribute to solve this problem. +Thankfully, L has a C attribute to solve this problem. This allows you to fetch results from related tables in advance: my $rs = $schema->resultset('CD')->search( @@ -571,7 +572,7 @@ The code to print the CD list remains the same: print "CD: " . $cd->title . ", Artist: " . $cd->artist->name; } -L has now prefetched all matching data from the C table, +L has now prefetched all matching data from the C table, so no additional SQL statements are executed. You now have a much more efficient query. @@ -791,7 +792,7 @@ Just use C instead, then check C: # do whatever else you wanted if it was a new row } -=head2 Static sub-classing DBIx::Class result classes +=head2 Static sub-classing DBIC result classes AKA adding additional relationships/methods/etc. to a model for a specific usage of the (shared) model. @@ -833,11 +834,11 @@ B 1; -=head2 Dynamic Sub-classing DBIx::Class proxy classes +=head2 Dynamic Sub-classing DBIC proxy classes AKA multi-class object inflation from one table -L classes are proxy classes, therefore some different +L classes are proxy classes, therefore some different techniques need to be employed for more than basic subclassing. In this example we have a single user table that carries a boolean bit for admin. We would like like to give the admin users @@ -966,7 +967,7 @@ exactly the above functionality. =head2 Skip result object creation for faster results -DBIx::Class is not built for speed, it's built for convenience and +L is not built for speed, it's built for convenience and ease of use, but sometimes you just need to get the data, and skip the fancy objects. @@ -988,7 +989,7 @@ load_components, eg L. =head2 Get raw data for blindingly fast results If the L solution -above is not fast enough for you, you can use a DBIx::Class to return values +above is not fast enough for you, you can use L to return values exactly as they come out of the database with none of the convenience methods wrapped round them. @@ -1223,13 +1224,13 @@ building a renaming facility, like so: 1; -By overridding the L -method and extracting a custom option from the provided \%attr hashref one can +By overridding the L +method and extracting a custom option from the provided \%attr hashref, one can then simply iterate over all the Schema's ResultSources, renaming them as needed. To use this facility, simply add or modify the \%attr hashref that is passed to -L, as follows: +L, as follows: my $schema = MyDatabase::Schema->connect( @@ -1612,14 +1613,14 @@ L. =head2 Schema versioning -The following example shows simplistically how you might use DBIx::Class to -deploy versioned schemas to your customers. The basic process is as follows: +The following example shows simplistically how you might use L +to deploy versioned schemas to your customers. The basic process is as follows: =over 4 =item 1. -Create a DBIx::Class schema +Create a L =item 2. @@ -1670,8 +1671,8 @@ B As your application evolves, it may be necessary to modify your schema to change functionality. Once the changes are made to your schema in -DBIx::Class, export the modified schema and the conversion scripts as -in L. +L, export the modified schema and the conversion scripts +as in L. B @@ -1759,7 +1760,7 @@ passing them as bind values: See L and L for more explanation. Note that -L sets L to C, so you must pass +L sets L to C, so you must pass the bind values (the C<[1, 2, 3]> arrayref in the above example) wrapped in arrayrefs together with the column name, like this: C<< [column_name => value] >>. @@ -1815,7 +1816,7 @@ then strange and unexpected data corrupt B occur. The Catalyst Wiki Unicode page at L has additional information on the use of Unicode with Catalyst and -DBIx::Class. +L. The following databases do correctly handle unicode data:- @@ -1870,7 +1871,7 @@ C). =head2 Easy migration from class-based to schema-based setup -You want to start using the schema-based approach to L +You want to start using the schema-based approach to L (see L), but have an established class-based setup with lots of existing classes that you don't want to move by hand. Try this nifty script instead: @@ -1908,10 +1909,10 @@ namespace, which is currently left as an exercise for the reader. =head1 OVERLOADING METHODS -L uses the L package, which provides for redispatch of +L uses the L package, which provides for redispatch of method calls, useful for things like default values and triggers. You have to use calls to C to overload methods. More information on using -L with L can be found in +L with L can be found in L. =head2 Setting default values for a row @@ -1933,7 +1934,7 @@ For more information about C, look in the L documentation. See also L for more ways to write your own base classes to do this. -People looking for ways to do "triggers" with DBIx::Class are probably +People looking for ways to do "triggers" with L are probably just looking for this. =head2 Changing one field whenever another changes @@ -2037,7 +2038,7 @@ Next, we'll define the accessor-wrapper subroutine: =head1 DEBUGGING AND PROFILING -=head2 DBIx::Class objects with Data::Dumper +=head2 DBIC objects with Data::Dumper L can be a very useful tool for debugging, but sometimes it can be hard to find the pertinent data in all the data it can generate. @@ -2186,7 +2187,7 @@ See also L and L in this document. =head1 STARTUP SPEED -L programs can have a significant startup delay +L programs can have a significant startup delay as the ORM loads all the relevant classes. This section examines techniques for reducing the startup delay. @@ -2210,7 +2211,7 @@ details on creating static schemas from a database). =head2 Move Common Startup into a Base Class -Typically L result classes start off with +Typically L result classes start off with use base qw/DBIx::Class::Core/; __PACKAGE__->load_components(qw/InflateColumn::DateTime/); @@ -2251,7 +2252,7 @@ avoiding L. =head2 Cached statements -L normally caches all statements with L<< prepare_cached()|DBI/prepare_cached >>. +L normally caches all statements with L<< prepare_cached()|DBI/prepare_cached >>. This is normally a good idea, but if too many statements are cached, the database may use too much memory and may eventually run out and fail entirely. If you suspect this may be the case, you may want to examine DBI's L<< CachedKids|DBI/CachedKidsCachedKids_(hash_ref) >> hash: diff --git a/lib/DBIx/Class/Manual/DocMap.pod b/lib/DBIx/Class/Manual/DocMap.pod index 83c9633..5b94e5a 100644 --- a/lib/DBIx/Class/Manual/DocMap.pod +++ b/lib/DBIx/Class/Manual/DocMap.pod @@ -12,7 +12,7 @@ DBIx::Class::Manual::DocMap - What documentation do we have? =item L - Full example Schema. -=item L - How to use DBIx::Class if you know SQL (external, available on CPAN) +=item L - How to use DBIC if you know SQL (external, available on CPAN) =item L - What do all those terms mean? diff --git a/lib/DBIx/Class/Manual/Example.pod b/lib/DBIx/Class/Manual/Example.pod index 2d0e2e3..155cd09 100644 --- a/lib/DBIx/Class/Manual/Example.pod +++ b/lib/DBIx/Class/Manual/Example.pod @@ -25,7 +25,7 @@ And these rules exists: =head2 Installation -Install DBIx::Class via CPAN should be sufficient. +Install L via CPAN should be sufficient. =head3 Create the database/tables @@ -350,7 +350,7 @@ It should output: =head1 Notes A reference implementation of the database and scripts in this example -are available in the main distribution for DBIx::Class under the +are available in the main distribution for L under the directory F. With these scripts we're relying on @INC looking in the current diff --git a/lib/DBIx/Class/Manual/FAQ.pod b/lib/DBIx/Class/Manual/FAQ.pod index 051ae30..9f8827b 100644 --- a/lib/DBIx/Class/Manual/FAQ.pod +++ b/lib/DBIx/Class/Manual/FAQ.pod @@ -5,7 +5,7 @@ DBIx::Class::Manual::FAQ - Frequently Asked Questions (in theory) =head1 DESCRIPTION This document is intended as an anti-map of the documentation. If you -know what you want to do, but not how to do it in L, then +know what you want to do, but not how to do it in L, then look here. It does B contain much code or examples, it just gives explanations and pointers to the correct pieces of documentation to read. @@ -30,27 +30,27 @@ go to L. Now, decide whether you want to have the database itself be the definitive source of information about the data layout, or your -DBIx::Class schema. If it's the former, look up the documentation for -your database, eg. L, on how -to create tables, and start creating them. For a nice universal +L. If it's the former, look up the +documentation for your database, eg. L, +on how to create tables, and start creating them. For a nice universal interface to your database, you can try L. If you decided on the latter choice, read the FAQ on setting up your classes manually, and the one on creating tables from your schema. -=item .. use DBIx::Class with L? +=item .. use DBIC with L? Install L from CPAN. See its documentation, or below, for further details. -=item .. set up my DBIx::Class classes automatically from my database? +=item .. set up my DBIC classes automatically from my database? Install L from CPAN, and read its documentation. -=item .. set up my DBIx::Class classes manually? +=item .. set up my DBIC classes manually? Look at the L and come back here if you get lost. -=item .. create my database tables from my DBIx::Class schema? +=item .. create my database tables from my DBIC schema? Create your classes manually, as above. Write a script that calls L. See there for details, or the @@ -73,11 +73,11 @@ connection does not happen until you actually request data, so don't be alarmed if the error from incorrect connection details happens a lot later. -=item .. use DBIx::Class across multiple databases? +=item .. use DBIC across multiple databases? If your database server allows you to run querys across multiple -databases at once, then so can DBIx::Class. All you need to do is make -sure you write the database name as part of the +databases at once, then so can L. All you need to do +is make sure you write the database name as part of the L call. Eg: __PACKAGE__->table('mydb.mytablename'); @@ -85,7 +85,7 @@ L call. Eg: And load all the Result classes for both / all databases using one L call. -=item .. use DBIx::Class across PostgreSQL/DB2/Oracle schemas? +=item .. use DBIC across PostgreSQL/DB2/Oracle schemas? Add the name of the schema to the L as part of the name, and make sure you give the one user you are going @@ -98,7 +98,7 @@ necessary. =over 4 -=item .. tell DBIx::Class about relationships between my tables? +=item .. tell DBIC about relationships between my tables? There are a variety of relationship types that come pre-defined for you to use. These are all listed in L. If @@ -137,9 +137,9 @@ as you like. See L. The term 'relationship' is used loosely with many_to_many as it is not considered a relationship in the fullest sense. For more info, read the documentation on L. -=item .. stop DBIx::Class from attempting to cascade deletes on my has_many and might_have relationships? +=item .. stop DBIC from attempting to cascade deletes on my has_many and might_have relationships? -By default, DBIx::Class cascades deletes and updates across +By default, L cascades deletes and updates across C and C relationships. You can disable this behaviour on a per-relationship basis by supplying C<< cascade_delete => 0 >> in the relationship attributes. @@ -147,7 +147,7 @@ C<< cascade_delete => 0 >> in the relationship attributes. The cascaded operations are performed after the requested delete or update, so if your database has a constraint on the relationship, it will have deleted/updated the related records or raised an exception -before DBIx::Class gets to perform the cascaded operation. +before L gets to perform the cascaded operation. See L. @@ -231,7 +231,7 @@ for the join used by each relationship. =item .. create joins with conditions other than column equality? -Currently, L can only create join conditions using +Currently, L can only create join conditions using equality, so you're probably better off creating a C in your database, and using that as your source. A C is a stored SQL query, which can be accessed similarly to a table, see your database @@ -254,7 +254,7 @@ etc.), but this may change in the future. =item .. find more help on constructing searches? -Behind the scenes, DBIx::Class uses L to help construct +Behind the scenes, L uses L to help construct its SQL searches. So if you fail to find help in the L, try looking in the SQL::Abstract documentation. @@ -471,49 +471,49 @@ Invoked like this: =over 4 -=item How do I store my own (non-db) data in my DBIx::Class objects? +=item How do I store my own (non-db) data in my DBIC objects? You can add your own data accessors to your Result classes. One method is to use the built in mk_group_accessors (via L) - package App::Schema::Result::MyTable; + package App::Schema::Result::MyTable; - use parent 'DBIx::Class::Core'; + use parent 'DBIx::Class::Core'; - __PACKAGE__->table('foo'); #etc - __PACKAGE__->mk_group_accessors('simple' => qw/non_column_data/); # must use simple group + __PACKAGE__->table('foo'); #etc + __PACKAGE__->mk_group_accessors('simple' => qw/non_column_data/); # must use simple group -An another method is to use L with your L package. +An another method is to use L with your L package. - package App::Schema::Result::MyTable; + package App::Schema::Result::MyTable; - use Moose; # import Moose - use Moose::Util::TypeConstraint; # import Moose accessor type constraints + use Moose; # import Moose + use Moose::Util::TypeConstraint; # import Moose accessor type constraints - extends 'DBIx::Class::Core'; # Moose changes the way we define our parent (base) package + extends 'DBIx::Class::Core'; # Moose changes the way we define our parent (base) package - has 'non_column_data' => ( is => 'rw', isa => 'Str' ); # define a simple attribute + has 'non_column_data' => ( is => 'rw', isa => 'Str' ); # define a simple attribute - __PACKAGE__->table('foo'); # etc + __PACKAGE__->table('foo'); # etc With either of these methods the resulting use of the accesssor would be - my $row; + my $row; - # assume that somewhere in here $row will get assigned to a MyTable row + # assume that somewhere in here $row will get assigned to a MyTable row - $row->non_column_data('some string'); # would set the non_column_data accessor + $row->non_column_data('some string'); # would set the non_column_data accessor - # some other stuff happens here + # some other stuff happens here - $row->update(); # would not inline the non_column_data accessor into the update + $row->update(); # would not inline the non_column_data accessor into the update -=item How do I use DBIx::Class objects in my TT templates? +=item How do I use DBIC objects in my TT templates? -Like normal objects, mostly. However you need to watch out for TT -calling methods in list context. When calling relationship accessors +Like normal objects, mostly. However, you need to watch out for TT +calling methods in list context. When calling relationship accessors, you will not get resultsets, but a list of all the related objects. Use the L method, or the @@ -525,6 +525,8 @@ See also L. =item See the SQL statements my code is producing? Set the shell environment variable C to a true value. +B<< Not the C variable; >> this has to do with debugging +on the L end of things. For more info see L for details of how to turn on debugging in the environment, pass your own filehandle to @@ -532,7 +534,7 @@ save debug to, or create your own callback. =item Why didn't my search run any SQL? -L runs the actual SQL statement as late as possible, thus +L runs the actual SQL statement as late as possible, thus if you create a resultset using C in scalar context, no query is executed. You can create further resultset refinements by calling search again or relationship accessors. The SQL query is only run when @@ -540,9 +542,9 @@ you ask the resultset for an actual result object. =item How do I deal with tables that lack a primary key? -If your table lacks a primary key, DBIx::Class can't work out which row +If your table lacks a primary key, L can't work out which row it should operate on, for example to delete or update. However, a -UNIQUE constraint on one or more columns allows DBIx::Class to uniquely +UNIQUE constraint on one or more columns allows L to uniquely identify the row, so you can tell L these columns act as a primary key, even if they don't from the database's point of view: @@ -555,7 +557,7 @@ Look at the tips in L =item How do I reduce the overhead of database queries? -You can reduce the overhead of object creation within L +You can reduce the overhead of object creation within L using the tips in L and L diff --git a/lib/DBIx/Class/Manual/Features.pod b/lib/DBIx/Class/Manual/Features.pod index 7c7d5c6..1c5495d 100644 --- a/lib/DBIx/Class/Manual/Features.pod +++ b/lib/DBIx/Class/Manual/Features.pod @@ -1,6 +1,6 @@ =head1 NAME -DBIx::Class::Manual::Features - A boatload of DBIx::Class features with links to respective documentation +DBIx::Class::Manual::Features - A boatload of DBIC features with links to respective documentation =head1 META @@ -30,7 +30,7 @@ L over raw SQL. =head2 Cross DB @@ -216,13 +216,13 @@ Result class =back -=head1 DBIx::Class Specific Features +=head1 DBIC Specific Features These things may be in other ORM's, but they are very specific, so doubtful =head2 ->deploy -Create a database from your DBIx::Class schema. +Create a database from your L. my $schema = Frew::Schema->connect( $dsn, $user, $pass ); @@ -234,7 +234,7 @@ See also: L =head2 Schema::Loader -Create a DBIx::Class schema from your database. +Create a L from your database. package Frew::Schema; @@ -300,7 +300,7 @@ See L =head2 Extensible -DBIx::Class helped pioneer fast MI in Perl 5 with Class::C3, so it is made to +L helped pioneer fast MI in Perl 5 with Class::C3, so it is made to allow extensions to nearly every part of it. =head2 Extensibility example: DBIx::Class::Helpers diff --git a/lib/DBIx/Class/Manual/Glossary.pod b/lib/DBIx/Class/Manual/Glossary.pod index 4feb8e1..7231e2c 100644 --- a/lib/DBIx/Class/Manual/Glossary.pod +++ b/lib/DBIx/Class/Manual/Glossary.pod @@ -9,6 +9,10 @@ explain them. =head1 DBIx::Class TERMS +=head2 DBIC + +Shorthand for L. + =head2 DB schema Refers to a single physical schema within an RDBMS. Synonymous with the terms @@ -23,18 +27,18 @@ the following L(s): =head2 Inflation The act of turning database row data into objects in -language-space. DBIx::Class result classes can be set up to inflate -your data into perl objects which more usefully represent their -contents. For example: L for +language-space. L can +be set up to inflate your data into Perl objects which more usefully represent +their contents. For example: L for datetime or timestamp column data. See also L. =head2 Deflation -The opposite of L. Existing perl objects that represent -column values can be passed to DBIx::Class methods to store into the -database. For example a L object can be automatically +The opposite of L. Existing Perl objects that represent +column values can be passed to L methods to store into the +database. For example, a L object can be automatically deflated into a datetime string for insertion. See L and other modules in that namespace. @@ -43,11 +47,11 @@ See L and other modules in that namespace. Object-relational mapping, or Object-relationship modelling. Either way it's a method of mapping the contents of database tables (rows), -to objects in programming-language-space. DBIx::Class is an ORM. +to objects in programming-language-space. L is an ORM. =head2 Relationship -In DBIx::Class a relationship defines the connection between exactly +In L, a relationship defines the connection between exactly two tables. The relationship condition lists the columns in each table that contain the same values. It is used to output an SQL JOIN condition between the tables. @@ -113,7 +117,8 @@ See Result. Result objects contain your actual data. They are returned from ResultSet objects. These are sometimes (incorrectly) called -row objects, including older versions of the DBIC documentation. +row objects, including older versions of the L +documentation. See also: L diff --git a/lib/DBIx/Class/Manual/Intro.pod b/lib/DBIx/Class/Manual/Intro.pod index 947898a..fb60007 100644 --- a/lib/DBIx/Class/Manual/Intro.pod +++ b/lib/DBIx/Class/Manual/Intro.pod @@ -544,6 +544,6 @@ information on this can be found in L =item * L -=back +=head1 AUTHOR AND CONTRIBUTORS -=cut +See L and L in DBIx::Class diff --git a/lib/DBIx/Class/Manual/Joining.pod b/lib/DBIx/Class/Manual/Joining.pod index 5785349..e9b02e0 100644 --- a/lib/DBIx/Class/Manual/Joining.pod +++ b/lib/DBIx/Class/Manual/Joining.pod @@ -4,8 +4,8 @@ DBIx::Class::Manual::Joining - Manual on joining tables with DBIx::Class =head1 DESCRIPTION -This document should help you to use L if you are trying -to convert your normal SQL queries into DBIx::Class based queries, if +This document should help you to use L if you are trying +to convert your normal SQL queries into L based queries, if you use joins extensively (and also probably if you don't). =head1 WHAT ARE JOINS @@ -39,7 +39,7 @@ L. =head1 DEFINING JOINS AND RELATIONSHIPS -In L each relationship between two tables needs to first +In L each relationship between two tables needs to first be defined in the L for the table. If the relationship needs to be accessed in both directions (i.e. Fetch all tracks of a CD, and fetch the CD data for a Track), @@ -246,7 +246,7 @@ Or combine the two: =head2 Table aliases -As an aside to all the discussion on joins, note that L +As an aside to all the discussion on joins, note that L uses the C as table aliases. This is important when you need to add grouping or ordering to your queries: diff --git a/lib/DBIx/Class/Manual/Reading.pod b/lib/DBIx/Class/Manual/Reading.pod index cb352a2..c55c62b 100644 --- a/lib/DBIx/Class/Manual/Reading.pod +++ b/lib/DBIx/Class/Manual/Reading.pod @@ -1,16 +1,16 @@ =head1 NAME -DBIx::Class::Manual::Reading - How to read and write DBIx::Class POD. +DBIx::Class::Manual::Reading - How to read and write DBIC POD. =head1 DESCRIPTION This doc should help users to understand how the examples and -documentation found in the L distribution can be +documentation found in the L distribution can be interpreted. -Writers of DBIx::Class POD should also check here to make sure their -additions are consistent with the rest of the documentation. +Writers of L POD should also check here to make sure +their additions are consistent with the rest of the documentation. =head1 METHODS diff --git a/lib/DBIx/Class/Manual/ResultClass.pod.proto b/lib/DBIx/Class/Manual/ResultClass.pod.proto index 29ff9e9..d2f5e04 100644 --- a/lib/DBIx/Class/Manual/ResultClass.pod.proto +++ b/lib/DBIx/Class/Manual/ResultClass.pod.proto @@ -39,7 +39,7 @@ a DB query =head1 DESCRIPTION -In L, a user normally receives query results as instances of a +In L, a user normally receives query results as instances of a certain C, depending on the main query source. Besides being the primary "toolset" for interaction with your data, a C also serves to establish source metadata, which is then used during initialization diff --git a/lib/DBIx/Class/Manual/Troubleshooting.pod b/lib/DBIx/Class/Manual/Troubleshooting.pod index f76934e..a95331a 100644 --- a/lib/DBIx/Class/Manual/Troubleshooting.pod +++ b/lib/DBIx/Class/Manual/Troubleshooting.pod @@ -106,7 +106,7 @@ happen to turn on SQL-quoting. $rs->search( {}, { order_by => [ 'name DESC' ] } ); -Since L >= 0.08100 and L >= 1.50 the above +Since L >= 0.08100 and L >= 1.50 the above should be written as: $rs->search( {}, { order_by => { -desc => 'name' } } ); @@ -134,12 +134,12 @@ with full current updates will not be subject to this problem):- This issue is due to perl doing an exhaustive search of blessed objects under certain circumstances. The problem shows up as performance -degradation exponential to the number of L result objects in +degradation exponential to the number of L result objects in memory, so can be unnoticeable with certain data sets, but with huge performance impacts on other datasets. A pair of tests for susceptibility to the issue and performance effects -of the bless/overload problem can be found in the L test +of the bless/overload problem can be found in the L test suite, in the C file. Further information on this issue can be found in diff --git a/lib/DBIx/Class/Optional/Dependencies.pm b/lib/DBIx/Class/Optional/Dependencies.pm index 6af4221..bc69983 100644 --- a/lib/DBIx/Class/Optional/Dependencies.pm +++ b/lib/DBIx/Class/Optional/Dependencies.pm @@ -128,7 +128,7 @@ my $reqs = { }, pod => { title => 'DBIx::Class::Admin', - desc => 'Modules required for the DBIx::Class administrative library', + desc => 'Modules required for the DBIC administrative library', }, }, @@ -138,7 +138,7 @@ my $reqs = { }, pod => { title => 'dbicadmin', - desc => 'Modules required for the CLI DBIx::Class interface dbicadmin', + desc => 'Modules required for the CLI DBIC interface dbicadmin', }, }, @@ -790,14 +790,14 @@ can be found at L EOS '=head1 DESCRIPTION', <<'EOD', -Some of the less-frequently used features of L have external +Some of the less-frequently used features of L have external module dependencies on their own. In order not to burden the average user with modules he will never use, these optional dependencies are not included in the base Makefile.PL. Instead an exception with a descriptive message is thrown when a specific feature is missing one or several modules required for its operation. This module is the central holding place for the current list -of such dependencies, for DBIx::Class core authors, and DBIx::Class extension -authors alike. +of such dependencies, for L core authors, and DBIx::Class +extension authors alike. EOD '=head1 CURRENT REQUIREMENT GROUPS', <<'EOD', @@ -834,7 +834,7 @@ EOD '=item Return Value: \%list_of_requirement_groups', '=back', <<'EOD', -This method should be used by DBIx::Class packagers, to get a hashref of all +This method should be used by L packagers, to get a hashref of all dependencies keyed by dependency group. Each key (group name) can be supplied to one of the group-specific methods below. EOD @@ -845,7 +845,7 @@ EOD '=item Return Value: \%list_of_module_version_pairs', '=back', <<'EOD', -This method should be used by DBIx::Class extension authors, to determine the +This method should be used by L extension authors, to determine the version of modules a specific feature requires in the B version of DBIx::Class. See the L for a real-world example. @@ -868,7 +868,7 @@ EOD '=back', <<"EOD", Returns a single line string suitable for inclusion in larger error messages. -This method would normally be used by DBIx::Class core-module author, to +This method would normally be used by L core-module author, to indicate to the user that he needs to install specific modules before he will be able to use a specific feature. diff --git a/lib/DBIx/Class/Ordered.pm b/lib/DBIx/Class/Ordered.pm index 5e40dc0..c52d4c4 100644 --- a/lib/DBIx/Class/Ordered.pm +++ b/lib/DBIx/Class/Ordered.pm @@ -90,7 +90,7 @@ That's it, now you can change the position of your objects. =head1 DESCRIPTION This module provides a simple interface for modifying the ordered -position of DBIx::Class objects. +position of L objects. =head1 AUTO UPDATE @@ -489,7 +489,7 @@ sub move_to_group { =head2 insert -Overrides the DBIC insert() method by providing a default +Overrides the L by providing a default position number. The default will be the number of rows in the table +1, thus positioning the new record at the last position. @@ -514,7 +514,7 @@ sub insert { =head2 update -Overrides the DBIC update() method by checking for a change +Overrides the L by checking for a change to the position and/or group columns. Movement within a group or to another group is handled by repositioning the appropriate siblings. Position defaults to the end @@ -568,7 +568,7 @@ sub update { =head2 delete -Overrides the DBIC delete() method by first moving the object +Overrides the L by first moving the object to the last position, then deleting it, thus ensuring the integrity of the positions. diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm index c6f744d..6a481ca 100644 --- a/lib/DBIx/Class/Relationship.pm +++ b/lib/DBIx/Class/Relationship.pm @@ -44,7 +44,7 @@ the definition in the L. This class provides methods to set up relationships between the tables in your database model. Relationships are the most useful and powerful -technique that L provides. To create efficient database queries, +technique that L provides. To create efficient database queries, create relationships between any and all tables that have something in common, for example if you have a table Authors: @@ -214,7 +214,7 @@ Cascading deletes are off by default on a C relationship. To turn them on, pass C<< cascade_delete => 1 >> in the $attr hashref. -By default, DBIC will return undef and avoid querying the database if a +By default, L will return undef and avoid querying the database if a C accessor is called when any part of the foreign key IS NULL. To disable this behavior, pass C<< undef_on_null_fk => 0 >> in the C<\%attrs> hashref. @@ -338,7 +338,7 @@ pass C<< cascade_delete => 0 >> in the C<$attr> hashref. The cascaded operations are performed after the requested delete or update, so if your database has a constraint on the relationship, it will have deleted/updated the related records or raised an exception -before DBIx::Class gets to perform the cascaded operation. +before L gets to perform the cascaded operation. If you copy an object in a class with a C relationship, all the related objects will be copied as well. To turn this behaviour off, @@ -427,7 +427,7 @@ hashref. The cascaded operations are performed after the requested delete or update, so if your database has a constraint on the relationship, it will have deleted/updated the related records or raised an exception -before DBIx::Class gets to perform the cascaded operation. +before L gets to perform the cascaded operation. See L for documentation on relationship methods and valid relationship attributes. Also see diff --git a/lib/DBIx/Class/Relationship/Base.pm b/lib/DBIx/Class/Relationship/Base.pm index d1f507e..d6ef9f5 100644 --- a/lib/DBIx/Class/Relationship/Base.pm +++ b/lib/DBIx/Class/Relationship/Base.pm @@ -330,7 +330,7 @@ relationships. =item cascade_delete -By default, DBIx::Class cascades deletes across C, +By default, L cascades deletes across C, C and C relationships. You can disable this behaviour on a per-relationship basis by supplying C<< cascade_delete => 0 >> in the relationship attributes. @@ -338,11 +338,11 @@ C<< cascade_delete => 0 >> in the relationship attributes. The cascaded operations are performed after the requested delete, so if your database has a constraint on the relationship, it will have deleted/updated the related records or raised an exception -before DBIx::Class gets to perform the cascaded operation. +before L gets to perform the cascaded operation. =item cascade_update -By default, DBIx::Class cascades updates across C and +By default, L cascades updates across C and C relationships. You can disable this behaviour on a per-relationship basis by supplying C<< cascade_update => 0 >> in the relationship attributes. diff --git a/lib/DBIx/Class/ResultClass/HashRefInflator.pm b/lib/DBIx/Class/ResultClass/HashRefInflator.pm index 4d002ab..1078be2 100644 --- a/lib/DBIx/Class/ResultClass/HashRefInflator.pm +++ b/lib/DBIx/Class/ResultClass/HashRefInflator.pm @@ -28,7 +28,7 @@ DBIx::Class::ResultClass::HashRefInflator - Get raw hashrefs from a resultset =head1 DESCRIPTION -DBIx::Class is faster than older ORMs like Class::DBI but it still isn't +L is faster than older ORMs like L but it still isn't designed primarily for speed. Sometimes you need to quickly retrieve the data from a massive resultset, while skipping the creation of fancy result objects. Specifying this class as a C for a resultset will change C<< $rs->next >> diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm index 563ca1e..aeec58f 100644 --- a/lib/DBIx/Class/ResultSet.pm +++ b/lib/DBIx/Class/ResultSet.pm @@ -48,7 +48,7 @@ DBIx::Class::ResultSet - Represents a query used for fetching a set of results. =head1 DESCRIPTION A ResultSet is an object which stores a set of conditions representing -a query. It is the backbone of DBIx::Class (i.e. the really +a query. It is the backbone of L (i.e. the really important/useful bit). No SQL is executed on the database when a ResultSet is created, it @@ -698,9 +698,9 @@ C attribute, which is the name of a L (the unique constraint corresponding to the L is always named -C). If the C attribute has been supplied, and DBIC is unable -to construct a query that satisfies the named unique constraint fully ( -non-NULL values for each column member of the constraint) an exception is +C). If the C attribute has been supplied, and L +is unable to construct a query that satisfies the named unique constraint +fully (non-NULL values for each column member of the constraint) an exception is thrown. If no C is specified, the search is carried over all unique constraints @@ -2024,8 +2024,8 @@ sub update { =back Fetches all objects and updates them one at a time via -L. Note that C will run DBIC defined -triggers, while L will not. +L. Note that C will run L +defined triggers, while L will not. =cut @@ -2082,8 +2082,8 @@ sub delete { =back Fetches all objects and deletes them one at a time via -L. Note that C will run DBIC defined -triggers, while L will not. +L. Note that C will run L +defined triggers, while L will not. =cut @@ -3164,7 +3164,7 @@ Currently the source alias that refers to the result set returned by a L/L family method depends on how you got to the resultset: it's C by default, but eg. L aliases it to the related result source name (and keeps C referring to the original result set). The long -term goal is to make L always alias the current resultset as C +term goal is to make L always alias the current resultset as C (and make this method unnecessary). Thus it's currently necessary to use this method in predefined queries (see @@ -3991,7 +3991,7 @@ names: SELECT name, COUNT( employeeid ), MAX( LENGTH( name ) ) AS longest_name FROM employee B You will almost always need a corresponding L attribute when you -use L, to instruct DBIx::Class how to store the result of the column. +use L, to instruct L how to store the result of the column. Also note that the L attribute has nothing to do with the SQL-side 'AS' identifier aliasing. You can however alias a function, so you can use it in e.g. an C clause. This is done via the C<-as> B