/ 
Bigtop-0.21
River stage zero No dependents
/ bigtop

NAME

bigtop - the parser/generater for the bigtop langauge

SYNOPSIS

For regnerating pieces of an existing app:

bigtop [options] file.bigtop all

Or, for brand new apps:

bigtop --new AppName 'ascii_art'

Or, to augment an existing app:

bigtop --add app.bigtop 'ascii_art'

See "ASCII Art" below for what ascii_art can be.

DESCRIPTION

To learn more about bigtop, consult Bigtop::Docs::TOC. It has a list of all the documentation along with suggestions of where to start.

This script usually takes a bigtop input file and a list of things to build. The things you can build have the same names as the blocks in the config section of your bigtop file. You may also choose all which will build all of those things in the order they appear in the config section.

If you are starting a new app from scratch, you can get a jump start with the --new flag (or -n):

bigtop --new AppName table1 table2

If you already have a bigtop file, you can add to it with the --add (or -a):

bigtop --add file.bigtop table3 table4

But, see "ASCII Art" below for more interesting options than a list of table names.

Both new and add options do an all build when they finish making/updating the bigtop file. If you don't want an immediate all build, try tentmaker with the same flags.

The new option will also try to build a database for the app to use immediately using sqlite (if it can find it in your path).

NON-HELP OPTIONS

--create (or -c)

Use this if you already have a bigtop source file and want to make a brand new app from it. Perhaps someone gave you a bigtop file, you copied one from the examples directory of the bigtop distribution, or you built one with tentmaker.

This will make an h2xs style path under the current directory for the app described in your bigtop file. It will even copy that bigtop file into the docs directory while it builds whatever you ask for.

Without this option, if the current directory looks like a bad place to build, a fatal error will result and you will have to use this option. A bad place to build is a place where building seems not to have happened before. If any of these are missing, then the directory is bad:

Build.PL
Changes
t/
lib/

When create is in effect, the following bigtop config options affect the location of the initial build:

base_dir

the directory under which all building will happen. Defaults to the current directory.

app_dir

the subdirectory of base_dir where Build.PL and friends will live. Defaults to the h2xs style directory name based on your app's name. If your app section starts:

app App::Name::SubName

then the default app_dir is:

App-Name-SubName

When create is not in effect, these config parameters are ignored WITH a warning.

--new (or -n) App::Name [table_1...|ascii_art]

See "ASCII Art" below for how to specify table relationships.

Use this option to create a working application from scratch. If you only provide an app name, it will use a minimal bigtop specification. The resulting app will not run (or have any code in it). You must then augment the bigtop file with tentmaker or a text editor and regenerate to get a running app.

If you supply optional table names or ASCII art, enough additional items will be added to the bigtop file to make a running app (except that you might need to build the database). Some of the extra items will be repeated for each model you request.

In either case, when bigtop finishes, there will be an App-Name subdirectory of the current directory. In it will be all the usual pieces describing an app. The bigtop file will be in the docs directory.

If you have a working sqlite in your path -- and you specified tables or ASCII art -- -n will also make an sqlite database called app.db in the build directory. As it will tell you, you can change to that directory and start the app immediately.

If you don't have sqlite, a message will explain what to do to start the app. Mostly this boils down to changing into the new build directory, creating a database called app.db, and running app.server with the proper flags for your database engine.

--add (-a )

If you have an existing bigtop file and want to add tables and their controllers to it, use this option like this:

bigtop --add file.bigtop table...|ascii_art

See "ASCII Art" below for how to specify table relationships.

This option reads an existing file.bigtop and adds tables and controllers to it, before doing an all build. (If you don't want an all build, use the same options with tentmaker.)

Any new tables will be created. All relationships in the ASCII art will be applied, even if they affect existing tables.

Note that this option may disturb comments and whitespace in your original. It uses Bigtop::Deparser, which cannonicalizes the whitespace. Basically extraneous whitespace is removed (and indenting is regularized). When new lines are removed, subsequent comments drift down in the revised file.

Revision control is always a good idea. It is especially important here. Make sure file.bigtop is commited to your revision control system prior to running bigtop in add mode.

--keep_inline (or -k)

Normally, this script removes all traces of the _Inline directory it used while building your app. Use this option if you want to save a microscopic amount of time on each regeneration or if you have an incurable curiosity.

Note that the directory will only be removed if it is really _Inline in the current directory. If you have a .Inline directory under home directory etc., the script will not affect it.

HELP OPTIONS

In addition to the flags that do useful things, there are help flags:

--help or -h

Prints a multi-line usage message showing all the options.

--pg_help and --mysql_help

Print advice on how to start your app.server with a Postgres or MySQL database instead of sqlite. This includes instructions on creating and building the database, as well as flags app.server needs in order to reach that database.

ASCII Art

Both --new and --add allow you to specify a list of tables or ASCII art. The ASCII art option allows you to quickly note relationships between tables with simple operators.

Note well: Since the relationship operators use punctuation that your shell probably loves, you must surround the art with single quotes.

It is easiest to understand the options 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   |
+-----------+       +----------+

First, you'll be happy to know that bigtop's ASCII art is simpler to draw than the above.

What our data model shows is that each position refers to a job (description), 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.

Here's how to specify this data model in bigtop ASCII art:

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 art 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.

->

The first table has a foreign key pointing to the second.

<-

The second table has a foreign key pointing to the first. This is really a convenience synonymn for ->, but the tables are put into generated SQL in their overall order of appearance. So, there is a slight differnce between them.

-

The two tables have a one-to-one relationship. Each of them will have a foreign key pointing to the other.

AUTHOR

Phil Crow <crow.phil@gmail.com>

COPYRIGHT and LICENSE

Copyright (C) 2005-6 by 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.