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.
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 through your browser.
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 an empty stub [not yet implemented].
Expects: nothing
The remaining handlers are all AJAX handlers. They are triggered by GUI user events and send back a plain text representation of the updated abstract syntax tree being edited. Eventually a method will allow the user to save that output back to the disk, but it's not here yet.
Each routine is given a parameter (think keyword) and a new value. Some of them also receive additional data, see below.
do_update_std
The parameter is 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, if I ever get around to writing about them).
The new_value is merely passed to the set_ method, which is responsible for updating the tree properly. Errors are trapped.
do_update_backend
While this is probably not wise, the parameter has the form 'type::backend' referring to 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.
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
Again, the parameter form is bad: 'type::backend::keyword'. If needed, this creates the keyword as a statement in the backend's config block. In any case, it sets the value to the new value passed in (except that it converts 'false' to 0 and anything else to 1).
It uses change_conf to do the actual work.
do_update_conf_bool_controlled
This is just like do_update_conf_bool, but accepts two additional url parameters. These are the values for false and true, in that order.
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'.
If one of the values is the string 'undefined' the statement will be deleted from the backend.
do_update_conf_text
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.
do_update_app_statement
If the new value eq 'undefined' the statement is removed from the app block. Otherwise the statement has its value changed to the new value (the statement is created if needed). Mulitple values should be separated by a comma and a space (yes this prevents Kip Worthington, III. from couting as an author name).
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
Guess what this does. Eventually there will be a way to avoid this step, but for now only file input is acceptable.
HELPER METHODS
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.
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.
input
Accessor to get/set the input file text in memory.
deparsed
Accessor to get/set the deparsed (canonicalized) text of the file.
AUTHOR
Phil Crow, <philcrow2000@yahoo.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.