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

FreeBSD Manual Pages

  
 
  

home | help
Bigtop::TentMaker(3)  User Contributed Perl Documentation Bigtop::TentMaker(3)

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.

perl v5.32.0			  2020-08-29		  Bigtop::TentMaker(3)

NAME | SYNOPSIS | DESCRIPTION | HANDLERS | LAUNCH METHODS | HELPER METHODS | AUTHOR | COPYRIGHT AND LICENSE

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

home | help