Commit | Line | Data |
16dc9970 |
1 | package SQL::Translator::Parser; |
2 | |
077ebf34 |
3 | # ---------------------------------------------------------------------- |
d529894e |
4 | # $Id: Parser.pm,v 1.5 2002-11-22 03:03:40 kycl4rk Exp $ |
077ebf34 |
5 | # ---------------------------------------------------------------------- |
d529894e |
6 | # Copyright (C) 2002 Ken Y. Clark <kclark@cpan.org>, |
077ebf34 |
7 | # darren chamberlain <darren@cpan.org> |
16dc9970 |
8 | # |
077ebf34 |
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 | # ---------------------------------------------------------------------- |
16dc9970 |
23 | |
24 | use strict; |
25 | use vars qw( $VERSION ); |
d529894e |
26 | $VERSION = sprintf "%d.%02d", q$Revision: 1.5 $ =~ /(\d+)\.(\d+)/; |
16dc9970 |
27 | |
077ebf34 |
28 | sub parse { "" } |
16dc9970 |
29 | |
30 | 1; |
31 | |
49e1eb70 |
32 | # ---------------------------------------------------------------------- |
16dc9970 |
33 | # Enough! or Too much. |
34 | # William Blake |
49e1eb70 |
35 | # ---------------------------------------------------------------------- |
36 | |
37 | =pod |
16dc9970 |
38 | |
39 | =head1 NAME |
40 | |
41 | SQL::Translator::Parser - base object for parsers |
42 | |
16dc9970 |
43 | =head1 DESCRIPTION |
44 | |
8295a8cc |
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. |
16dc9970 |
51 | |
8295a8cc |
52 | =head1 FORMAT OF THE DATA STRUCTURE |
16dc9970 |
53 | |
8295a8cc |
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 | |
49e1eb70 |
79 | =item B<indices> |
8295a8cc |
80 | |
49e1eb70 |
81 | The indices keys is a reference to an array of hashrefs. Each hashref |
8295a8cc |
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 | |
49e1eb70 |
91 | would be described in the indices element as: |
8295a8cc |
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', |
948190b3 |
125 | order => 1, # the order in the original table |
8295a8cc |
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', |
948190b3 |
146 | order => 1, |
8295a8cc |
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 | }, |
49e1eb70 |
156 | 'indices' => [ |
8295a8cc |
157 | { |
158 | 'name' => 'username_idx', |
159 | 'fields' => [ |
160 | 'username' |
161 | ], |
162 | 'type' => 'normal', |
163 | }, |
164 | ], |
165 | |
166 | =back |
167 | |
168 | |
169 | =head1 AUTHORS |
170 | |
d529894e |
171 | Ken Y. Clark, E<lt>kclark@cpan.org<gt>, |
49e1eb70 |
172 | darren chamberlain E<lt>darren@cpan.orgE<gt>. |
16dc9970 |
173 | |
174 | =head1 SEE ALSO |
175 | |
176 | perl(1). |
177 | |
178 | =cut |