clarify use_moose doc
[dbsrgits/DBIx-Class-Schema-Loader.git] / lib / DBIx / Class / Schema / Loader / Base.pm
index 997b7e0..46357c2 100644 (file)
@@ -20,9 +20,10 @@ use Class::Inspector ();
 use Data::Dumper::Concise;
 use Scalar::Util 'looks_like_number';
 use File::Slurp 'slurp';
+use DBIx::Class::Schema::Loader::Utils 'split_name';
 require DBIx::Class;
 
-our $VERSION = '0.07000';
+our $VERSION = '0.07001';
 
 __PACKAGE__->mk_group_ro_accessors('simple', qw/
                                 schema
@@ -49,6 +50,7 @@ __PACKAGE__->mk_group_ro_accessors('simple', qw/
                                 default_resultset_class
                                 schema_base_class
                                 result_base_class
+                                use_moose
                                overwrite_modifications
 
                                 relationship_attrs
@@ -64,6 +66,7 @@ __PACKAGE__->mk_group_ro_accessors('simple', qw/
                                 datetime_locale
                                 config_file
                                 loader_class
+                                qualify_objects
 /);
 
 
@@ -128,7 +131,7 @@ overwriting a dump made with an earlier version.
 
 The option also takes a hashref:
 
-    naming => { relationships => 'v6', monikers => 'v6' }
+    naming => { relationships => 'v7', monikers => 'v7' }
 
 The keys are:
 
@@ -142,6 +145,10 @@ How to name relationship accessors.
 
 How to name Result classes.
 
+=item column_accessors
+
+How to name column accessors in Result classes.
+
 =back
 
 The values can be:
@@ -177,12 +184,11 @@ In general, there is very little difference between v5 and v6 schemas.
 This mode is identical to C<v6> mode, except that monikerization of CamelCase
 table names is also done correctly.
 
-CamelCase column names in case-sensitive mode will also be handled correctly
-for relationship name inflection.
+CamelCase column names in case-preserving mode will also be handled correctly
+for relationship name inflection. See L</preserve_case>.
 
-Currently, only Sybase ASE, MSSQL with CS/BIN collation and Firebird without
-the L<unquoted_ddl|DBIx::Class::Schema::Loader::DBI::InterBase/unquoted_ddl>
-option are in case-sensitive mode.
+In this mode, CamelCase L</column_accessors> are normalized based on case
+transition instead of just being lowercased, so C<FooId> becomes C<foo_id>.
 
 If you don't have any CamelCase table or column names, you can upgrade without
 breaking any of your code.
@@ -195,10 +201,10 @@ and singularization put this in your C<Schema.pm> file:
 
     __PACKAGE__->naming('current');
 
-Or if you prefer to use 0.05XXX features but insure that nothing breaks in the
+Or if you prefer to use 0.07XXX features but insure that nothing breaks in the
 next major version upgrade:
 
-    __PACKAGE__->naming('v5');
+    __PACKAGE__->naming('v7');
 
 =head2 generate_pod
 
@@ -252,12 +258,10 @@ relationship types override those set in 'all'.
 For example:
 
   relationship_attrs => {
-    all      => { cascade_delete => 0 },
-    has_many => { cascade_delete => 1 },
+    belongs_to => { is_deferrable => 1 },
   },
 
-will set the C<cascade_delete> option to 0 for all generated relationships,
-except for C<has_many>, which will have cascade_delete as 1.
+use this to make your foreign key constraints DEFERRABLE.
 
 =head2 debug
 
@@ -336,7 +340,8 @@ List of additional classes which all of your table classes will use.
 =head2 components
 
 List of additional components to be loaded into all of your table
-classes.  A good example would be C<ResultSetManager>.
+classes.  A good example would be
+L<InflateColumn::DateTime|DBIx::Class::InflateColumn::DateTime>
 
 =head2 resultset_components
 
@@ -446,12 +451,12 @@ columns with the DATE/DATETIME/TIMESTAMP data_types.
 Sets the locale attribute for L<DBIx::Class::InflateColumn::DateTime> for all
 columns with the DATE/DATETIME/TIMESTAMP data_types.
 
-=head1 config_file
+=head2 config_file
 
 File in Perl format, which should return a HASH reference, from which to read
 loader options.
 
-=head1 preserve_case
+=head2 preserve_case
 
 Usually column names are lowercased, to make them easier to work with in
 L<DBIx::Class>. This option lets you turn this behavior off, if the driver
@@ -463,6 +468,19 @@ case-sensitive collation will turn this option on unconditionally.
 Currently the drivers for SQLite, mysql, MSSQL and Firebird/InterBase support
 setting this option.
 
+=head2 qualify_objects
+
+Set to true to prepend the L</db_schema> to table names for C<<
+__PACKAGE__->table >> calls, and to some other things like Oracle sequences.
+
+=head2 use_moose
+
+Creates Schema and Result classes that use L<Moose>, L<MooseX::NonMoose> and
+L<namespace::autoclean>. The default content after the md5 sum also makes the
+classes immutable.
+
+It is safe to upgrade your existing Schema to this option.
+
 =head1 METHODS
 
 None of these methods are intended for direct invocation by regular
@@ -525,6 +543,19 @@ sub new {
 
     $self->_validate_class_args;
 
+    if ($self->use_moose) {
+        eval <<'EOF';
+package __DBICSL__DUMMY;
+use Moose;
+use MooseX::NonMoose;
+use namespace::autoclean;
+EOF
+        if ($@) {
+            die sprintf "You must install the following CPAN modules to enable the use_moose option: %s.\n",
+                "Moose, MooseX::NonMoose and namespace::autoclean";
+        }
+    }
+
     push(@{$self->{components}}, 'ResultSetManager')
         if @{$self->{resultset_components}};
 
@@ -555,6 +586,7 @@ sub new {
         $self->{naming} = {
             relationships => $naming_ver,
             monikers => $naming_ver,
+            column_accessors => $naming_ver,
         };
     }
 
@@ -695,8 +727,9 @@ EOF
                 last;
             }
 
-            $self->naming->{relationships} ||= $v;
-            $self->naming->{monikers}      ||= $v;
+            $self->naming->{relationships}    ||= $v;
+            $self->naming->{monikers}         ||= $v;
+            $self->naming->{column_accessors} ||= $v;
 
             $self->schema_version_to_dump($real_ver);
 
@@ -847,8 +880,8 @@ sub _load_external {
     }
 
     if ($old_real_inc_path) {
-        open(my $fh, '<', $old_real_inc_path)
-            or croak "Failed to open '$old_real_inc_path' for reading: $!";
+        my $code = slurp $old_real_inc_path;
+
         $self->_ext_stmt($class, <<"EOF");
 
 # These lines were loaded from '$old_real_inc_path',
@@ -857,7 +890,6 @@ sub _load_external {
 # upgrade. See skip_load_external to disable this feature.
 EOF
 
-        my $code = slurp $old_real_inc_path;
         $code = $self->_rewrite_old_classnames($code);
 
         if ($self->dynamic) {
@@ -905,14 +937,11 @@ sub load {
 
 Arguments: schema
 
-Rescan the database for newly added tables.  Does
-not process drops or changes.  Returns a list of
-the newly added table monikers.
+Rescan the database for changes. Returns a list of the newly added table
+monikers.
 
-The schema argument should be the schema class
-or object to be affected.  It should probably
-be derived from the original schema_class used
-during L</load>.
+The schema argument should be the schema class or object to be affected.  It
+should probably be derived from the original schema_class used during L</load>.
 
 =cut
 
@@ -924,15 +953,27 @@ sub rescan {
 
     my @created;
     my @current = $self->_tables_list({ constraint => $self->constraint, exclude => $self->exclude });
+
     foreach my $table (@current) {
         if(!exists $self->{_tables}->{$table}) {
             push(@created, $table);
         }
     }
 
-    my $loaded = $self->_load_tables(@created);
+    my %current;
+    @current{@current} = ();
+    foreach my $table (keys %{ $self->{_tables} }) {
+        if (not exists $current{$table}) {
+            $self->_unregister_source_for_table($table);
+        }
+    }
+
+    delete $self->{_dump_storage};
+    delete $self->{_relations_started};
 
-    return map { $self->monikers->{$_} } @$loaded;
+    my $loaded = $self->_load_tables(@current);
+
+    return map { $self->monikers->{$_} } @created;
 }
 
 sub _relbuilder {
@@ -1067,6 +1108,9 @@ sub _reload_classes {
             local *Class::C3::reinitialize = sub {};
             use warnings;
 
+            if ($class->can('meta')) {
+                $class->meta->make_mutable;
+            }
             Class::Unload->unload($class) if $unload;
             my ($source, $resultset_class);
             if (
@@ -1075,6 +1119,9 @@ sub _reload_classes {
                 && ($resultset_class ne 'DBIx::Class::ResultSet')
             ) {
                 my $has_file = Class::Inspector->loaded_filename($resultset_class);
+                if ($resultset_class->can('meta')) {
+                    $resultset_class->meta->make_mutable;
+                }
                 Class::Unload->unload($resultset_class) if $unload;
                 $self->_reload_class($resultset_class) if $has_file;
             }
@@ -1104,6 +1151,7 @@ sub _reload_class {
             unless $_[0] =~ /^Subroutine \S+ redefined/;
     };
     eval "require $class;";
+    die "Failed to reload class $class: $@" if $@;
 }
 
 sub _get_dump_filename {
@@ -1144,8 +1192,13 @@ sub _dump_to_dir {
           qq|package $schema_class;\n\n|
         . qq|# Created by DBIx::Class::Schema::Loader\n|
         . qq|# DO NOT MODIFY THE FIRST PART OF THIS FILE\n\n|
-        . qq|use strict;\nuse warnings;\n\n|
-        . qq|use base '$schema_base_class';\n\n|;
+        . qq|use strict;\nuse warnings;\n\n|;
+    if ($self->use_moose) {
+        $schema_text.= qq|use Moose;\nuse MooseX::NonMoose;\nuse namespace::autoclean;\nextends '$schema_base_class';\n\n|;
+    }
+    else {
+        $schema_text .= qq|use base '$schema_base_class';\n\n|;
+    }
 
     if ($self->use_namespaces) {
         $schema_text .= qq|__PACKAGE__->load_namespaces|;
@@ -1179,9 +1232,13 @@ sub _dump_to_dir {
               qq|package $src_class;\n\n|
             . qq|# Created by DBIx::Class::Schema::Loader\n|
             . qq|# DO NOT MODIFY THE FIRST PART OF THIS FILE\n\n|
-            . qq|use strict;\nuse warnings;\n\n|
-            . qq|use base '$result_base_class';\n\n|;
-
+            . qq|use strict;\nuse warnings;\n\n|;
+        if ($self->use_moose) {
+            $src_text.= qq|use Moose;\nuse MooseX::NonMoose;\nuse namespace::autoclean;\nextends '$result_base_class';\n\n|;
+        }
+        else {
+             $src_text .= qq|use base '$result_base_class';\n\n|;
+        }
         $self->_write_classfile($src_class, $src_text);
     }
 
@@ -1228,6 +1285,25 @@ sub _write_classfile {
 
     my ($custom_content, $old_md5, $old_ver, $old_ts) = $self->_get_custom_content($class, $filename);
 
+    # If upgrading to use_moose=1 replace default custom content with default Moose custom content.
+    # If there is already custom content, which does not have the Moose content, add it.
+    if ($self->use_moose) {
+        local $self->{use_moose} = 0;
+
+        if ($custom_content eq $self->_default_custom_content) {
+            local $self->{use_moose} = 1;
+
+            $custom_content = $self->_default_custom_content;
+        }
+        else {
+            local $self->{use_moose} = 1;
+
+            if ($custom_content !~ /\Q@{[$self->_default_moose_custom_content]}\E/) {
+                $custom_content .= $self->_default_custom_content;
+            }
+        }
+    }
+
     if (my $old_class = $self->_upgrading_classes->{$class}) {
         my $old_filename = $self->_get_dump_filename($old_class);
 
@@ -1284,10 +1360,19 @@ sub _write_classfile {
         or croak "Error closing '$filename': $!";
 }
 
+sub _default_moose_custom_content {
+    return qq|\n__PACKAGE__->meta->make_immutable;|;
+}
+
 sub _default_custom_content {
-    return qq|\n\n# You can replace this text with custom|
-         . qq| content, and it will be preserved on regeneration|
-         . qq|\n1;\n|;
+    my $self = shift;
+    my $default = qq|\n\n# You can replace this text with custom|
+         . qq| content, and it will be preserved on regeneration|;
+    if ($self->use_moose) {
+        $default .= $self->_default_moose_custom_content;
+    }
+    $default .= qq|\n1;\n|;
+    return $default;
 }
 
 sub _get_custom_content {
@@ -1466,6 +1551,12 @@ sub _resolve_col_accessor_collisions {
     }
 }
 
+sub _make_column_accessor_name {
+    my ($self, $column_name) = @_;
+
+    return join '_', map lc, split_name $column_name;
+}
+
 # Set up metadata (cols, pks, etc)
 sub _setup_src_meta {
     my ($self, $table) = @_;
@@ -1483,14 +1574,32 @@ sub _setup_src_meta {
         $table_name = \ $self->_quote_table_name($table_name);
     }
 
-    $self->_dbic_stmt($table_class,'table',$table_name);
+    my $full_table_name = ($self->qualify_objects ? ($self->db_schema . '.') : '') . (ref $table_name ? $$table_name : $table_name);
+
+    # be careful to not create refs Data::Dump can "optimize"
+    $full_table_name    = \do {"".$full_table_name} if ref $table_name;
+
+    $self->_dbic_stmt($table_class, 'table', $full_table_name);
 
     my $cols = $self->_table_columns($table);
     my $col_info = $self->__columns_info_for($table);
+
+    while (my ($col, $info) = each %$col_info) {
+        if ($col =~ /\W/) {
+            ($info->{accessor} = $col) =~ s/\W+/_/g;
+        }
+    }
+
     if ($self->preserve_case) {
-        for my $col (keys %$col_info) {
-            $col_info->{$col}{accessor} = lc $col
-                if $col ne lc($col);
+        while (my ($col, $info) = each %$col_info) {
+            if ($col ne lc($col)) {
+                if ((not exists $self->naming->{column_accessors}) || (($self->naming->{column_accessors} =~ /(\d+)/)[0] >= 7)) {
+                    $info->{accessor} = $self->_make_column_accessor_name($info->{accessor} || $col);
+                }
+                else {
+                    $info->{accessor} = lc($info->{accessor} || $col);
+                }
+            }
         }
     }
     else {
@@ -1502,11 +1611,18 @@ sub _setup_src_meta {
 
     my $fks = $self->_table_fk_info($table);
 
-    for my $fkdef (@$fks) {
+    foreach my $fkdef (@$fks) {
         for my $col (@{ $fkdef->{local_columns} }) {
             $col_info->{$col}{is_foreign_key} = 1;
         }
     }
+
+    my $pks = $self->_table_pk_info($table) || [];
+
+    foreach my $pkcol (@$pks) {
+        $col_info->{$pkcol}{is_nullable} = 0;
+    }
+
     $self->_dbic_stmt(
         $table_class,
         'add_columns',
@@ -1515,7 +1631,6 @@ sub _setup_src_meta {
 
     my %uniq_tag; # used to eliminate duplicate uniqs
 
-    my $pks = $self->_table_pk_info($table) || [];
     @$pks ? $self->_dbic_stmt($table_class,'set_primary_key',@$pks)
           : carp("$table has no primary key");
     $uniq_tag{ join("\0", @$pks) }++ if @$pks; # pk is a uniq
@@ -1576,7 +1691,7 @@ sub _default_table2moniker {
         return join '', map ucfirst, split /\W+/, $inflected;
     }
 
-    my @words = map lc, split /(?<=[[:lower:]])[\W_]*(?=[[:upper:]])|[\W_]+/, $table;
+    my @words = map lc, split_name $table;
     my $as_phrase = join ' ', @words;
 
     my $inflected = Lingua::EN::Inflect::Phrase::to_S($as_phrase);
@@ -1801,6 +1916,22 @@ sub _uc {
     return $self->preserve_case ? $name : uc($name);
 }
 
+sub _unregister_source_for_table {
+    my ($self, $table) = @_;
+
+    eval {
+        local $@;
+        my $schema = $self->schema;
+        # in older DBIC it's a private method
+        my $unregister = $schema->can('unregister_source') || $schema->can('_unregister_source');
+        $schema->$unregister($self->_table2moniker($table));
+        delete $self->monikers->{$table};
+        delete $self->classes->{$table};
+        delete $self->_upgrading_classes->{$table};
+        delete $self->{_tables}{$table};
+    };
+}
+
 # remove the dump dir from @INC on destruction
 sub DESTROY {
     my $self = shift;