lib/SQL/Translator/Parser.pm

   1 package SQL::Translator::Parser;
   2
   3 # ----------------------------------------------------------------------
   4 # $Id: Parser.pm,v 1.6 2003-01-27 17:04:44 dlc Exp $
   5 # ----------------------------------------------------------------------
   6 # Copyright (C) 2003 Ken Y. Clark <kclark@cpan.org>,
   7 #                    darren chamberlain <darren@cpan.org>,
   8 #                    Chris Mungall <cjm@fruitfly.org>
   9 #
  10 # This program is free software; you can redistribute it and/or
  11 # modify it under the terms of the GNU General Public License as
  12 # published by the Free Software Foundation; version 2.
  13 #
  14 # This program is distributed in the hope that it will be useful, but
  15 # WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 # General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU General Public License
  20 # along with this program; if not, write to the Free Software
  21 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  22 # 02111-1307  USA
  23 # ----------------------------------------------------------------------
  24
  25 use strict;
  26 use vars qw( $VERSION );
  27 $VERSION = sprintf "%d.%02d", q$Revision: 1.6 $ =~ /(\d+)\.(\d+)/;
  28
  29 sub parse { "" }
  30
  31 1;
  32
  33 # ----------------------------------------------------------------------
  34 # Enough! or Too much.
  35 # William Blake
  36 # ----------------------------------------------------------------------
  37
  38 =pod
  39
  40 =head1 NAME
  41
  42 SQL::Translator::Parser - base object for parsers
  43
  44 =head1 DESCRIPTION
  45
  46 Parser modules that get invoked by SQL::Translator need to implement a
  47 single function: B<parse>.  This function will be called by the
  48 SQL::Translator instance as $class::parse($tr, $data_as_string), where
  49 $tr is a SQL::Translator instance.  Other than that, the classes are
  50 free to define any helper functions, or use any design pattern
  51 internally that make the most sense.
  52
  53 =head1 FORMAT OF THE DATA STRUCTURE
  54
  55 The data structure returned from the B<parse> function has a very
  56 particular format.
  57
  58 =over 4
  59
  60 =item o
  61
  62 The data structure should be a reference to a hash, the keys of which
  63 are table names.
  64
  65 =item o
  66
  67 The values associated with each table should also be a reference to a
  68 hash.  This hash should have several keys, enumerated below.
  69
  70 =back
  71
  72 =over 15
  73
  74 =item B<type>
  75
  76 This is the type of the table, if applicable, as a string, or undef if not (for
  77 example, if the database does not have multiple options).  For MySQL,
  78 this value might include MyISAM, HEAP, or similar.
  79
  80 =item B<indices>
  81
  82 The indices keys is a reference to an array of hashrefs.  Each hashref
  83 defines one index, and has the keys 'name' (if defined, it will be a
  84 string), 'type' (a string), and 'fields' (a reference to another
  85 array).  For example, a table in a MySQL database with two indexes,
  86 created as:
  87
  88   PRIMARY KEY (id),
  89   KEY foo_idx (foo),
  90   KEY foo_bar_idx (foo, bar),
  91
  92 would be described in the indices element as:
  93
  94   [
  95     {
  96       'type' => 'primary_key',
  97       'fields' => [
  98                     'id'
  99                   ],
 100       'name' => undef,
 101     },
 102     {
 103       'type' => 'normal',
 104       'fields' => [
 105                     'foo'
 106                   ],
 107       'name' => 'foo_idx',
 108     },
 109     {
 110       'type' => 'normal',
 111       'fields' => [
 112                     'foo',
 113                     'bar',
 114                   ],
 115       'name' => 'foo_bar_idx',
 116     },
 117   ]
 118
 119 =item B<fields>
 120
 121 The fields element is a refernce to a hash; the keys of this hash are
 122 the row names from the table, and each value fills in this template:
 123
 124   {
 125     type           => 'field',
 126     order          => 1,      # the order in the original table
 127     name           => '',     # same as the key
 128     data_type      => '',     # in the db's jargon,
 129                               # i.e., MySQL => int, Oracale => INTEGER
 130     size           => '',     # int
 131     null           => 1 | 0,  # boolean
 132     default        => '',
 133     is_auto_inc    => 1 1 0,  # boolean
 134     is_primary_key => 1 | 0,  # boolean
 135   }
 136
 137 So a row defined as:
 138
 139   username CHAR(8) NOT NULL DEFAULT 'nobody',
 140   KEY username_idx (username)
 141
 142 would be represented as:
 143
 144   'fields => {
 145     'username' => {
 146       type           => 'field',
 147       order          => 1,
 148       name           => 'username',
 149       data_type      => 'char',
 150       size           => '8',
 151       null           => undef,
 152       default        => 'nobody',
 153       is_auto_inc    => undef,
 154       is_primary_key => undef,
 155     },
 156   },
 157   'indices' => [
 158     {
 159       'name' => 'username_idx',
 160       'fields' => [
 161                     'username'
 162                   ],
 163       'type' => 'normal',
 164     },
 165   ],
 166
 167 =back
 168
 169
 170 =head1 AUTHORS
 171
 172 Ken Y. Clark, E<lt>kclark@cpan.org<gt>,
 173 darren chamberlain E<lt>darren@cpan.orgE<gt>.
 174
 175 =head1 SEE ALSO
 176
 177 perl(1).
 178
 179 =cut