Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bigtop::ScriptHelp::StUser:Contributed)Bigtop::ScriptHelp::Style::Kickstart(3)

NAME
       Bigtop::ScriptHelp::Style::Kickstart - handles kickstart	syntax for
       scripts

SYNOPSIS
       Most users use this module as the default style for the bigtop and
       tentmaker scripts:

	   bigtop -n AppName [kickstart]

       See "KICKSTART SYNTAX" below for	details, but note that kickstart could
       be a file whose contents	are in kickstart syntax.

       If you are writing a script that	wants to leverage styles do this:

	   use Bigtop::ScriptHelp::Style;

	   my $style = Bigtop::ScriptHelp::Style->get_style( 'Kickstart' );

	   # then pass $style to methods of Bigtop::ScriptHelp

DESCRIPTION
       See "Bigtop::ScriptHelp::Style" for a description of what this module
       must do in general.

SUBCLASSING
       As of version 0.33, this	module has been	revised	to make	subclassing
       easier.	This allows you	complete control over what columns are
       generated by default.  All you need to do is subclass this module and
       implement two methods: "get_default_base_columns" and
       "get_default_filler_columns".  But, you can rely	on this	module to
       handle the original kickstart syntax.

METHODS
       get_columns
	   This	method is for internal use, but	is exposed so subclasses don't
	   have	to implement it.  It specifies that definitions	like

	       tablename(col,col2:int)

	   will	be parsed with "parse_columns" (see below).

       get_db_layout
	   This	method does not	use standard in.  Instead, it expects
	   kickstart syntax.  See "KICKSTART SYNTAX" below.

       get_default_base_columns
	   Subclasses override this method to control which columns are
	   created by default.	Note that if a user explicitly declares	a
	   column in the parentheses of	a table	definition, the	corresponding
	   column in this collection is	ignored.

	   Returns a hash with two keys: "is_normal_default" and
	   "normal_defaults".  "is_normal_defaults" is a hash keyed by the
	   name	of each	column with two	keys: "where" (either front or rear)
	   and "typees"	(an anonymous array of Bigtop "is" values, usually
	   these are SQL types or other	column definition phrases).
	   "normal_defaults" is	an anonymous array of column names, they must
	   correspond to keys in "is_normal_defaults".	The order of the
	   columns in the array	controls when they are added to	the list of
	   columns.  But, remember that	"where"	decides	whether	to unshift or
	   push	them into the list.

	   For example,	the method in this module does this:

	       return {
		   is_normal_default =>	{
		       id	=> {
			   where => 'front',
			   types => [ 'int4', 'primary_key', 'auto' ]
		       },
		       created	=> {
			   where => 'rear',
			   types => [ 'datetime' ],
		       },
		       modified	=> {
			   where => 'rear',
			   types => [ 'datetime' ],
		       },
		   },
		   normal_defaults => [
		       qw( id created modified )
		   ],
	       };

       get_default_filler_columns
	   Suppose a table is in the kickstart file, but has no	column
	   definitions.	 It will get columns.  First, this method returns a
	   string which	is the default art for the table.  Second, as with all
	   tables, columns returned by "get_default_base_columns" are added.

	   The method in this module returns:

	       return 'ident,description';

	   If you return the empty string, no filler columns will be added to
	   your	tables.

       parse_columns
	   This	method is exposed so subclasses	don't have to implement	it.
	   It receives a kickstart art string and parses it into an anonymous
	   array of columns.  Each element in the array	is a hash with keys
	   "name" (the name of the SQL column) and "types" (an anonymous hash
	   of Bigtop "is" values, which	are an SQL type	and a list of other
	   column definition phrases).	There are other	keys: "default"	and
	   "optional".	These are used when the	art includes "=" or "+".

       print_instructions
	   Called by bigtop script when	it makes a new application containing
	   table definitions (you used art with	this style).  Prints
	   instructions	on how to start	the development	application using
	   sqlite.

       help_pg
	   Revises the instructions from "print_instructions" so they are good
	   for PostgreSQL.

       help_mysql
	   Revises the instructions from "print_instructions" so they are good
	   for mysql.

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.

       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:

	   tentmaker -a	docs/app.bigtop	kickstart_file

       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:

	   +-----------+       +----------+
	   |	job    |<------| position |
	   +-----------+       +----------+
		 ^
		 |
	   +-----------+       +----------+
	   | job_skill |------>|  skill	  |
	   +-----------+       +----------+

       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.

       Here's how to specify this data model with bigtop kickstart syntax:

	   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.

       The same	kickstart can be used with --new and --add for both bigtop and
       tentmaker scripts.

       There are four kickstart	table relationship 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.

       <- or *>
	   The second table has	a foreign key pointing to the first.

	   The *> form is useful if you	want to	read the relationship with the
	   phrase 'has-many' as	in

	       book*>chapter

	   Each	book has many chapters.	 Instead of

	       book<-chapter

	   Each	chapter	belongs	to a book.  But, both forms are	equivalent.

       -> or <*
	   The first table has a foreign key pointing to the second.  This is
	   really a convenience	synonymn for <-.

	   Note	that tables will appear	in the generated SQL 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.

       -   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 SQL which is unlikely	to load	well due to foreign key
	   forward references.

   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.

       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.

       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:

	   bigtop -n App 'family(name,+phone)<-child(name,birth_day:date)'

       By default all columns will have	type varchar (but note that SQL
       backends	translate that into a valid string type	for each supported
       database, 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.

       Do not include foreign key columns in the list.	They will be generated
       based on	the relationship punctuation between the tables.

       The phone column	in the family table has	a leading plus sign, and will
       therefore be optional on	the HTML form.

       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:

	   bigtop -a docs/app.bigtop '
	       anniversary(anniversary:date,gift_pref=money)<-family'

       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 HTML forms of 'money.'  Finally,	a new foreign key will
       be added	to the existing	family table pointing to the anniversary
       table.

       You may find it easier to supply	the kickstart text by first specifying
       the relationships without including the columns,	then defining the
       columns later:

	   tentmaker -n	App \
	   'child->family anniversary->family
	       child(name,birth_day:date)
	       family(name,+phone)
	       anniversary(anniversary:date,gift_pref=money)'

       You may mention a table as many times as	you like, but only define its
       columns once.

       Finally,	as mentioned in	the SYNOPSIS, and described in more detail
       below (see "KICKSTART FILES"), you may put the kickstart	in a file and
       supply the file name on the command line:

	   tentmaker -n	App app.kickstart

       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.

   FORMAL SUMMARY
       Here is the formal syntax for each table	definition:

	   name[(COL_DEF[,COL_DEF...])]

       I'm following the convention that brackets enclose optional elements.
       Everything else appears as is, or is defined below.

       Where name is a valid SQL table name and	COL_DEF	is as follows:

	   [+]col_name[:TYPE_INFO][=default]

       Where plus makes	the HTML form field for	the column optional, col_name
       is a valid SQL column name, and all defaults are	literal	strings	(they
       will be quoted in SQL).	If you need more interesting defaults, edit
       the bigtop file after it	is updated.  TYPE_INFO is a colon separated
       list of column declaration words.

       Suppose you want	this column definition:

	   state int4 NOT NULL DEFAULT 4,

       Say this:

	   state:int4:NOT:NULL=4

   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:

	   bigtop -n NewApp file.kickstart

       Unfortunately, you cannot currently pipe	to bigtop or tentmaker,	they
       do not read from	standard in.

       Here is an example kickstart file for a blogging	application:

	   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

       Note again that spaces are not allowed in column	definition lists,
       since whitespace	is the separator of table and table relationship
       entries.

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

COPYRIGHT AND LICENSE
       Copyright (C) 2007, 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.

perl v5.24.1			  2017-Bigtop::ScriptHelp::Style::Kickstart(3)

NAME | SYNOPSIS | DESCRIPTION | SUBCLASSING | METHODS | KICKSTART SYNTAX | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bigtop::ScriptHelp::Style::Kickstart&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help