lib/SQL/Translator/Producer/POD.pm

   1 package SQL::Translator::Producer::POD;
   2
   3 # -------------------------------------------------------------------
   4 # Copyright (C) 2002-2009 SQLFairy Authors
   5 #
   6 # This program is free software; you can redistribute it and/or
   7 # modify it under the terms of the GNU General Public License as
   8 # published by the Free Software Foundation; version 2.
   9 #
  10 # This program is distributed in the hope that it will be useful, but
  11 # WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 # General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program; if not, write to the Free Software
  17 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  18 # 02111-1307  USA
  19 # -------------------------------------------------------------------
  20
  21 =head1 NAME
  22
  23 SQL::Translator::Producer::POD - POD producer for SQL::Translator
  24
  25 =head1 SYNOPSIS
  26
  27   use SQL::Translator;
  28
  29   my $t = SQL::Translator->new( parser => '...', producer => 'POD', '...' );
  30   print $t->translate;
  31
  32 =head1 DESCRIPTION
  33
  34 Creates a POD description of each table, field, index, and constraint.
  35 A good starting point for text documentation of a schema.  You can
  36 easily convert the output to HTML or text using "perldoc" or other
  37 interesting formats using Pod::POM or Template::Toolkit's POD plugin.
  38
  39 =cut
  40
  41 use strict;
  42 use vars qw[ $VERSION ];
  43 $VERSION = '1.99';
  44
  45 use SQL::Translator::Schema::Constants;
  46 use SQL::Translator::Utils qw(header_comment);
  47
  48 # -------------------------------------------------------------------
  49 sub produce {
  50     my $t           = shift;
  51     my $schema      = $t->schema;
  52     my $schema_name = $schema->name || 'Schema';
  53     my $args        = $t->producer_args;
  54     my $title       = $args->{'title'} || $schema_name;
  55
  56     my $pod = "=pod\n\n=head1 DESCRIPTION\n\n$title\n\n=head1 TABLES\n\n";
  57
  58     for my $table ( $schema->get_tables ) {
  59         my $table_name = $table->name or next;
  60         my @fields     = $table->get_fields or next;
  61         $pod .= "=head2 $table_name\n\n=head3 FIELDS\n\n";
  62
  63         #
  64         # Fields
  65         #
  66         for my $field ( @fields ) {
  67             $pod .= "=head4 " . $field->name . "\n\n=over 4\n\n";
  68
  69             my $data_type = $field->data_type;
  70             my $size      = $field->size;
  71             $data_type   .= "($size)" if $size;
  72
  73             $pod .= "=item * $data_type\n\n";
  74             $pod .= "=item * PRIMARY KEY\n\n" if $field->is_primary_key;
  75
  76             my $default = $field->default_value;
  77             $pod .= "=item * Default '$default' \n\n" if defined $default;
  78
  79             $pod .= sprintf( "=item * Nullable '%s' \n\n",
  80                 $field->is_nullable ? 'Yes' : 'No' );
  81
  82             $pod .= "=back\n\n";
  83         }
  84
  85         #
  86         # Indices
  87         #
  88         if ( my @indices = $table->get_indices ) {
  89             $pod .= "=head3 INDICES\n\n";
  90             for my $index ( @indices ) {
  91                 $pod .= "=head4 " . $index->type . "\n\n=over 4\n\n";
  92                 $pod .= "=item * Fields = " .
  93                     join(', ', $index->fields ) . "\n\n";
  94                 $pod .= "=back\n\n";
  95             }
  96         }
  97
  98         #
  99         # Constraints
 100         #
 101         if ( my @constraints = $table->get_constraints ) {
 102             $pod .= "=head3 CONSTRAINTS\n\n";
 103             for my $c ( @constraints ) {
 104                 $pod .= "=head4 " . $c->type . "\n\n=over 4\n\n";
 105                 $pod .= "=item * Fields = " .
 106                     join(', ', $c->fields ) . "\n\n";
 107
 108                 if ( $c->type eq FOREIGN_KEY ) {
 109                     $pod .= "=item * Reference Table = L</" .
 110                         $c->reference_table . ">\n\n";
 111                     $pod .= "=item * Reference Fields = " .
 112                         join(', ', map {"L</$_>"} $c->reference_fields ) .
 113                         "\n\n";
 114                 }
 115
 116                 if ( my $update = $c->on_update ) {
 117                     $pod .= "=item * On update = $update\n\n";
 118                 }
 119
 120                 if ( my $delete = $c->on_delete ) {
 121                     $pod .= "=item * On delete = $delete\n\n";
 122                 }
 123
 124                 $pod .= "=back\n\n";
 125             }
 126         }
 127     }
 128
 129     my $header = ( map { $_ || () } split( /\n/, header_comment('', '') ) )[0];
 130        $header =~ s/^Created by //;
 131     $pod .= "=head1 PRODUCED BY\n\n$header\n\n=cut";
 132
 133     return $pod;
 134 }
 135
 136 1;
 137
 138 # -------------------------------------------------------------------
 139 # Expect poison from the standing water.
 140 # William Blake
 141 # -------------------------------------------------------------------
 142
 143 =pod
 144
 145 =head1 AUTHOR
 146
 147 Ken Y. Clark E<lt>kclark@cpan.orgE<gt>.
 148
 149 =head2 CONTRIBUTORS
 150
 151 Jonathan Yu E<lt>frequency@cpan.orgE<gt>
 152
 153 =head1 SEE ALSO
 154
 155 perldoc, perlpod, Pod::POM, Template::Manual::Plugins.
 156
 157 =cut