From: Marcus Ramberg Date: Fri, 14 Oct 2005 14:23:42 +0000 (+0000) Subject: improved docs. X-Git-Tag: v0.05005~200 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=076652e8bd5edaaf4c6c6a65f631bf529bbff41c;p=dbsrgits%2FDBIx-Class.git improved docs. --- diff --git a/Changes b/Changes index 803003c..7a42577 100644 --- a/Changes +++ b/Changes @@ -4,6 +4,7 @@ Revision history for DBIx::Class - Minor bugfix to new (Row.pm) - Schema doesn't die if it can't load a class (Schema.pm) - New UUID columns plugin (UUIDColumns.pm) + - Documentation improvements. 0.03001 2005-09-23 14:00:00 - Fixes to relationship helpers diff --git a/lib/DBIx/Class.pm b/lib/DBIx/Class.pm index ef46276..9bee70f 100644 --- a/lib/DBIx/Class.pm +++ b/lib/DBIx/Class.pm @@ -68,6 +68,18 @@ for DBIx::Class::Table, ::Row, ::Schema, ::DB and ::Relationship, and have a look at t/lib/DBICTest.pm for a brief example. +=head1 SEE ALSO + +=over 4 + +=item L - DBIC Core Classes + +=item L Compat layer. + +=item L - User's manual. + +=back + =head1 AUTHOR Matt S. Trout diff --git a/lib/DBIx/Class/Core.pm b/lib/DBIx/Class/Core.pm index 5dc4096..85b9fa3 100644 --- a/lib/DBIx/Class/Core.pm +++ b/lib/DBIx/Class/Core.pm @@ -24,8 +24,28 @@ DBIx::Class::Core - Core set of DBIx::Class modules. =head1 DESCRIPTION This class just inherits from the various modules that makes -up the DBIx::Class core features. +up the DBIx::Class core features. This makes it a convenient base +class for your DBIx::Class setup. +At the moment those are: + +=over 4 + +=item L + +=item L + +=item L + +=item L + +=item L + +=item L + +=item L + +=back =head1 AUTHORS diff --git a/lib/DBIx/Class/DB.pm b/lib/DBIx/Class/DB.pm index a758b8f..7d1b5ca 100644 --- a/lib/DBIx/Class/DB.pm +++ b/lib/DBIx/Class/DB.pm @@ -33,6 +33,17 @@ This class provides a simple way of specifying a database connection. =over 4 + +=item storage + +Which storage backend to be used. Defaults to L + +=item class_resolver + +Which class to use for resolving a class. Defaults to +L, which returns whatever you throw +at it. See resolve_class below. + =cut __PACKAGE__->mk_classdata('storage'); diff --git a/lib/DBIx/Class/Manual.pod b/lib/DBIx/Class/Manual.pod new file mode 100644 index 0000000..8ef5213 --- /dev/null +++ b/lib/DBIx/Class/Manual.pod @@ -0,0 +1,34 @@ +=head1 USER MANUAL + +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 +from your SQL database. + +=head1 SECTIONS + +=over 4 + +=item L + +A beginner's introduction to using the native DBIx::Class interface + +=item L + +Convenient reciepes for DBIC usage. + +=item L + +Frequently asked questions about DBIC. + +=item L + +Got trouble? Let us shoot it for you. + +=back + +If you're using the CDBI Compat layer, we suggest reading the L +documentation. It should behave the same way. + +=cut + diff --git a/lib/DBIx/Class/Manual/Intro.pod b/lib/DBIx/Class/Manual/Intro.pod new file mode 100644 index 0000000..158f2bc --- /dev/null +++ b/lib/DBIx/Class/Manual/Intro.pod @@ -0,0 +1,167 @@ +=head1 Introduction. + +So, you are bored with SQL, and want a native perl interface for your classes? +Or you've been doing this for a while with L, and think there's +a better way? You've come to the right place. Let's look at how you can set +and use your first native DBIx::Class tree. + +First we'll see how you can set up your classes yourself. If you want them +to be auto-discovered, just skip to the next section, which shows you how +to use DBIx::Class::Loader. + +=head2 Setting it up manually + +First, you'll need a base class. It should inherit from DBIx::Class +like this: + + package MyApp::DB + use base qw/DBIx::Class/; + +You will also want to load some of L's components. +L provides a good basic set. In addition you'll +have to use either L or L We'll +use DB in this introduction, since it involves less magic. + + __PACKAGE__->load_components(qw/Core DB/); + +If you want serial/auto-incremental primary keys, you'll need to add +the apropriate component for your db as well, for example + + __PACKAGE__->load_components(qw/Core DB PK::Auto::SQLite/); + +Once you've loaded the components, it's time to set up your connection: + + __PACKAGE__->connection('dbi:SQLite:/home/me/myapp/my.db'); + +This method is similar to the normal L, and can take user/pass/dbi +attribute hash as well as the dsn. + +With that out of the way, we can define our first table class: + + package MyApp::DB::Frob + + use base qw/MyApp::DB/; + +Then we specify which table it uses, + + __PACKAGE__->table('frob'); + +and specify which columns it has. + + __PACKAGE__->add_columns(qw/id foo bar/); + +This will automatically create accessors for each of the columns, so that +you can read/update the values in rows you've retrieved. + +Also, you need to tell it which column is the primary key: + + __PACKAGE__->set_primary_key('id'); + +If you have multiple primary keys, just pass a list instead. + +That's pretty much all you need for a basic setup. If you have more advanced +needs like using more than 1 database connections for the same class, see +L. + +=head2 Using L. + +This is an additional class, and not part of the DBIx::Class distribution. +Like L, it inspects your database, and automatically +creates classes for all the tables in your database. Here's a simple setup: + + package MyApp::DB; + + use DBIx::Class::Loader; + + my $loader=DBIx::Class::Loader->new( + dsn => 'dbi:SQLite:/home/me/myapp/my.db', + namespace => 'MyApp::DB'); + 1; + +This should be equivalent to the manual in the section above. +L takes lots of other options. For more information, +consult the reference documentation. + +=head2 Basic Usage + +Once you've defined the basic classes, you can start interacting with your +database. The simplest way to get a column is by primary key: + + my $frob=MyApp::DB::Frob->find(14); + +This will run a select with id=14 in the WHERE clause, and return an instance +of MyApp::DB::Frob that represents this row. Once you have that row, you can +access and update columns + + my $val=$frob->bar; + $frob->bar(14); + +or if you prefer, you can use the set_column/get_column accessors instead +of the autogenerated accessors based on your column names. + +Just like with L, you do an 'update' to commit your changes +to the database: + + $frob->update; + +If needed, you can drop your local changes instead like this: + + $frob->discard_changes if $frob->is_changed; + +As you can see, is_changed allows you to check if there are local changes to +your object. + +=head2 Adding and removing rows. + +To make a new row, and put it into the database, you can use the 'create' +method from L + + my $new_thingie=MyApp::DB::Frob->create({ + foo=>'homer', + bar=>'bart' }); + +likewise, you can remove if from the database like this: + + $new_thingie->delete(); + +or even without retrieving first. This operation takes the same kind of +arguments as a search. + + MyApp::DB::Frob->delete({foo=>'bart'}); + +=head2 Finding your objects. + +DBIx::Class provides a few different ways to retrieve data from your database. +The simplest looks something like this: + + $rs=MyApp::DB::Frob->search(foo=>'bart'); + +note that all the search methods return a recordset in scalar context or +a list containing all the elements in list context. + +We also provide a handy shortcut for doing a like search: + + $rs=MyApp::DB::Frob->search_like(foo=>'bar%'); + +Or you can provide your own handmade WHERE clause, like + + $rs=MyApp::DB::Frob->search_literal('foo=?','bart'); + +The other way to provide more complex queries, is to provide a +L construct to search: + + $rs=MyApp::DB::Frob->search({ + bar=>{'>' => 10 }, + foo=>{'!=','bart'}, + id => [1,14,15,65,43] + }); + +The search can also be modifyed by passing another hash with attributes: + + $rs=MyApp::DB::Frob->search( {foo=>'bart'}, + { page=>1, rows=>2, order_by=>'bar' } ); + +For a complete overview over the available attributes, see +L + +=cut diff --git a/lib/DBIx/Class/PK.pm b/lib/DBIx/Class/PK.pm index 859eba3..3dba00d 100644 --- a/lib/DBIx/Class/PK.pm +++ b/lib/DBIx/Class/PK.pm @@ -35,6 +35,12 @@ sub _ident_values { return (map { $self->{_column_data}{$_} } keys %{$self->_primaries}); } +=item set_primary_key <@cols> + +define one or more columns as primary key for this class + +=cut + sub set_primary_key { my ($class, @cols) = @_; my %pri; @@ -42,6 +48,12 @@ sub set_primary_key { $class->_primaries(\%pri); } +=item find + +Finds columns based on the primary key(s). + +=cut + sub find { my ($class, @vals) = @_; my $attrs = (@vals > 1 && ref $vals[$#vals] eq 'HASH' ? pop(@vals) : {}); @@ -69,6 +81,12 @@ sub find { return (@row ? $class->_row_to_object(\@cols, \@row) : ()); } +=item discard_changes + +Roll back changes that hasn't been comitted to the database. + +=cut + sub discard_changes { my ($self) = @_; delete $self->{_dirty_columns}; @@ -85,6 +103,13 @@ sub discard_changes { return $self; } +=item id + +returns the primary key(s) for the current row. Can't be called as +a class method. + +=cut + sub id { my ($self) = @_; $self->throw( "Can't call id() as a class method" ) unless ref $self; @@ -92,6 +117,12 @@ sub id { return (wantarray ? @pk : $pk[0]); } +=item primary_columns + +read-only accessor which returns a list of primary keys. + +=cut + sub primary_columns { return keys %{shift->_primaries}; } diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm index 3297235..c56480a 100644 --- a/lib/DBIx/Class/ResultSet.pm +++ b/lib/DBIx/Class/ResultSet.pm @@ -170,4 +170,38 @@ sub page { return $self->new($self->{class}, $attrs); } +=head1 NAME + +DBIX::Class::Recordset - Responsible for fetching and creating recordsets. + +=head1 SYNOPSIS; + +$rs=MyApp::DB::Class->search(registered=>1); + + +=head1 Attributes + +The recordset is responsible for handling the various attributes that +can be passed in with the search functions. Here's an overview of them: + +=over 4 + +=item order_by + +Which column to order the results by. +=item page + +Should the resultset be paged? This can also be enabled by using the +'page' option. + +=item rows + +For paged resultsset, how many rows per page + +=item offset + +For paged resultsset, which page to start on. + +=back + 1; diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm index 4fe3a67..72c1583 100644 --- a/lib/DBIx/Class/Schema.pm +++ b/lib/DBIx/Class/Schema.pm @@ -48,6 +48,12 @@ DBIx::Class::Schema - composable schemas =over 4 +=item register_class + +Registers the class in the schema's class_registrations. This is a hash +containing components, and their representative classes. It's used by +compose_connection to create/modify all the existing database classes. + =cut sub register_class { @@ -57,10 +63,26 @@ sub register_class { $class->class_registrations(\%reg); } +=item registered_classes + +Simple read-only accessor for the schema's registered classes. See +register_class above if you want to modify it. + + +=cut + sub registered_classes { return values %{shift->class_registrations}; } +=item load_classes [} + +Uses L to find all components, unless specified explicitly. +Then it loads the component (using L), and registers them (using +B + +=cut + sub load_classes { my $class = shift; my @comp = grep { $_ !~ /^#/ } @_; @@ -78,6 +100,10 @@ sub load_classes { } } +=item compose_connection + +=cut + sub compose_connection { my ($class, $target, @info) = @_; my $conn_class = "${target}::_db"; @@ -103,6 +129,10 @@ sub compose_connection { $conn_class->class_resolver($target); } +=item setup_connection_class <$target> <@info> + +=cut + sub setup_connection_class { my ($class, $target, @info) = @_; $class->inject_base($target => 'DBIx::Class');