Philip Crow > Bigtop > Bigtop::TentMaker

Download:
Bigtop-0.38.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  1
View/Report Bugs
Source  

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

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.

do_update_std

This method only serves to update the app name. It does that by calling set_appname on the AST.

do_update_top_config_text

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.

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_controller_statement_pair

Directly calls do_update_subblock_statement_pair, 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_table_statement_pair

Directly calls do_update_subblock_statement_pair specifying type table and passing on all parameters.

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. 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.

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. Documentation scripts are welcome to call this method to kick start a doc pull from the backends. They should then call:

get_backends

Accessor which returns the internal hash of all backends and their backend block keywords.

read_file

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.

HELPER METHODS ^

new

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.

set_testing

Pass this a true value to turn off html dumps from app block creation for testing.

show_idents

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.

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 almost 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.

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. Any future request for the tree or input text will trigger reading of the file.

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-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.

syntax highlighting: