1package Bigtop::Backend::SQL;
2use strict; use warnings;
3
4BEGIN {
5    Bigtop::Parser->add_valid_keywords(
6        Bigtop::Keywords->get_docs_for(
7                'field', 'is', 'refers_to', 'on_delete', 'on_update'
8        )
9    );
10
11    Bigtop::Parser->add_valid_keywords(
12        Bigtop::Keywords->get_docs_for(
13                'table', 'sequence', 'data', 'refered_to_by'
14        )
15    );
16
17    Bigtop::Parser->add_valid_keywords(
18        Bigtop::Keywords->get_docs_for( 'app_literal', 'SQL' )
19    );
20
21    Bigtop::Parser->add_valid_keywords(
22        Bigtop::Keywords->get_docs_for(
23                'join_table', 'joins', 'names', 'data'
24        )
25    );
26}
27
28package # table_block
29    table_block;
30use strict; use warnings;
31
32sub get_create_keyword {
33    my $self = shift;
34
35    return 'TABLE';
36}
37
38sub _skip_this_block {
39    my $self = shift;
40
41    my $skip = $self->walk_postorder( 'skip_this' );
42
43    return pop @{ $skip };
44}
45
46package # seq_block
47    seq_block;
48use strict; use warnings;
49
50sub get_create_keyword {
51    my $self = shift;
52
53    return 'SEQUENCE';
54}
55
56sub _skip_this_block {
57    my $self = shift;
58
59    my $skip = $self->walk_postorder( 'skip_this' );
60
61    return pop @{ $skip };
62}
63
64package # schema_block
65    schema_block;
66use strict; use warnings;
67
68sub get_create_keyword {
69    my $self = shift;
70
71    return 'SCHEMA';
72}
73
74sub _skip_this_block {
75    my $self = shift;
76
77    return;
78}
79
80package # table_element_block
81    table_element_block;
82use strict; use warnings;
83
84sub skip_this {
85    my $self         = shift;
86
87    if ( $self->{__BODY__} eq 'not_for' ) {
88        foreach my $skipped_backend ( @{ $self->{__ARGS__} } ) {
89            if ( $skipped_backend eq 'SQL' ) {
90                return [ 1 ];
91            }
92        }
93    }
94}
95
961;
97
98=head1 NAME
99
100Bigtop::Backend::SQL - defines legal keywords in table and field blocks
101
102=head1 SYNOPSIS
103
104If you are making an SQL generating backend:
105
106    use Bigtop::Backend::SQL;
107
108This specifies the valid keywords for the SQL generating backend.
109
110If you need additional keywords which are generally useful, add them
111here (and send in a patch).  If you need backend specific keywords, register
112them within your backend module.  Note that only keywords affecting
113the SQL should be put here.  But, fields have other keywords which
114affect things like how they look in html forms and whether they are fetched
115by default.  Register those keywords in Bigtop::Control:: or
116Bigtop::Model:: modules.
117
118=head1 DESCRIPTION
119
120If you are using a Bigtop backend which generates SQL, you should
121read this document to find out what the valid keywords inside table
122and field blocks are.
123
124If you are writing a Bigtop backend to generate SQL, you should use
125this module.  That will register the standard table and field keywords
126with the Bigtop parser.
127
128=head1 BASIC STRUCTURE
129
130A bigtop app block could look like this:
131
132    app name {
133        table name {
134            field name {
135            }
136        }
137    }
138
139=head1 KEYWORDS
140
141Inside the table, you can include the following keywords:
142
143=over 4
144
145=item sequence
146
147This must be the name of a valid sequence defined with an app level
148sequence block.  Any field whose 'is' list includes auto (which is an
149alias for assign_by_sequence) will use this sequence.
150
151=item data
152
153Allows you to include data for table population.  Include
154as many column name => value pairs as you need.  Repeat for each
155row you want to insert.  They will become INSERT INTO statements.
156
157Example:
158
159    table payeepayor {
160        field id    { is int, primary_key, assign_by_sequence; }
161        field name  { is varchar; }
162        sequence payeepayor_seq;
163        data
164            name => `Gas Company`;
165        data
166            id   => 2,
167            name => `Electric Company`;
168    }
169
170Note that it is not wise to manually assign ids for tables with sequence
171defaults.  I show it here as a simple syntactic example.
172
173Be somewhat careful with quoting.  Numbers won't be quoted, but
174strings will be.  If you need internal quotes, escape them as in:
175
176    data name => `Phil\'s Business Center`;
177
178Double quotes don't need escaping, since the value will be single quoted.
179
180=back
181
182Inside the field you may include
183
184=over 4
185
186=item is (required)
187
188This defines the basic SQL declaration for the column.  Provide a
189comma separated list of SQL column definition phrases or put them
190all in a back quoted string or use some combination of those.
191There are some keywords you can use, these are translated by the
192backend to their proper equivalents:
193
194=over 4
195
196=item int
197
198Short for int4.
199
200=item primary_key
201
202Not very short for PRIMARY KEY.
203
204=item assign_by_sequence
205
206Short for defaults to the next value from the sequence for this table.
207To use this, you must have a defined sequence for the table and that
208sequence must be defined at the app level.  (Defining it twice seems odd
209to me, but some tables must share an index.  The app level definition
210creates the sequence, as in it generates 'CREATE SEQUENCE...'.  The table
211level definition ties this table to a sequence, as in it generates
212a default clause with the sequence in it.)
213
214=item auto
215
216A pure synonymn for assign_by_sequence, for those who refuse to type
217so long a keyword.
218
219=back
220
221=item update_with
222
223Not currently supported.
224
225=item refers_to
226
227This marks the column as a foreign key (whether a genuine SQL foreign
228key is used is up to the backend).  Currently, you can only specify the
229table this column points to.  The assumption about which column varies
230depending on who's doing the assuming.  For example, Class::DBI assumes
231the column refers to the primary key of the other table.  Gantry makes
232the tacit assumption that the primary key is the single column called id.
233
234=back
235
236=head1 AUTHOR
237
238Phil Crow <crow.phil@gmail.com>
239
240=head1 COPYRIGHT and LICENSE
241
242Copyright (C) 2005 by Phil Crow
243
244This library is free software; you can redistribute it and/or modify
245it under the same terms as Perl itself, either Perl version 5.8.6 or,
246at your option, any later version of Perl 5 you may have available.
247
248=cut
249