/ 
Bigtop-0.21
River stage zero No dependents
/ Bigtop::ScriptHelp

NAME

Bigtop::ScriptHelp - A helper modules for command line utilities

SYNOPSIS

#!/usr/bin/perl
use Bigtop::ScriptHelp;

my $default = Bigtop::ScriptHelp->get_minimal_default();
my $tree    = Bigtop::Parser->parse_string( $default );
# ...

my $better_default = Bigtop::ScriptHelp->get_big_default(
        $name, $art
);
my $better_tree    = Bigtop::Parser->parse_string( $better_default );

Bigtop::ScriptHelp->augment_tree( $bigtop_tree, $art );

my $new_field_label = Bigtop::ScriptHelp->default_label( $name );

DESCRIPTION

This module is used by the bigtop and tentmaker scripts. It provides convenience functions for them.

ASCII art

Whenever users are allowed to supply tables, they could just name the tables, but they will probably want to use ASCII art to show their relationships. This section explains those.

Note well: for these to work well, your SQL and Model backends have to understand what to do with them. For instance, the only Model that understands what to do with a many-to-many relationship is GantryDBIxClass.

Each relationship is between a pair of tables. These tables must appear with their relational operator in between them without whitespace. There are four operators which specify three relations:

a->b

Table a has a foreign key pointing to table b, this is a many-to-one relationship from a to b.

b<-a

Table a has a foreign key pointing to table b, this is a one-to-many relationship from b to a.

This is a synonymn, for a->b, except that if the tables have not already been created, the first one listed is created first. This might matter if your SQL backend makes genuine foreign keys and your database won't allow forward references.

a-b

Table a and table b have a one-to-one relationship, each will have columns pointing to the other.

a<->b

Tables a and b have a many-to-many relationship. A third table called a_b will be created for you to join them. The has many relationship in table a will be called bs (not to be taken literally), whilc the has many relationship in table b will be called as. You may use the tentmaker or a text editor to add a names statement to the generated join_table block, to provide alternate names.

METHODS

get_minimal_default

Params: app_name (optional, defaults to Sample)

Returns: a little default bigtop string suitable for initial building. It has everything you need for your app except tables and controllers.

get_big_default

Params: an app name and a list of ascii art table relationships.

Returns: a bigtop file suitable for immediately creating an app and starting it.

augment_tree

Params: a Bigtop::Parser syntax tree (what you got from a parse_* method) and a list of ascii art table relationships

Returns: nothing, but the tree you passed will be updated.

default_label

Params: a new name

Returns: a default label for that name

Example of conversion: if name is birth_date, the label becomes 'Birth Date'.

default_controller

Params: a new table name

Returns: a default label for that table's controller

Example of conversion: if table name is birth_date, the controller becomes 'BirthDate'.

FUNCTIONS

The following functions are meant for internal use, but you might like them too. Don't call them through the class, call them as functions.

parse_ascii_art

Params: a single string (space delimited) of all the ASCII art relationships to be put into the bigtop file and a hash reference of existing tables you don't want to add (optional defaults to {}).

Returns: a single hash reference with these keys:

all_tables - your hash reference updated with the tables in the art.
new_tables - an array reference of tables you need to add.
joiners    - an array reference of join_tables, each element is
             a two element array, each element is one of the
             many-to-many tables.
foreigners - a hash reference keyed by table name storing an array
             of the foreign tables it hold keys for.
valid_ident

Params: a proposed ident

Returns: true if the ident looks good, false otherwise. Note that the regex is not perfect. For instance, it will allow leading numbers.

AUTHOR

Phil Crow, <crow.phil@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2006, 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.