Bigtop::TentMaker - A Gantry App to Help You Code Bigtop Files
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.
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.
Bigtop::Docs::TentTut
Bigtop::Docs::TentRef
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.
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
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.
Kills the running tentmaker.
Params: None
Returns: undef
Note that the script usually dies before it can return a good AJAX response to the browser, which results in one Javascript error in the browser.
This method only serves to update the app name. It does that by calling set_appname on the AST.
This method is a generic accessor for top level config block statements.
Parameters:
the top level config statement name the new value to give it
If the new value is 'undefined' (the string), the statement will be cleared.
This method handles backend selection/deselection.
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.
Allows toggling for boolean backend block keywords.
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.
Like do_update_conf_bool, but allows control over what true and false mean.
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.
Updates backend block statements which have string values.
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.
Creates/updates the value of app level statements, when the value is text.
statement_keyword new_value
It uses set_app_statement on the application subtree in Bigtop::Parser.
Like do_update_app_statement_text, but for when the value is boolean.
Use the word 'false' to delete the statement.
Somewhat like do_update_app_statement_text, but for when the value takes one or more pairs.
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.
Removes a statement from the app level config block.
Creates/updates an app level config statement.
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.
For exisiting app level config statements, changes the accessor flag.
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.
Changes the name of a named block.
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.
Makes a new app level block.
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.
Makes a new block inside a table or controller.
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.
Removes a block from the AST.
ident
The front end is responsible for any user confirmation popups.
It uses delete_block on the AST.
Changes the is type for blocks which acept those.
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.
Creates/updates a statement in a block.
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).
Directly calls do_update_block_statement_text, specifying type controller.
If value eq 'true', the statement is made true, otherwise it will be removed.
Directly calls do_update_subblock_statement_pair, specifying type controller.
Updates statements at many levels of the tree, including table, join_table, controller, field, and method blocks.
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.
Directly calls do_update_block_statement_text specifying type table.
Directly calls do_update_subblock_statement_pair specifying type table and passing on all parameters.
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.
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.'
Creates/updates boolean statements in field blocks.
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.
Immediately calls do_update_subblock_statement_pair, specifying type field.
Immediately calls do_update_subblock_statement_text, specifying type field.
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.)
Updates the text of a literal.
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.
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.
Directly calls do_update_subblock_statement_pair, specifying type method.
Directly calls do_update_subblock_statement_text, specifying type method.
Supports all pair updates in subblocks.
type ident::keyword
The values are received from the query string:
keys=key1][key2&values=val1][val2
It uses change_statement on the AST.
Supports all single value updates on subblock statements (and some block statements too).
block_type block_ident::keyword new_value
It uses do_update_statement.
Not yet called by the front end.
Exchanges the position of two app level blocks.
ident_to_move ident_to_put_it_after
It uses move_block on the AST.
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. In any case, since I learned to compile the grammar into a module, the times involved are no longer significant.
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 raw input 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.
The backends hash is used internally to know which backends are available, whether they are in use, and what statements they support. Documentation scripts are welcome to call this method to kick start a doc pull from the backends. They should then call:
Accessor which returns the internal hash of all backends and their backend block keywords.
Reads the input file. If the user didn't supply a file, asks Bigtop::ScriptHelp to generate a starting point using the requested (or default) style.
Used by tests to gain a pseudo-instance through which to call helper methods. For instance, some tests call methods on this instance to turn templating on an off. See t/tentmaker/*.t for examples.
Pass this a true value to turn off html dumps from app block creation for testing.
Used during test development 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). This saves counting created items on your fingers.
This is a gantry init method. It fishes the file name from the site object.
Builds an array whose elements are hashes describing each config statement in the app level config block.
Used by almost all AJAX handlers to deparse the updated tree and return it to the client.
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.
Used by all the do_update_conf_* methods to actually change the config portion of the AST.
Used by do_update_backend to remove a backend from the AST.
Used by do_update_backend to add a backend from the AST.
Keeps the backends hash up to date.
Accessor to get/set the name of the input file. Setting it blows the cache of other accessible values.
Returns the name of the input file given on the command line.
Stores the input file name during startup. Calling this blows the cashed deparsed bigtop source code and abstarct syntax tree. Any future request for the tree or input text will trigger reading of the file.
Returns the Bigtop abstract syntax tree.
Accessor to get/set the input file text in memory.
Accessor to get/set the deparsed (canonicalized) text of the file.
Returns 1 if there have been changes since the last save, 0 otherwise.
Phil Crow, <crow.phil@gmail.com>
Copyright (C) 2006-7, 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.
To install Bigtop, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bigtop
CPAN shell
perl -MCPAN -e shell install Bigtop
For more information on module installation, please visit the detailed CPAN module installation guide.