This method is for internal use, but is exposed so subclasses dont have
to implement it. It specifies that definitions like
will be parsed with parse_columns (see below).
|get_db_layout||This method does not use standard in. Instead, it expects kickstart syntax. See KICKSTART SYNTAX below.|
Subclasses override this method to control which columns are created by
default. Note that if a user explicitly declares a column in the
parentheses of a table definition, the corresponding column in this
collection is ignored.
Returns a hash with two keys: is_normal_default and normal_defaults. is_normal_defaults is a hash keyed by the name of each column with two keys: where (either front or rear) and typees (an anonymous array of Bigtop is values, usually these are SQL types or other column definition phrases). normal_defaults is an anonymous array of column names, they must correspond to keys in is_normal_defaults. The order of the columns in the array controls when they are added to the list of columns. But, remember that where decides whether to unshift or push them into the list.
For example, the method in this module does this:
Suppose a table is in the kickstart file, but has no column definitions.
It will get columns. First, this method returns a string which is
the default art for the table. Second, as with all tables, columns
returned by get_default_base_columns are added.
The method in this module returns:
If you return the empty string, no filler columns will be added to your tables.
|parse_columns||This method is exposed so subclasses dont have to implement it. It receives a kickstart art string and parses it into an anonymous array of columns. Each element in the array is a hash with keys name (the name of the SQL column) and types (an anonymous hash of Bigtop is values, which are an SQL type and a list of other column definition phrases). There are other keys: default and optional. These are used when the art includes = or +.|
|print_instructions||Called by bigtop script when it makes a new application containing table definitions (you used art with this style). Prints instructions on how to start the development application using sqlite.|
|help_pg||Revises the instructions from print_instructions so they are good for PostgreSQL.|
|help_mysql||Revises the instructions from print_instructions so they are good for mysql.|
Bigtops kickstart syntax allows you to describe your tables, their columns, and how they are related to other tables in a compressed text style.
Note well: Since the descriptions use punctuation that your shell probably loves, you must surround them with single quotes on the command line. But, theres no need to do that if you put the kickstart description in a file. To use the file method, put your kickstart in a file and give that files name as in:
It is easiest to understand kickstart syntax is by seeing an example. So, suppose we have a four table data model describing a bit of our personnel process:
+-----------+ +----------+ | job |<------| position | +-----------+ +----------+ ^ | +-----------+ +----------+ | job_skill |------>| skill | +-----------+ +----------+
What this data model shows is that each position refers to a job, each job could require many skills, and each skill could be associated with many jobs. The last two mean that job and skill share a many-to-many relationship.
bigtop --new HR job<-position job<->skill
This indicates a foreign key from position to job and an implied table, called job_skill, to hold the many-to-many relationship between job and skill.
There are four kickstart table relationship operators:
<-> Many-to-many. A new table will be made with foreign keys to each operand table. Each operand table will have a has_many relationship. Note that your Model backend may not understand these relationships. At the time of this writing only Model GantryDBIxClass did, by luck it happens to be the default. <- or *> The second table has a foreign key pointing to the first.
The *> form is useful if you want to read the relationship with the phrase has-many as in
Each book has many chapters. Instead of
Each chapter belongs to a book. But, both forms are equivalent.
-> or <* The first table has a foreign key pointing to the second. This is really a convenience synonymn for <-.
Note that tables will appear in the generated SQL so that foreign keys appear after the tables they refer to (at least that is the goal). Hence the order of your tables in the kickstart has no bearing on their order in the bigtop file.
- The two tables have a one-to-one relationship. Each of them will have a foreign key pointing to the other. Note that this will create SQL which is unlikely to load well due to foreign key forward references.
As of Bigtop 0.23, you may use the syntax below to specify information about the columns in your tables, in addition to the table relationships above.
Note Well: When following the instructions below, never be tempted to use spaces inside column definitions. If you need spaces, colons might work. If not, youll need to edit the generated bigtop file, just like old times.
Column definitions must be placed inside parnetheses immediately after the table name and immediately before any table relationship operator. Separate columns with commas. Specify type definitions with colons. Use equals for defaults and leading plus signs for optional fields. For example:
bigtop -n App family(name,+phone)<-child(name,birth_day:date)
By default all columns will have type varchar (but note that SQL backends translate that into a valid string type for each supported database, if a bare varchar wouldnt work). If you need some other type, use a colon, as I did for birth_day. If your type definition needs multiple words, use colons instead of spaces.
Do not include foreign key columns in the list. They will be generated based on the relationship punctuation between the tables.
The phone column in the family table has a leading plus sign, and will therefore be optional on the HTML form.
You can still augment the bigtop file later. Existing tables in the bigtop file will have foreign keys added as specified by relation operators, but parenthetical column lists will be used only for new tables. For example:
This will add a new table called anniversary with anniversary (a date) and gift_pref columns. The later will have a default value in the database and on HTML forms of money. Finally, a new foreign key will be added to the existing family table pointing to the anniversary table.
You may find it easier to supply the kickstart text by first specifying the relationships without including the columns, then defining the columns later:
tentmaker -n App \ child->family anniversary->family child(name,birth_day:date) family(name,+phone) anniversary(anniversary:date,gift_pref=money)
You may mention a table as many times as you like, but only define its columns once.
Finally, as mentioned in the SYNOPSIS, and described in more detail below (see KICKSTART FILES), you may put the kickstart in a file and supply the file name on the command line:
tentmaker -n App app.kickstart
None of the syntax changes when you use the file approach, except that you dont need the shell quotes. In paricular, using a file does not allow you to include spaces within a tables definition.
Here is the formal syntax for each table definition:
Im following the convention that brackets enclose optional elements. Everything else appears as is, or is defined below.
Where name is a valid SQL table name and COL_DEF is as follows:
Where plus makes the HTML form field for the column optional, col_name is a valid SQL column name, and all defaults are literal strings (they will be quoted in SQL). If you need more interesting defaults, edit the bigtop file after it is updated. TYPE_INFO is a colon separated list of column declaration words.
Suppose you want this column definition:
state int4 NOT NULL DEFAULT 4,
Traditionally, kickstart text was specified on the command line. Now you can put it in a file and invoke bigtop or tentmaker like this:
bigtop -n NewApp file.kickstart
Here is an example kickstart file for a blogging application:
blog(active:int4,ident,title,subtitle,blurb,body,gps,comments_enabled:int4,rank:int4,section,username,tag) author(name,address,city,state,country,gps) comment(active:int4,rejected:int4,name,email,url,subject,body) link(active:int4,location,label,posted_date,score,username,tag) tag(active:int4,label,rank) image(active:int4,label,descr,file,default_image,file_ident,file_name,file_size:int4,file_mime,file_suffix) attachment(active:int4,label,descr,file,default_image,file_ident,file_name,file_size:int4,file_mime,file_suffix) section(active:int4,label) blog<-image blog<-attachment blog<-author blog<-comment blog<-section
Note again that spaces are not allowed in column definition lists, since whitespace is the separator of table and table relationship entries.
Phil Crow, <email@example.com>
Copyright (C) 2007, Phil Crow
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.
|perl v5.20.3||BIGTOP::SCRIPTHELP::STYLE::KICKSTART (3)||2016-04-03|