lib/SQL/Translator/Parser.pm

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