lib/SQL/Translator/Producer/POD.pm

   1 package SQL::Translator::Producer::POD;
   2
   3 =head1 NAME
   4
   5 SQL::Translator::Producer::POD - POD producer for SQL::Translator
   6
   7 =head1 SYNOPSIS
   8
   9   use SQL::Translator;
  10
  11   my $t = SQL::Translator->new( parser => '...', producer => 'POD', '...' );
  12   print $t->translate;
  13
  14 =head1 DESCRIPTION
  15
  16 Creates a POD description of each table, field, index, and constraint.
  17 A good starting point for text documentation of a schema.  You can
  18 easily convert the output to HTML or text using "perldoc" or other
  19 interesting formats using Pod::POM or Template::Toolkit's POD plugin.
  20
  21 =cut
  22
  23 use strict;
  24 use warnings;
  25 use vars qw[ $VERSION ];
  26 $VERSION = '1.59';
  27
  28 use SQL::Translator::Schema::Constants;
  29 use SQL::Translator::Utils qw(header_comment);
  30
  31 sub produce {
  32     my $t           = shift;
  33     my $schema      = $t->schema;
  34     my $schema_name = $schema->name || 'Schema';
  35     my $args        = $t->producer_args;
  36     my $title       = $args->{'title'} || $schema_name;
  37
  38     my $pod = "=pod\n\n=head1 DESCRIPTION\n\n$title\n\n=head1 TABLES\n\n";
  39
  40     for my $table ( $schema->get_tables ) {
  41         my $table_name = $table->name or next;
  42         my @fields     = $table->get_fields or next;
  43         $pod .= "=head2 $table_name\n\n=head3 FIELDS\n\n";
  44
  45         #
  46         # Fields
  47         #
  48         for my $field ( @fields ) {
  49             $pod .= "=head4 " . $field->name . "\n\n=over 4\n\n";
  50
  51             my $data_type = $field->data_type;
  52             my $size      = $field->size;
  53             $data_type   .= "($size)" if $size;
  54
  55             $pod .= "=item * $data_type\n\n";
  56             $pod .= "=item * PRIMARY KEY\n\n" if $field->is_primary_key;
  57
  58             my $default = $field->default_value;
  59             $pod .= "=item * Default '$default' \n\n" if defined $default;
  60
  61             $pod .= sprintf( "=item * Nullable '%s' \n\n",
  62                 $field->is_nullable ? 'Yes' : 'No' );
  63
  64             $pod .= "=back\n\n";
  65         }
  66
  67         #
  68         # Indices
  69         #
  70         if ( my @indices = $table->get_indices ) {
  71             $pod .= "=head3 INDICES\n\n";
  72             for my $index ( @indices ) {
  73                 $pod .= "=head4 " . $index->type . "\n\n=over 4\n\n";
  74                 $pod .= "=item * Fields = " .
  75                     join(', ', $index->fields ) . "\n\n";
  76                 $pod .= "=back\n\n";
  77             }
  78         }
  79
  80         #
  81         # Constraints
  82         #
  83         if ( my @constraints = $table->get_constraints ) {
  84             $pod .= "=head3 CONSTRAINTS\n\n";
  85             for my $c ( @constraints ) {
  86                 $pod .= "=head4 " . $c->type . "\n\n=over 4\n\n";
  87                 $pod .= "=item * Fields = " .
  88                     join(', ', $c->fields ) . "\n\n";
  89
  90                 if ( $c->type eq FOREIGN_KEY ) {
  91                     $pod .= "=item * Reference Table = L</" .
  92                         $c->reference_table . ">\n\n";
  93                     $pod .= "=item * Reference Fields = " .
  94                         join(', ', map {"L</$_>"} $c->reference_fields ) .
  95                         "\n\n";
  96                 }
  97
  98                 if ( my $update = $c->on_update ) {
  99                     $pod .= "=item * On update = $update\n\n";
 100                 }
 101
 102                 if ( my $delete = $c->on_delete ) {
 103                     $pod .= "=item * On delete = $delete\n\n";
 104                 }
 105
 106                 $pod .= "=back\n\n";
 107             }
 108         }
 109     }
 110
 111     my $header = ( map { $_ || () } split( /\n/, header_comment('', '') ) )[0];
 112        $header =~ s/^Created by //;
 113     $pod .= "=head1 PRODUCED BY\n\n$header\n\n=cut";
 114
 115     return $pod;
 116 }
 117
 118 1;
 119
 120 # -------------------------------------------------------------------
 121 # Expect poison from the standing water.
 122 # William Blake
 123 # -------------------------------------------------------------------
 124
 125 =pod
 126
 127 =head1 AUTHOR
 128
 129 Ken Youens-Clark E<lt>kclark@cpan.orgE<gt>.
 130
 131 =head2 CONTRIBUTORS
 132
 133 Jonathan Yu E<lt>frequency@cpan.orgE<gt>
 134
 135 =head1 SEE ALSO
 136
 137 perldoc, perlpod, Pod::POM, Template::Manual::Plugins.
 138
 139 =cut