.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bigtop::ScriptHelp::Style::Kickstart 3"
.TH Bigtop::ScriptHelp::Style::Kickstart 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Bigtop::ScriptHelp::Style::Kickstart \- handles kickstart syntax for scripts
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Most users use this module as the default style for the bigtop and
tentmaker scripts:
.PP
.Vb 1
\&    bigtop -n AppName [kickstart]
.Ve
.PP
See \*(L"\s-1KICKSTART\s0 \s-1SYNTAX\s0\*(R" below for details, but note that kickstart could
be a file whose contents are in kickstart syntax.
.PP
If you are writing a script that want to leverage styles do this:
.PP
.Vb 1
\&    use Bigtop::ScriptHelp::Style;
.Ve
.PP
.Vb 1
\&    my $style = Bigtop::ScriptHelp::Style->get_style( 'Kickstart' );
.Ve
.PP
.Vb 1
\&    # then pass $style to methods of Bigtop::ScriptHelp
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
See \f(CW\*(C`Bigtop::ScriptHelp::Style\*(C'\fR for a description of what this module
must do in general.
.SH "METHODS"
.IX Header "METHODS"
.IP "get_db_layout" 4
.IX Item "get_db_layout"
This method does not use standard in.  Instead, it expects
kickstart syntax.  See \*(L"\s-1KICKSTART\s0 \s-1SYNTAX\s0\*(R" below.
.SH "KICKSTART SYNTAX"
.IX Header "KICKSTART SYNTAX"
Bigtop's kickstart syntax allows you to describe your tables, their columns,
and how they are related to other tables in a compressed text style.
.PP
Note well: Since the descriptions use punctuation that your shell probably
loves, you must surround them with single quotes on the command line.  But,
there's 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
file's name as in:
.PP
.Vb 1
\&    tentmaker -a docs/app.bigtop kickstart_file
.Ve
.PP
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:
.PP
.Vb 8
\&    +-----------+       +----------+
\&    |    job    |<------| position |
\&    +-----------+       +----------+
\&          ^
\&          |
\&    +-----------+       +----------+
\&    | job_skill |------>|  skill   |
\&    +-----------+       +----------+
.Ve
.PP
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.
.PP
Here's how to specify this data model with bigtop kickstart syntax:
.PP
.Vb 1
\&    bigtop --new HR 'job<-position job<->skill'
.Ve
.PP
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.
.PP
The same kickstart can be used with \-\-new and \-\-add for both bigtop
and tentmaker scripts.
.PP
There are four kickstart table relationship operators:
.IP "<\->" 4
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.
.IP "<\- or *>" 4
.IX Item "<- or *>"
The second table has a foreign key pointing to the first.
.Sp
The *> form is useful if you want to read the relationship with the phrase
\&'has\-many' as in
.Sp
.Vb 1
\&    book*>chapter
.Ve
.Sp
Each book has many chapters.  Instead of
.Sp
.Vb 1
\&    book<-chapter
.Ve
.Sp
Each chapter belongs to a book.  But, both forms are equivalent.
.IP "\-> or <*" 4
.IX Item "-> or <*"
The first table has a foreign key pointing to the second.  This is really
a convenience synonymn for <\-.
.Sp
Note that tables will appear in the generated \s-1SQL\s0 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.
.IP "\-" 4
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 \s-1SQL\s0 which
is unlikely to load well due to foreign key forward references.
.Sh "\s-1COLUMN\s0 \s-1DEFINITIONS\s0"
.IX Subsection "COLUMN DEFINITIONS"
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.
.PP
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, you'll need to edit the generated bigtop file, just like
old times.
.PP
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:
.PP
.Vb 1
\&    bigtop -n App 'family(name,+phone)<-child(name,birth_day:date)'
.Ve
.PP
By default all columns will have type varchar (but note that \s-1SQL\s0 backends
translate that into some other string type for all supported databases,
if a bare varchar wouldn't 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.
.PP
Do not include foreign key columns in the list.  They will be generated
based on the relationship punctuation between the tables.
.PP
The phone column in the family table has a leading plus sign, and will
therefore be optional on the \s-1HTML\s0 form.
.PP
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:
.PP
.Vb 2
\&    bigtop -a docs/app.bigtop '
\&        anniversary(anniversary:date,gift_pref=money)<-family'
.Ve
.PP
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 \s-1HTML\s0 forms of 'money.'  Finally, a new foreign key will be added
to the existing family table pointing to the anniversary table.
.PP
You may find it easier to supply the kickstart text by first specifying the
relationships without including the columns, then defining the columns later:
.PP
.Vb 5
\&    tentmaker -n App \e
\&    'child->family anniversary->family
\&        child(name,birth_day:date)
\&        family(name,+phone)
\&        anniversary(anniversary:date,gift_pref=money)'
.Ve
.PP
You may mention a table as many times as you like, but only define its
columns once.
.PP
Finally, as mentioned in the \s-1SYNOPSIS\s0, and described in more detail below
(see \*(L"\s-1KICKSTART\s0 \s-1FILES\s0\*(R", you may put the kickstart in
a file and supply the file name on the command line:
.PP
.Vb 1
\&    tentmaker -n App app.kickstart
.Ve
.PP
None of the syntax changes when you use the file approach, except that
you don't need the shell quotes.  In paricular, using a file does not
allow you to include spaces within a table's definition.
.Sh "\s-1FORMAL\s0 \s-1SUMMARY\s0"
.IX Subsection "FORMAL SUMMARY"
Here is the formal syntax for each table definition:
.PP
.Vb 1
\&    name(COL_DEF[,COL_DEF...])
.Ve
.PP
Where name is a valid \s-1SQL\s0 table name and \s-1COL_DEF\s0 is as follows:
.PP
.Vb 1
\&    [+]col_name[:TYPE_INFO][=default]
.Ve
.PP
Where plus makes the \s-1HTML\s0 form field for the column optional,
col_name is a valid \s-1SQL\s0 column name, and
all defaults are literal strings (they will be quoted in \s-1SQL\s0).  If you need
more interesting defaults, edit the bigtop file after it is updated.
\&\s-1TYPE_INFO\s0 is a colon separated list of column declaration words.
.PP
Suppose you want this column definition:
.PP
.Vb 1
\&    state int4 NOT NULL DEFAULT 4,
.Ve
.PP
Say this:
.PP
.Vb 1
\&    state:int4:NOT:NULL=4
.Ve
.Sh "\s-1KICKSTART\s0 \s-1FILES\s0"
.IX Subsection "KICKSTART FILES"
Traditionally, kickstart text was specified on the command line.  Now you
can put it in a file and invoke bigtop or tentmaker like this:
.PP
.Vb 1
\&    bigtop -n NewApp file.kickstart
.Ve
.PP
Unfortunately, you cannot currently pipe to bigtop to tentmaker, they
do not read from standard in.
.PP
Here is an example kickstart file for a blogging application:
.PP
.Vb 13
\&    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
.Ve
.PP
Note again that spaces are not allowed in column definition lists, since
whitespace is the separator of table and table relationship entries.
.SH "AUTHOR"
.IX Header "AUTHOR"
Phil Crow, <crow.phil@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007, Phil Crow
.PP
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.