.\" 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 3"
.TH Bigtop 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Bigtop \- A web application data language processor
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
See Bigtop::Docs::TentTut or Bigtop::Docs::Tutorial for how to create
a Bigtop file.  Bigtop::Docs::TOC is a guide to all of the
documentation modules.
.PP
The real synopsis (see Bigtop::ScriptHelp::Style::Kickstart):
.PP
.Vb 3
\&    bigtop --new AppName 'stock<-lot
\&    stock(symbol,name)
\&    lot(bought:date,price:int4,shares:int4)'
.Ve
.PP
or go manual:
.PP
.Vb 2
\&    vi your_app.bigtop (or use tentmaker see Bigtop::Docs::TentTut)
\&    bigtop --create your_app.bigtop all
.Ve
.PP
Then run your app (if you have sqlite in your path):
.PP
.Vb 2
\&    cd AppName
\&    ./app.server
.Ve
.PP
Modify your bigtop file and try again:
.PP
.Vb 1
\&    bigtop docs/your_app.bigtop all
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Bigtop is a language for describing the data of a web application.  Usually
this data will be stored in a relational database.  Once you have a
description of your data, you can generate a web application from it.
This includes all the pieces you need like: the sql statements ready for
feeding to your database command line tool, the httpd.conf you need to
Include in the httpd.conf on your system, the modules that will handle
the web requests, the models that make the database tables look like classes,
etc.
.PP
If you need to alter the data model in the future, you can change your
original description to match the new reality, then regenerate the
application without fear of losing hand written code (though you may
have to modify some of it to reflect the new reality).
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
This module is really a place holder, but it does provide some developer
routines (which are not exported):
.IP "write_file" 4
.IX Item "write_file"
.Vb 2
\&    use Bigtop;
\&    Bigtop::write_file( $file_name, $file_content, $no_overwrite )
.Ve
.Sp
This attempts to write \f(CW$file_content\fR to \f(CW$file_name\fR and dies on failures
of open or close.  Further, if you pass a true no_overwrite flag, it
will check to see if the file exists and refuse to overwrite it.  In that
case, the user gets a warning that the file has been skipped because it
already exists.  If you don't want the user to see the warning, turn off
the Bigtop warning.  To avoid fatal errors on write failures, wrap in an
eval.  Putting these together, we come to my typcial usage:
.Sp
.Vb 5
\&    eval {
\&        no warnings qw( Bigtop );
\&        Bigtop::write_file( $some_output_file, $content, 'no_overwrite' );
\&    }
\&    warn $@ if $@;
.Ve
.IP "make_module_path" 4
.IX Item "make_module_path"
(Note that make_module_path uses File::Spec, so even though Unix directory
syntax is shown below, the function should work in other places.)
.Sp
.Vb 2
\&    use Bigtop;
\&    Bigtop::make_module_path( $build_dir, $module_name );
.Ve
.Sp
This attempts to make all the directories from \f(CW$build_dir\fR to the home
of the module.  It assumes that lib comes immediately after \f(CW$build_dir\fR.
.Sp
For example, a call like:
.Sp
.Vb 3
\&    Bigtop::make_module_path(
\&        '/home/username/App-Name', 'App::Name::Subname'
\&    );
.Ve
.Sp
Attempts to make these directories:
.Sp
.Vb 4
\&    /home/username/App-Name/lib
\&    /home/username/App-Name/lib/App
\&    /home/username/App-Name/lib/App/Name
\&    /home/username/App-Name/lib/App/Name/Subname
.Ve
.Sp
It doesn't report failures.  Making directories can fail because the
directories already exist (in which case you probably don't care) or
because they could not be written (in which case you'll notice soon enough,
when you try to write to them).
.Sh "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Bigtop::Docs::TOC
.PP
If you are interested in Bigtop's inner workings, consider delving into
some of these:
.IP "\(bu" 4
Bigtop::Parser
.IP "\(bu" 4
Bigtop::Keywords
.IP "\(bu" 4
Bigtop::Backend::Init
.IP "\(bu" 4
Bigtop::Backend::Init::Std
.IP "\(bu" 4
Bigtop::Backend::SQL
.IP "\(bu" 4
Bigtop::Backend::SQL::Postgres
.IP "\(bu" 4
Bigtop::Backend::CGI
.IP "\(bu" 4
Bigtop::Backend::CGI::Gantry
.IP "\(bu" 4
Bigtop::Backend::Control
.IP "\(bu" 4
Bigtop::Backend::Control::Gantry
.IP "\(bu" 4
Bigtop::Backend::HttpdConf
.IP "\(bu" 4
Bigtop::Backend::HttpdConf::Gantry
.IP "\(bu" 4
Bigtop::Backend::Model
.IP "\(bu" 4
Bigtop::Backend::Model::GantryDBIxClass
.IP "\(bu" 4
Bigtop::Backend::SiteLook::GantryDefault
.PP
The backends come in types.  Ideally, these types all share a set of
keywords which are requested from Bigtop::Keywords in the type's module.
So Bigtop::Backend::SQL is meant to request the \s-1KEYWORDS\s0 that all
Bigtop::SQL::* modules use.  They may request others, but only if they are
specific to the generated target.  For example, there might be some Postgres
specific keyword which doesn't apply to other databases.  It should be
requested in \f(CW\*(C`Bigtop::Backend::SQL::Postgres\*(C'\fR.  Even if you need backend
specific keywords, you should put them in \f(CW\*(C`Bigtop::Keywords\*(C'\fR so tentmaker
can display them.
.SH "JOIN US"
.IX Header "JOIN US"
Bigtop is discussed on the Gantry mailing list.  Please visit
http://www.usegantry.org, and click on the Mailing List tab under the
banner, for instructions.
.PP
Bigtop source is available for svn checkout.  For instructions, visit:
.PP
.Vb 1
\&    http://usegantry.org
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Phil Crow, <crow.phil@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2005\-7, 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.