adds the ability to filter generated code

[dbsrgits/DBIx-Class-Schema-Loader.git] / lib / DBIx / Class / Schema / Loader / Base.pm

diff --git a/lib/DBIx/Class/Schema/Loader/Base.pm b/lib/DBIx/Class/Schema/Loader/Base.pm
index 5634bc6..2a67684 100644 (file)
--- a/lib/DBIx/Class/Schema/Loader/Base.pm
+++ b/lib/DBIx/Class/Schema/Loader/Base.pm
@@ -72,9 +72,13 @@ __PACKAGE__->mk_group_ro_accessors('simple', qw/
                                 loader_class
                                 qualify_objects
                                 tables
+                                table_comments_table
+                                column_comments_table
                                 class_to_table
                                 uniq_to_primary
                                 quiet
+
+                                filter_generated_text
 /);
 
 
@@ -262,8 +266,24 @@ L</really_erase_my_files>.)
 By default POD will be generated for columns and relationships, using database
 metadata for the text if available and supported.
 
-Reading database metadata (e.g. C<COMMENT ON TABLE some_table ...>) is only
-supported for Postgres right now.
+Comment metadata can be stored in two ways.
+
+The first is that you can create two tables named C<table_comments> and
+C<column_comments> respectively.  They both need to have columns named
+C<table_name> and C<comment_text>.  The second one needs to have a column
+named C<column_name>.  Then data stored in these tables will be used as a
+source of metadata about tables and comments.
+
+(If you wish you can change the name of these tables with the parameters
+L</table_comments_table> and L</column_comments_table>.)
+
+As a fallback you can use built-in commenting mechanisms.  Currently this is
+only supported for PostgreSQL, Oracle and MySQL.  To create comments in
+PostgreSQL you add statements of the form C<COMMENT ON TABLE some_table IS
+'...'>, the same syntax is used in Oracle. To create comments in MySQL you add
+C<COMMENT '...'> to the end of the column or table definition.  Note that MySQL
+restricts the length of comments, and also does not handle complex Unicode
+characters properly.
 
 Set this to C<0> to turn off all POD generation.
 
@@ -299,6 +319,16 @@ which it will be forced into a separate description section.
 
 The default is C<60>
 
+=head2 table_comments_table
+
+The table to look for comments about tables in.  By default C<table_comments>.
+See L</generate_pod> for details.
+
+=head2 column_comments_table
+
+The table to look for comments about columns in.  By default C<column_comments>.
+See L</generate_pod> for details.
+
 =head2 relationship_attrs
 
 Hashref of attributes to pass to each generated relationship, listed
@@ -654,6 +684,21 @@ Automatically promotes the largest unique constraints with non-nullable columns
 on tables to primary keys, assuming there is only one largest unique
 constraint.
 
+=head2 filter_generated_text
+
+An optional hook that lets you filter the generated text for various classes through
+a function that change it in any way that you want.  The function will receive the class
+and text, and returns the new text to use instead.  For instance you could add
+custom comment, run C<perltidy>, or do anything else that you want.
+
+If this exists but fails to return text matching C</package/>, no file will be generated.
+
+    filter_generated_base => sub {
+        my ($class, $text) = @_;
+       ...
+       return $new_text;
+    }
+
 =head1 METHODS
 
 None of these methods are intended for direct invocation by regular
@@ -783,6 +828,8 @@ sub new {
 
     $self->{schema_class} ||= ( ref $self->{schema} || $self->{schema} );
     $self->{schema} ||= $self->{schema_class};
+    $self->{table_comments_table} ||= 'table_comments';
+    $self->{column_comments_table} ||= 'column_comments';
 
     croak "dump_overwrite is deprecated.  Please read the"
         . " DBIx::Class::Schema::Loader::Base documentation"
@@ -1625,7 +1672,15 @@ sub _write_classfile {
     $text .= qq|$_\n|
         for @{$self->{_dump_storage}->{$class} || []};
 
-    # Check and see if the dump is infact differnt
+    if ($self->{filter_generated_text}) {
+        $text = $self->{filter_generated_text}->($class, $text);
+       if (not $text or not $text =~ /package/) {
+           warn("$class skipped due to filter") if $self->debug;
+           return;
+       }
+    }
+
+    # Check and see if the dump is in fact different
 
     my $compare_to;
     if ($old_md5) {