lib/SQL/Translator/Parser.pm

   1 package SQL::Translator::Parser;
   2
   3 # ----------------------------------------------------------------------
   4 # $Id: Parser.pm,v 1.1.1.1.2.2 2002-03-21 15:47:08 dlc Exp $
   5 # ----------------------------------------------------------------------
   6 # Copyright (C) 2002 Ken Y. Clark <kycl4rk@users.sourceforge.net>,
   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.1.1.1.2.2 $ =~ /(\d+)\.(\d+)/;
  27
  28 sub parse { "" }
  29
  30 1;
  31
  32 #-----------------------------------------------------
  33 # Enough! or Too much.
  34 # William Blake
  35 #-----------------------------------------------------
  36 __END__
  37
  38 =head1 NAME
  39
  40 SQL::Translator::Parser - base object for parsers
  41
  42 =head1 DESCRIPTION
  43
  44 Parser modules that get invoked by SQL::Translator need to implement a
  45 single function: B<parse>.  This function will be called by the
  46 SQL::Translator instance as $class::parse($tr, $data_as_string), where
  47 $tr is a SQL::Translator instance.  Other than that, the classes are
  48 free to define any helper functions, or use any design pattern
  49 internally that make the most sense.
  50
  51 =head1 FORMAT OF THE DATA STRUCTURE
  52
  53 The data structure returned from the B<parse> function has a very
  54 particular format.
  55
  56 =over 4
  57
  58 =item o
  59
  60 The data structure should be a reference to a hash, the keys of which
  61 are table names.
  62
  63 =item o
  64
  65 The values associated with each table should also be a reference to a
  66 hash.  This hash should have several keys, enumerated below.
  67
  68 =back
  69
  70 =over 15
  71
  72 =item B<type>
  73
  74 This is the type of the table, if applicable, as a string, or undef if not (for
  75 example, if the database does not have multiple options).  For MySQL,
  76 this value might include MyISAM, HEAP, or similar.
  77
  78 =item B<indeces>
  79
  80 The indeces keys is a reference to an array of hashrefs.  Each hashref
  81 defines one index, and has the keys 'name' (if defined, it will be a
  82 string), 'type' (a string), and 'fields' (a reference to another
  83 array).  For example, a table in a MySQL database with two indexes,
  84 created as:
  85
  86   PRIMARY KEY (id),
  87   KEY foo_idx (foo),
  88   KEY foo_bar_idx (foo, bar),
  89
  90 would be described in the indeces element as:
  91
  92   [
  93     {
  94       'type' => 'primary_key',
  95       'fields' => [
  96                     'id'
  97                   ],
  98       'name' => undef,
  99     },
 100     {
 101       'type' => 'normal',
 102       'fields' => [
 103                     'foo'
 104                   ],
 105       'name' => 'foo_idx',
 106     },
 107     {
 108       'type' => 'normal',
 109       'fields' => [
 110                     'foo',
 111                     'bar',
 112                   ],
 113       'name' => 'foo_bar_idx',
 114     },
 115   ]
 116
 117 =item B<fields>
 118
 119 The fields element is a refernce to a hash; the keys of this hash are
 120 the row names from the table, and each value fills in this template:
 121
 122   {
 123     type           => 'field',
 124     name           => '',     # same as the key
 125     data_type      => '',     # in the db's jargon,
 126                               # i.e., MySQL => int, Oracale => INTEGER
 127     size           => '',     # int
 128     null           => 1 | 0,  # boolean
 129     default        => '',
 130     is_auto_inc    => 1 1 0,  # boolean
 131     is_primary_key => 1 | 0,  # boolean
 132   }
 133
 134 So a row defined as:
 135
 136   username CHAR(8) NOT NULL DEFAULT 'nobody',
 137   KEY username_idx (username)
 138
 139 would be represented as:
 140
 141   'fields => {
 142     'username' => {
 143       type           => 'field',
 144       name           => 'username',
 145       data_type      => 'char',
 146       size           => '8',
 147       null           => undef,
 148       default        => 'nobody',
 149       is_auto_inc    => undef,
 150       is_primary_key => undef,
 151     },
 152   },
 153   'indeces' => [
 154     {
 155       'name' => 'username_idx',
 156       'fields' => [
 157                     'username'
 158                   ],
 159       'type' => 'normal',
 160     },
 161   ],
 162
 163 =back
 164
 165
 166 =head1 AUTHORS
 167
 168 Ken Y. Clark, E<lt>kclark@logsoft.comE<gt>, darren chamberlain E<lt>darren@cpan.orgE<gt>
 169
 170 =head1 SEE ALSO
 171
 172 perl(1).
 173
 174 =cut