NAME

Bigtop::Docs::Syntax - A (mostly) complete Bigtop syntax description

Intro

This document is a fleshing out of Bigtop::Docs::Keywords. Note that you might find Bigtop::Docs::Cookbook more useful depending on the complexity of your questions and how you like to use docs. This is like a text book, the cookbook teaches exclusively by example. See also the examples directory in the distribution.

Anatomy of a Bigtop File

Bigtop files are designed to be easy to write and to read (by you and the computer). There is a basic structure based on brace delimited blocks, but it's not complicated like a programming language. It's a descriptive language. There is no flow of control. That means that you can put things in whatever order you like, except that config comes first and some recipients of the generated files may care about order. For instance, your command line SQL tool probably expects to see the definition for a sequence before it sees a table which uses it. These orderings are usually fairly intuitive, especially when that other program complains about missing definitions, etc.

The following skeleton is the smallest legal bigtop file which describes almost nothing (and will do nothing if you feed it to bigtop):

config {}
app App::Name {}

config Section

At the top level there are two sections in a Bigtop file. The order is enforced (though I can't really defend that). First comes the config. It lists things that make the output specific. In it, there are statements and backend blocks. Each statement can take exactly one value. If there are any characters that Perl wouldn't like in an identifier, enclose the value in backquotes (the quote usually found under tilde, not the ones on the same key with double quotes).

The available config statements are:

engine

This is the web engine you plan to use. Example:

engine MP13;

This notation is stolen from Catalyst and is also used in Gantry. Your actual choices are dependent on which framework you use and what the backend for that framework is expecting. Gantry supports these:

MP13 - mod_perl 1.3.x
MP20 - mod_perl 2.x
CGI  - cgi/fast cgi

template_engine

The templating system you want to use. Example:

template_engine TT;

Where TT could be replaced with one of these.

Default
Mason
Your::Soon::To::Be::Replaced::We::Hope::Home::Rolled::Templater

The Default will probably provide raw text/html output. Which of these you can choose, and what they do, is determined by your framework.

[ A fact which is still strange to me: Bigtop has no knowledge of the templates your application will use (though some of its backends might). ]

base_dir

Deprecated.

Optional, defaults to the current directory. Ignored with a warning except in create mode.

A path to where the app will be built. Enclose paths in backquotes. Example:

base_dir `/home/phil/play`;

app_dir

Deprecated.

Optional, defaults to the h2xs style directory name for your app. Ignored with a warning except in create mode.

A path relative to base_dir where Build.PL, Changes, README, etc. will live. For example, if your app block looks like this:

app MyNS::Apps::Name

the default will be MyNS-Apps-Name under the base_dir.

In addition to these hard coded keys, there are backend blocks which depend on what Bigtop:: modules you have installed. These typically generate files on the disk, which could be Perl modules, httpd.confs, etc.

The system is simplistic and best described by an example. Suppose you list

SomeType  SomeBackend {}

in the config section. Bigtop will assume the following (yes, I know how dangerous assumptions can be):

You have a package called Bigtop::SomeType::SomeBackend, defined in the usual way, which is installed on your system. (i.e. There is a file called SomeBackend.pm which defines the package Bigtop::SomeType::SomeBackend, which lives in the path Bigtop/SomeType/SomeBackend.pm, relative to an @INC member.)
That package has a method called gen_SomeType which does whatever backends of this type should do (it might make .pm files, .conf files, .sql files etc.). This allows bigtop to call gen_SomeType when the user types:
```
bigtop file.bigtop SomeType
```

The distribution comes with a number of these Bigtop:: backends. [ See Bigtop Backends below for a list. ] If you write a useful one, please send it in so we can include it in a future release.

As a user, you can mark a file as not to be generated by saying:

SomeType SomeBackend { no_gen 1; }

This serves as a reminder that you generated SomeType in the past, but have messed with the result (even though you were probably warned not to). But, more importantly, it allows SomeBackend to register the keywords it handles, so their absence doesn't generate parse errors.

Most backends also honor the template statement. If you say:

SomeType SomeModule { template my_template.tt; }

Bigtop::SomeType::SomeModule will use my_template.tt instead of the one hard coded inside it. Note that the template must be directly usable by Template Toolit. Further, it needs to define the same blocks as the backend's normal template. It's usually best to start by copying the template from the here doc in the backend into a file, then modify it.

That is all there is to the config section. A typical one looks like this:

config {
#   base_dir        `/home/user_name`;
    engine          MP20;
    template_engine TT;
    Init            Std        { no_gen 1; }
    SQL             Postgres   {}
    Control         Gantry     {}
    Model           GantryCDBI {}
}

Note that the base_dir statement is commented out. A comment is any line whose first non-whitespace character is a pound sign. In fact, base_dir is rarely needed.

After the "app Section", there is a list of all the current backends, what keywords they understand and what they do with them (if they do anything special).

app Section

The app section is far more interesting than the config section. This is where you describe the data in your application and how you want the user to view and manipulate it. This is the heart of the Bigtop file. Theoretically, you can completely recast the app (say by exchanging Postgres for mysql, Catalyst for Gantry, mod_perl 1.3 for mod_perl 2.0, etc.) without changing the app section. Whether you can do that in practice depends on whether there are backends for the system you want to move to (if you are interested in writing backends, see Bigtop::Docs::Modules for some pointers). Reality also impinges on this ideal. Some backends understand different keywords, because they work with different concepts.

In the app section, there are two key components:

Blocks

Most blocks look like this:

block_type Name {
    ... statements or blocks
}

Controller and method blocks are exceptions. These have a type property (the type is required for methods but is optional for controllers):

method name is stub { ... }

The legal values of this property are specified in the Bigtop::Control:: backend you choose. See it's docs for a list of the types and what they mean, but the trivial type, stub, is always supported.

Statements

Some examples of statements:

label          Description;
label          `First Name`;
header_options Add => `$site->location . '/add`;
cols           first_name, last_name, age;

A statement is a legal keyword followed by a value and terminated with a semi-colon. Legal values are numbers, valid Perl idents (including colons), anything you enclose in backward quotes (see A Note About Quotes in Strings if you need to embed quotes in strings), and comma separated lists of the above.

Note that we sometimes use => instead of comma, they mean substantially different things. Only use => when the backend tells you to. Always use the => when the backend tells you to.

(Footnote on fat commas: In the grammar, comma is the separator for items in a list, while the fat comma (=>) forms a pair which becomes a single element in the list. If your backend is expecting two items and it gets one pair instead, it will be sorely confused. Likewise, if your backend is expecting a pair, but you give it two items separated by comma, it will be just as confused. This is different from the way Perl treats the fat comma.)

Which keywords are legal depends on which backends you are using. Whether a particular keyword's value will work is up to the backend and to whatever program ends up receiving what the backend produced.

A Note About Quotes in Strings:

You can put whatever you like into backquoted strings (as long as you don't like backquotes). But if you put quotes in such strings, you may need to escape them in some way. For example, if the string is a label for html presentation, your backend will likely take your:

label `Customer's Name`;

and make it something like:

some_display_function('Customer's Name');

This will not work, since the generated Perl now has an extra single quote. Usually you avoid this by protecting the quote like this:

label `Customer\'s Name';

This results in the correct final output:

some_display_function('Customer\'s Name');

You must read the backend documentation to find out what will happen to the value you provide, but the above is typical.

[ Note for those who read tests as examples: In the tests you will see quotes protected by two backslashes. This is because the tests use here documents to build bigtop input. The first backslash is eaten by the heredoc processor. Since you will supply input from file (at least most of the time), you should not need two backslashes. ]

The general structure of the app section is:

app App::Name { }

In fact, that is a valid specification, but it doesn't do much (you could generate Init for such an app, but that would do slightly less than h2xs).

Inside the braces there are statements and blocks.

While the app level keywords are all defined by various backends, here are some that are commonly available:

authors

(registered by Bigtop::Control and Bigtop::Init::Std)

A comma separated list of authors (use backquotes around these to protect spaces, etc.). These authors will be put into the README file and into the AUTHORS section of the stub modules' POD.

authors `Phil Crow` => `philcrow2000@yahoo.com, `My Friend`;

Each author item may be either a name or name => email pair.

Note that Bigtop::Init:Std apps use Module::Build. It requires a meaningful authors section for ./Build dist. So this statement is not usually optional.

contact_us

(registered by Bigtop::Control and Bigtop::Init::Std)

Describe how to contact or join project developers:

    contact_us `Visit us at www.useourproject.org, or join our mailing
list by sending subscribe to list-sub@useourproject.org`;

Note that all manner of whitespace is legal inside the quotes, the value will be used literally.

copyright_holder

(registered by Bigtop::Control and Bigtop::Init::Std)

By default the copyright holder listed in README and POD is the first author. If you want someone else, list them here. For example, the app might belong to your company:

copyright_holder `The World Company`;

license_text

(registered by Bigtop::Control and Bigtop::Init::Std)

By default the license in README and POD is what h2xs produced for perl 5.8.0. Use this, if you want something different (e.g. due to company policy):

license_text `All rights reserved.`;

Include the complete text here. Feel free to include new lines in the backquotes.

location

(registered by Bigtop::HttpdConf, Bigtop::CGI, and Bigtop::SiteLook::GantryDefault)

The root location in your apache conf or cgi dispatching script. Defaults to /.

uses

(registered by Bigtop::Control, understood by Bigtop::Control::Gantry)

A list of modules which will be used in the base modules of the application.

literal

(part of the grammar)

Literal means literal. Enclose the value in backquotes and it will appear in the result unmodified. (Exception: one new line will be added if the literal does not already have trailing whitespace.) This means you are primarily responsible for white space management.

At the app level, there are several valid literal types:

HttpdConf

(registered by Bigtop::HttpdConf)

Places arbitrary directives between location blocks in httpd.conf:

literal HttpdConf `Include /some/other/file.conf

`;

You can certainly use this to add locations for which you don't have controllers defined in your Bigtop file. This opens the option of continuing to regenerate even after you have extra locations or other directives.

Literal HttpdConf directives appear in the generated output with controller locations in the order these appear in the Bigtop file.

Location

(registered by Bigtop::HttpdConf)

Places Apache directives directly into the root location of the app:

literal Location `    require valid-user`;

PerlTop

(registered by Bigtop::HttpdConf and Bigtop::CGI)

Places perl code immediately under the #!/usr/bin/perl line in either the <Perl> block in the generated httpd.conf or in the CGI/FastCGI dispatching script. May be repeated. Output appears in the same order as the statements in the Bigtop file. Example:

literal PerlTop `    use lib '/home/myuser/perl/lib';`;

PerlBlock

(handled by Bigtop::HttpdConf)

Places perl code into the <Perl> block in the generated httpd.conf after the use statement for the base module of the app. Output appears in the same area as the use statements for controller blocks, in the same order as the statements and controller blocks appear in the bigtop file. Example:

controller SubName {
    #...
}
literal PerlBlock `    use Some::Module;`;
controller OtherName {
    #...
}

yeilds:

<Perl>
    #!/usr/bin/perl

    use BaseModule;
    use SubName;
    use Some::Module;
    use OtherName;
</Perl>

You may prefer to have a single literal PerlBlock at the bottom of the bigtop file, below all of the controllers.

SQL

(registered by Bigtop::SQL)

Places SQL statements directly into schema.* generated by Bigtop::SQL::* modules. Literal SQL statements are mixed with sequences and tables in the generated file with all of them appearing in the output in the order they appear in the input.

There are additional literal statements at other levels.

Currently there are four legal block types at the app level: sequence, config, table, and controller. These are described in detail directly below.

sequence

(understood by Bigtop::SQL::*, Bigtop::Model::*, and some Bigtop::Control::* modules)

If you are going to generate default id's from sequences, use this to declare the sequence. Give the sequence a name and a block:

sequence address_seq {}

Currently the block must be empty (but it will eventually allow you to specify things like starting value, increment, etc.).

config

(understood by Bigtop::HttpdConf::* and Bigtop::CGI::*)

[ For historical reasons set_vars can be used as a synonym for config. That use is deprecated. ]

This allows you to dump PerlSetVar statements into the root location for your app in your httpd.conf or do the equivalent in your cgi dispatching script. Simply list the name of a variable and its value in each statement (remember to use backquotes):

config {
    dbconn `dbi:Pg:dbname=yourdb` => no_accessor;
    dbuser `some_user`            => no_accessor;

    smtp_host `smtp.example.com`;
}

If you tag the statement with => no_accessor, the controller backend will skip making an accessor for the variable (thus assuming that your framework is handling it). It will also omit the set var from the dir_config or other fishing normally done in the init method generated for the controller.

table

(understood by Bigtop::SQL::*, Bigtop::Model::*, and Bigtop::Control::*)

The general structure of a table is:

table name { }

Inside you can list either statements or field blocks. There are three legal statement at present:

data last_name => Crow, first_name => Phil;

(registered by Bigtop::SQL)

This corresponds directly to an INSERT INTO statement for the given data. You may use as many data statements as you like. Obviously, all fields you name must be defined for the table and your values must be of the proper SQL type. Note that it is usually a bad idea to specify a value for the primary key, in a data statement, when the table has an index.

foreign_display `%last_name, %first_name`;

(registered by Bigtop::Model)

This becomes the user's view of rows from this table when other tables point to them via a foreign_key. Always use backquotes. The formatting is simplistic. Any text, which looks like an ident, abutted against a percent must be a field in the table whose value will go in that spot. Literal percents are allowed at the end of the string or with trailing whitespace or punctuation (except underscore, '_').

model_base_class

(registered by Bigtop::Model)

Each Model backend has a default base class for its models. This overrides that default.

model_base_class Gantry::Utils::AuthCDBI;

not_for

(registered by Bigtop::Parser, understood by Bigtop::Model::* and Bigtop::SQL::*)

Tells one or more backends to skip this table. Choices:

not_for SQL;
not_for Model;
not_for Model, SQL;

For example, you might use this to obtain a model for a table that shouldn't appear in your in schema.* (perhaps the table lives in an external database).

sequence sequence_name;

(registered by Bigtop::SQL understood by Bigtop::SQL::* and Bigtop::Model::*);

This means that the table might use the named sequence, but how it uses it is up to the field blocks (see below). You can only name one sequence per table.

There is only one legal block type:

field name { }

The field block can contain only statements. The legal keywords typically include:

is

(registered and required by Bigtop::SQL)

Allows a comma separated list of SQL descriptors for this field. Choose from:

type (must be first)

This should be a valid SQL type (or something your backend will convert into one) like int4, varchar, etc.

primary_key (can only be used by one field in each table)

(handled by Bigtop::SQL::* and Bigtop::Model::*)

This column is the primary key. Multi-column primary keys are not supported.

assign_by_sequence (also known as auto)

(handled by Bigtop::SQL::* required by Bigtop::Model::Gantry)

This column's default value will be the next value of the sequence for this table. It is a fatal error to include this, unless the table has a sequence statement and that sequence is defined by a sequence block at the app level. All this indirection supports multiple tables sharing a single sequence.

Note that some models rely on auto-generated sequences.

Example field blocks (but see below for more statements):

field id   { is int4, primary_key, auto; }
field name { is varchar; }

label