NAME

Bigtop::TentMaker - A Gantry App to Help You Code Bigtop Files

SYNOPSIS

Start the tentmaker:

tentmaker [ --port=8192 ] [ file ]

Point your browser to the address it prints. Consult the POD for the tentmaker script for other command line options.

DESCRIPTION

Bigtop is a language for describing web applications. The Bigtop language is fairly complete, in that it lets you describe complex apps, but that means it is not so small. This module (and the tentmaker script which drives it) helps you get the syntax right using your browser.

Unless you need to work on tentmaker internals, you probably want to read the POD for the tentmaker script instead of the rest of this documentation. You might also want to look at Bigtop::Docs::TentTut and/or Bigtop::Docs::TentRef.

HANDLERS

There are three types of methods in this module: handlers called by browser action, methods called by the driving script during launch, and methods which help the others. This section discusses the handlers. See below for details on the other types.

do_main

This is the main handler users hit to initially load the page. It sends them the tenter.tt template populated with data from the file given on the command line. If no file is given, it gives them a small default bigtop as a starting point.

Expects: nothing

do_save

Writes current abstract syntax tree back to the disk.

Params:

full_path

Returns:

stash controller data saying either "Saved..." or "Couldn't write...'

The remaining handlers are all AJAX handlers. They are triggered by GUI events and return the plain text representation of the updated abstract syntax tree being edited.

Each routine is given a parameter (think keyword) and a new value. Some of them also receive additional data, see below. Errors are trapped and reported as warnings on the server side.

do_server_stop

Kills the running tentmaker.

Params: None

Returns: undef

do_update_std

This method is a facade for top level setters in Bigtop::Parser.

Parameters:

the set action to call
the new value to give it

The set action becomes the suffix of the name of a method the tree responds to. The full name is "set_$parameter" (see Bigtop::Parser for details of these methods).

The new_value is merely passed to the set_ method, which is responsible for updating the tree properly.

do_update_backend

This method handles backend selection/deselection.

Params:

backend_type::backend
new_value

The backend_type::backend must be a module in the Bigtop::Backend:: namespace.

The new value is a string (repeat: it is a string). If the string eq 'false', the backend is dropped from the config block of the file. Otherwise, it is added to the list.

Note well: When a config is dropped, all of the statements in its config block are LOST. This creates a disappointing end user reality. If you uncheck a backend box by mistake, after you recheck it, you must go focus and defocus on all text backend statements and check and uncheck all checkboxes. This is bad.

do_update_conf_bool

Allows toggling for boolean backend block keywords.

Parameters:

type::backend::keyword
new_value

As in do_update_backend, the new value is a string 'false' means the user unchecked the box, anything else means she checked it.

It uses change_conf to do the actual work.

do_update_conf_bool_controlled

Like do_update_conf_bool, but allows control over what true and false mean.

Parameters:

type::backend::keyword
new_value
false_value
true_value

If the new value eq 'false', the false value is assigned, otherwise the true value is used. This facilitates statements like the Init::Std 'Changes no_gen', where the value of the statement is not zero or one. In that case, the value should be undef or the string no_gen.

If one of the values is the string 'undef' or 'undefined' the statement will be deleted from the backend.

It uses change_conf to do the actual work.

do_update_conf_text

Updates backend block statements which have string values.

Parameters:

type::backend::keyword
new_value

This is like do_update_conf_bool, except that the new value is used as the statement value. If the value is false, the statement is removed from the backend's config block.

It uses change_conf to do the actual work.

do_update_app_statement_text

Creates/updates the value of app level statements, when the value is text.

Parameters:

statement_keyword
new_value

It uses set_app_statement on the application subtree in Bigtop::Parser.

do_update_app_statement_bool

Like do_update_app_statement_text, but for when the value is boolean.

Parameters:

statement_keyword
new_value

Use the word 'false' to delete the statement.

It uses set_app_statement on the application subtree in Bigtop::Parser.

do_update_app_statement_pair

Somewhat like do_update_app_statement_text, but for when the value takes one or more pairs.

Parameters:

keyword

Query string params:

keys=key1][key2][key3&values=value1][value2][value3

Note that the key/value pairs are passed in the query string.

If there are no keys, the statement is removed.

It uses set_app_statement_pairs on the application subtree in Bigtop::Parser.

do_delete_app_config

Removes a statement from the app level config block.

Params:

keyword

do_update_app_conf_statement

Creates/updates an app level config statement.

Params:

keyword
value
accessor

keyword is the name of the config statement (which is entirely up to the user, except that it must be a valid ident).

value is the completely arbitrary value of the statement (except that it can't have embedded backticks).

accessor is only used if the statement is new. In that case, this is the value for the accessor check box. If it is set, an accessor will be made for the statement, otherwise we assume the framework is handling it.

do_update_app_conf_accessor

For exisiting app level config statements, changes the accessor flag.

Params:

keyword
value

keyword is the name of that config statement.

value is either the string 'false' or anything else. If the value eq 'false', the accessor flag is removed. Otherwise, it is set.

do_update_name

Changes the name of a named block.

Params:

type::ident
new_value

Each nameable block in the Bigtop AST has a unique ident. Calling this with the type of the block, that ident, and a new value changes its name.

do_create_app_block

Makes a new app level block.

Params:

type::name
subtype

The type can be sequence, table, join_table, or controller. The name must be a valid ident. If they block's type understands a subtype, include it as a second, separate, parameter. Only controllers have types and they are: AutoCRUD, CRUD, or stub.

It uses create_block on the AST.

do_create_subblock

Makes a new block inside a table or controller.

Params:

parent_type::parent_ident::type::name
subtype

The parent type can be table or controller. The type can be field (for tables) or method (for controllers). The name must be a valid ident. Methods must have subtypes. Choose from: AutoCRUD_form, CRUD_form, or main_listing.

It uses create_subblock on the AST.

do_delete_block

Removes a block from the AST.

Params:

ident

The front end is responsible for any user confirmation popups.

It uses delete_block on the AST.

do_type_change

Changes the is type for blocks which acept those.

Params:

ident
new_type

new_type must be a string naming the new type.

Applies to controllers and methods.

It uses type_change on the AST.

do_update_block_statement_text

Creates/updates a statement in a block.

Params:

block_type
ident::keyword
new_value

block_type is table, join_table, or controller.

If new_value is false, the statement will be removed.

It uses do_update_statement (see below).

do_update_controller_statement_bool

Directly calls do_update_block_statement_text, specifying type controller.

If value eq 'true', the statement is made true, otherwise it will be removed.

do_update_controller_statement_text

Directly calls do_update_block_statement_text, specifying type controller.

do_update_statement

Updates statements at many levels of the tree, including table, join_table, controller, field, and method blocks.

Params:

block_type
block_ident
keyword
new_value

It uses either change_statement or remove_statement.

I don't think this is called by the templates or their javascript.

do_update_table_statement_text

Directly calls do_update_block_statement_text specifying type table.

do_update_data_statement

Tells the tree to update or add a data statement to an existing table. Only one argument of the data statement is ever updated. This corresponds to the single box the user updated in the front end.

Params: statement_id new_value

The statement id must be of the form:

data_value::ident_9::ident_4::2

where data_value is literal (and is discarded), ident_9 is the table's ident, ident_4 is the ident of the field whose value should become new_value, and 2 is the number of the data statement. The data statement number starts at 1 and is the order of appearance of the statement to change.

If the new_value is false, the item will be removed from the data statement. Yes, this is a problem is you want a zero.

do_table_reset_bool

Tells the tree to set one keyword to true or false for all of its fields.

Params: table_ident keyword raw_value

The raw_value is a string, either 'true' or 'false.'

do_update_field_statement_bool

Creates/updates boolean statements in field blocks.

Params:

keyword
new_value

If new_value eq 'true' the statement will be made true, otherwise it will be removed.

It uses do_update_subblock_statement_text.

do_update_field_statement_pair

Immediately calls do_update_subblock_statement_pair, specifying type field.

do_update_field_statement_text

Immediately calls do_update_subblock_statement_text, specifying type field.

do_update_join_table_statement_pair

Immediately calls do_update_subblock_statement_pair, specifying type join_table. (Astute readers will note that join_table is a block not a subblock, the the necessary code is the same for both. Some refactoring is probably in order.)

do_update_literal

Updates the text of a literal.

Params:

ident
new_value

new_value can have any charactes except backquotes.

You must create and delete blocks with direct calls to do_create_app_block and do_delete_block.

It directly calls walk_postorder with 'change_literal' as the action.

do_update_method_statement_bool

Params:

keyword
new_value

If new_value eq 'true' boolean is made true, otherwise the statement will be removed.

It calls do_update_subblock_statement_text, specifying type method.

do_update_method_statement_pair

Directly calls do_update_subblock_statement_pair, specifying type method.

do_update_method_statement_text

Directly calls do_update_subblock_statement_text, specifying type method.

do_update_subblock_statement_pair

Supports all pair updates in subblocks.

Params:

type
ident::keyword

The values are received from the query string:

keys=key1][key2&values=val1][val2

It uses change_statement on the AST.

do_update_subblock_statement_text

Supports all single value updates on subblock statements (and some block statements too).

Params:

block_type
block_ident::keyword
new_value

It uses do_update_statement.

do_move_block_after

Not yet called by the front end.

Exchanges the position of two app level blocks.

Params:

ident_to_move
ident_to_put_it_after

It uses move_block on the AST.

LAUNCH METHODS

take_performance_hit

This method allows the server to take the hit of compiling Bigtop::Parser and initially parsing the input file with it, before declaring that the server is up and available. I no longer think this is a good idea, but for now it is reality.

It builds a list of all the backends available on the system (by walking @INC looking for things in the Bigtop::Backend:: namespace). It also reads the file given to it and parses that into a bigtop AST. Then it deparses that to produce the initial presented in the browser. Think of this as canonicallizing the input file for presentation. Finally, it builds the statements hash, filling it with docs from all the keywords that all of the backends register.

This method takes at least 5 seconds, even though I haven't profiled it, I believe most of that is spent compiling the grammar. Subsequent operations on the tree are subsecond.

build_backend_list

The backends hash is used internally to know which backends are available, whether they are in use, and what statements they support.

read_file

Reads the input file. If the user didn't supply a file, asks Bigtop::ScriptHelp to generate a minimal starting point.

HELPER METHODS

new

Used by tests to gain a pseudo-instance through which to call helper methods. They could call them through the class, but naming an instance saves typing.

show_idents

Used by tests to get a dump of all the idents in the current tree. You get Data::Dumper output of an array of the idents. Each element is an array listing the type, name, and ident for one tree node. All nodes with idents appear in the output, but the order is a bit odd (it is depth first traversal order).

init

This is a gantry init method. It fishes the file name from the site object.

compile_app_configs

Builds an array whose elements are hashes describing each config statement in the app level config block.

complete_update

Used by all AJAX handlers to deparse the updated tree and return it to the client.

unescape

Typical routine to turn %.. into a proper character. Takes a list which it will join with slashes to undo HTTP::Server::Simple's overly aggressive unescaping.

change_conf

Used by all the do_update_conf_* methods to actually change the config portion of the AST.

drop_backend

Used by do_update_backend to remove a backend from the AST.

add_backend

Used by do_update_backend to add a backend from the AST.

update_backends

Keeps the backends hash up to date.

_get_backend_block_statements

Helps update_backends.

file

Accessor to get/set the name of the input file. Setting it blows the cache of other accessible values.

get_file

Returns the name of the input file given on the command line.

set_file

Stores the input file name during startup. Calling this blows the cashed deparsed bigtop source code and abstarct syntax tree.

get_tree

Returns the Bigtop abstract syntax tree.

input

Accessor to get/set the input file text in memory.

deparsed

Accessor to get/set the deparsed (canonicalized) text of the file.

dirty

Returns 1 if there have been changes since the last save, 0 otherwise.

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.

cpanm Bigtop

perl -MCPAN -e shell
install Bigtop