From: Brandon Black Date: Mon, 10 Jul 2006 04:44:35 +0000 (+0000) Subject: docs updates, no longer overwrite dumped schema files by default X-Git-Tag: 0.03004~5 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=d65cda9ebaebbf4b6e0e7a9bb9ba20c919afb55c;p=dbsrgits%2FDBIx-Class-Schema-Loader.git docs updates, no longer overwrite dumped schema files by default --- diff --git a/Changes b/Changes index a25350d..b4a332c 100644 --- a/Changes +++ b/Changes @@ -1,5 +1,17 @@ Revision history for Perl extension DBIx::Class::Schema::Loader +0.03004 XXX TDB + - make_schema_at efficiency improvements + - improved debugging output + - column metadata now included in dumped schemas + - new fatal error if loader_options not yet specified at clone() time + - Carp::Clan added, and some dies converted to croaks + - no longer overwrites files when dumping, unless asked + to do so via the dump_overwrite option + - loader_options can now be embedded in the connection info + - Documentation improvements + - Deprecation notices updated + 0.03003 Tue Jun 6 02:22:49 UTC 2006 - Fix inclusion of external add-on class definitions in dump_to_dir output. diff --git a/lib/DBIx/Class/Schema/Loader.pm b/lib/DBIx/Class/Schema/Loader.pm index aee970d..8e6b5fd 100644 --- a/lib/DBIx/Class/Schema/Loader.pm +++ b/lib/DBIx/Class/Schema/Loader.pm @@ -45,10 +45,14 @@ DBIx::Class::Schema::Loader - Dynamic definition of a DBIx::Class::Schema DBIx::Class::Schema::Loader automates the definition of a L by scanning database table definitions and -setting up the columns and primary keys. +setting up the columns, primary keys, and relationships. -DBIx::Class::Schema::Loader currently supports DBI for MySQL, -PostgreSQL, SQLite and DB2. +DBIx::Class::Schema::Loader currently supports only the DBI storage type. +It has explicit support for L, L, L, and +L. Other DBI drivers may function to a greater or lesser +degree with this loader, depending on how much of the DBI spec they +implement, and how standard their implementation is. Patches to make +other DBDs work correctly welcome. See L for notes on writing your own vendor-specific subclass for an unsupported DBD driver. @@ -75,22 +79,21 @@ detailed information on all of the arguments, most of which are only useful in fairly complex scenarios, see the L documentation. -This method is *required*, for backwards compatibility reasons. If -you do not wish to change any options, just call it with an empty -argument list during schema class initialization. +This method is *required* at this time, for backwards compatibility +reasons. If you do not wish to change any options, just call it +with an empty argument list during schema class initialization. + +You should either specify this method before setting the connection +information for your schema, or specify these options as a part of +your connection information (see below). For now it will merely +warn if the ordering is wrong, but in the future this will cause problems. =cut sub loader_options { my $self = shift; - my %args; - if(ref $_[0] eq 'HASH') { - %args = %{$_[0]}; - } - else { - %args = @_; - } + my %args = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_; my $class = ref $self || $self; $args{schema} = $self; @@ -98,7 +101,10 @@ sub loader_options { weaken($args{schema}) if ref $self; $self->_loader_args(\%args); - $self->_invoke_loader if $self->storage && !$class->loader; + if($self->storage && !$class->loader) { + warn "Do not set loader_options after specifying the connection info"; + $self->_invoke_loader; + } $self; } @@ -125,12 +131,27 @@ sub _invoke_loader { =head2 connection -See L. +See L for basic usage. + +If the final argument is a hashref, and it contains a key C, +that key will be deleted, and its value will be used for the loader options, +just as if set via the L method above. + +The actual auto-loading operation (the heart of this module) will be invoked +as soon as the connection information is defined. =cut sub connection { - my $self = shift->next::method(@_); + my $self = shift; + + if($_[-1] && ref $_[-1] eq 'HASH') { + if(my $loader_opts = delete $_[-1]->{loader_options}) { + $self->loader_options($loader_opts); + } + } + + $self = $self->next::method(@_); my $class = ref $self || $self; $self->_invoke_loader if $self->_loader_args && !$class->loader; @@ -301,12 +322,13 @@ code that was written against pre-0.03 versions of this module. This version is intended to be backwards-compatible with pre-0.03 code, but will issue warnings about your usage of deprecated features/methods. +B, +and converting code that uses these methods should be trivial. + =head2 load_from_connection This deprecated method is now roughly an alias for L. -This method *will* disappear in a future version. - For now, using this method will invoke the legacy behavior for backwards compatibility, and merely emit a warning about upgrading your code. @@ -316,8 +338,9 @@ use L just like pre-0.03 versions of this module did. You can force these legacy inflections with the -option C, even after switch over -to the preferred L way of doing things. +option L, +even after switch over to the preferred L way of doing +things. That option will not go away until at least 0.05. See the source of this method for more details. @@ -335,8 +358,9 @@ sub load_from_connection { warn 'You should regenerate your Model files, which may eliminate' . ' the following deprecation warning:'; } - warn 'load_from_connection deprecated, please [re-]read the' - . ' [new] DBIx::Class::Schema::Loader documentation'; + warn 'load_from_connection deprecated, and will dissappear in 0.04000, ' + . 'please [re-]read the [new] DBIx::Class::Schema::Loader ' + . 'documentation'; # Support the old connect_info / dsn / etc args... $args{connect_info} = [ @@ -387,8 +411,7 @@ to tables in other schemas will be silently ignored. At some point in the future, an intelligent way around this might be devised, probably by allowing the C option to be an -arrayref of schemas to load, or perhaps even offering schema -constraint/exclusion options just like the table ones. +arrayref of schemas to load. In "normal" L usage, manually-defined source classes and relationships have no problems crossing vendor schemas. @@ -403,9 +426,8 @@ Based upon the work of IKEBE Tomohiro =head1 THANK YOU -Adam Anderson, Andy Grundman, Autrijus Tang, Dan Kubb, David Naughton, -Randal Schwartz, Simon Flack, Matt S Trout, everyone on #dbix-class, and -all the others who've helped. +Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent +in a bug report or suggestion. =head1 LICENSE diff --git a/lib/DBIx/Class/Schema/Loader/Base.pm b/lib/DBIx/Class/Schema/Loader/Base.pm index 3272b88..a260f35 100644 --- a/lib/DBIx/Class/Schema/Loader/Base.pm +++ b/lib/DBIx/Class/Schema/Loader/Base.pm @@ -28,6 +28,7 @@ __PACKAGE__->mk_ro_accessors(qw/ inflect_plural debug dump_directory + dump_overwrite legacy_default_inflections @@ -64,6 +65,12 @@ Try to automatically detect/setup has_a and has_many relationships. If set to true, each constructive L statement the loader decides to execute will be C-ed before execution. +=head2 db_schema + +Set the name of the schema to load (schema in the sense that your database +vendor means it). Does not currently support loading more than one schema +name. + =head2 constraint Only load tables matching regex. Best specified as a qr// regex. @@ -138,6 +145,10 @@ your existing code if you started developing on a version prior to 0.03 and don't wish to go around updating all your relationship names to the new defaults. +This option will continue to be supported until at least version 0.05xxx, +but may dissappear sometime thereafter. It is recommended that you update +your code to use the newer-style inflections when you have the time. + =head2 dump_directory This option is designed to be a tool to help you transition from this @@ -162,8 +173,16 @@ is meant for one-time manual usage. See L for examples of the recommended way to access this functionality. +=head2 dump_overwrite + +If set to a true value, the dumping code will overwrite existing files. +The default is false, which means the dumping code will die if it encounters +an existing file. + =head1 DEPRECATED CONSTRUCTOR OPTIONS +B + =head2 inflect_map Equivalent to L. @@ -177,7 +196,7 @@ Equivalent to L. You connect these schemas the same way you would any L, which is by calling either C or C on a schema class or object. These options are only supported via the deprecated -C interface, which will be removed in the future. +C interface, which is also being removed in 0.04000. =head1 METHODS @@ -230,7 +249,8 @@ sub new { # Support deprecated arguments for(qw/inflect_map inflect/) { warn "Argument $_ is deprecated in favor of 'inflect_plural'" - if $self->{$_}; + . ", and will be removed in 0.04000" + if $self->{$_}; } $self->{inflect_plural} ||= $self->{inflect_map} || $self->{inflect}; @@ -326,6 +346,7 @@ sub _dump_to_dir { my ($self) = @_; my $target_dir = $self->dump_directory; + my $schema_class = $self->schema_class; croak "Must specify target directory for dumping!" if ! $target_dir; @@ -343,7 +364,9 @@ sub _dump_to_dir { $self->_ensure_dump_subdirs($schema_class); my $schema_fn = $self->_get_dump_filename($schema_class); - open(my $schema_fh, '>', $schema_fn) + croak "$schema_fn exists, will not overwrite" + if -f $schema_fn && !$self->dump_overwrite; + sysopen(my $schema_fh, '>', $schema_fn) or croak "Cannot open $schema_fn for writing: $!"; print $schema_fh qq|package $schema_class;\n\n$tagline\n\n|; print $schema_fh qq|use strict;\nuse warnings;\n\n|; @@ -356,6 +379,8 @@ sub _dump_to_dir { foreach my $src_class (sort keys %{$self->{_dump_storage}}) { $self->_ensure_dump_subdirs($src_class); my $src_fn = $self->_get_dump_filename($src_class); + croak "$src_fn exists, will not overwrite" + if -f $src_fn && !$self->dump_overwrite; open(my $src_fh, '>', $src_fn) or croak "Cannot open $src_fn for writing: $!"; print $src_fh qq|package $src_class;\n\n$tagline\n\n|; diff --git a/t/lib/dbixcsl_common_tests.pm b/t/lib/dbixcsl_common_tests.pm index 62bb632..db95bb2 100644 --- a/t/lib/dbixcsl_common_tests.pm +++ b/t/lib/dbixcsl_common_tests.pm @@ -316,7 +316,7 @@ sub run_tests { isa_ok( $rs_rel4->first, $class4); # find on multi-col pk - my $obj5 = $rsobj5->find( id1 => 1, id2 => 1 ); + my $obj5 = $rsobj5->find({id1 => 1, id2 => 1}); is( $obj5->id2, 1 ); # mulit-col fk def