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

FreeBSD Manual Pages

  
 
  

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

NAME
       Bigtop::Keywords	- A central place to describe all bigtop keywords

SYNOPSIS
       In your backend or backend type module:

	   use Bigtop::Keywords;
	   # There is no need to use Bigtop::Parser since it uses you.

	   BEGIN {
	       Bigtop::Parser->add_valid_keywords(
		   Bigtop::Keywords->get_docs_for(
		       $keyword_level,
		       qw( your	keywords here )
		   )
	       );
	   }

       Note that this must be done in a	BEGIN block.

       Or, if you are writing a	documenation tool:

	   my $keyword_for = Bigtop::Keywords->get_full_doc_hash();

DESCRIPTION
       Since many backends need	to use the same	keywords, it eventually	dawned
       on me that a central place to describe would be a good thing.  This is
       that place.  By keeping all the keyword definitions here, all backends
       can share them.	This became especially helpful with the	birth of
       tentmaker.  It wants to consistently tell users about the keywords.

       If you write or modify a	backend	and need new keywords in the process,
       define them here	and send in a patch.  This will	avoid name collisions
       and keep	the tentmaker functioning.  Read on for	how to define the
       keywords.

DEFINING KEYWORDS
       To define a new keyword,	first decide at	what level it will be used.
       That is,	does it	apply inside controller	blocks,	table blocks, or
       somewhere else.	See "KEYWORD LEVELS" for a list	of all the choices.

       Once you	know where your	keyword	should be legal, find its level	among
       the top level keys in the %docs_for in this file.  Inside the hash for
       your level add a	new hash keyed by your keyword name (pick the name
       carefully, changing them	after release is painful).  The	value for your
       new hash	key is itself a	hash.  Here are	the legal keys for the hash
       (all keys are optional unless marked required):

       keyword
	   Required and	must be	the same as the	key for	the hash.  The
	   official name of the	keyword.  The user must	type this to use the
	   keyword (or get a tool to do	it for her).

       label
	   Required for	tentmaker.  The	name tentmaker shows its users for
	   this	keyword.  Traditionally, this is just the keyword beautified
	   so the label	for keyword 'contact_us' is 'Contact Us'.

       descr
	   tentmaker shows this	next to	the input box for the keyword.	Feel
	   free	to use a bit of	html in	the value for descr.  For instance,
	   when	providing examples, surround them with pre tags.

       sort_order
	   tentmaker uses this to order	the statements within their category.
	   A simple numeric sort is done on these values.

       multiple
	   Indicates that the keyword can accept a list	of values (or pairs of
	   them	if its type is pair).  This only applies to types text,	pair,
	   and select.	The others ignore it.  See below for information about
	   types.

       repeatable
	   Indicates that the statement	can be repeated.  Currently only data
	   statements may be repeated to any useful effect.  To	contrast,
	   multiple means that the single statement can	take many values in a
	   comma separated list, while repeatable means	that the keyword
	   itself may be used many times each timw with	one or more values.
	   Again, only data statements are repeatble.

       pair_labels
	   You probably	want to	use this key if	your keyword's type is pair.
	   A two element array reference with the labels to display over the
	   two input columns of	keywords whose type is pair.  Example:

	       pair_labels => [	'Name',	'Email Address'	],

       pair_required
	   Required for	keywords of type pair.

	   Use this key	for all	pair keywords.	Make it	true if	a pair is
	   always required for the keyword and false if	items may have only
	   the first half of a pair (like author pairs where the name is in
	   the hash key	position and the optional email	address	is in the
	   value position).

	   Look	for keywords of	type pair for examples.

       options
	   An array reference of hashes	describing the options for the
	   keyword.  Use this only for keywords	of type	select.	 Example:

	       options => [
		   { label => 'User Sees This',	value => 'internal_value' },
		   { label => 'Hourly',		value => '24'		  },
	       ],

	   If you don't	want a default,	you should include a hash like this:

	       { label => '-- Choose One --', value => 'undefined' },

	   The value 'undefined' is special to JavaScript.  So,	tentmaker will
	   unset the value if you the user selects '-- Choose One --'.

       quick_label
	   Only	applies	to field keywords.  Indicates that this	keyword	should
	   appear in the Field Quick Edit box in tentmaker.  Fields appear
	   there in the	same order they	appear in the full edit	expanding box.
	   That	order is controlled by the sort_order (see below).

	   Quick editing does not allow	pairs or multiples.  You can set a
	   quick_label for a multiple entry keyword, but the quick edit	will
	   only	update the first one.  If the user changes the one in the
	   quick edit, only that one will be preserved.	 Pairs will not	work
	   in the quick	edit box.

       refresh
	   Unused and ignored.

	   This	used to	indicate that a	field keyword update should trigger a
	   full	page refresh.  There is	now javascript support to update the
	   DOM no matter what happens and it should stay that way.  Temptation
	   to set this flag indicates a	lack of	javascript courage.

       urgency
	   Indicates how useful	the keyword is.	 Most have urgency 0, they
	   show	up white on the	screen.	 tentmaker currently understands these
	   urgency values:

	     value  screen color  implied meaning
	     -----------------------------------------------------------------
	       10   red		  required by someone
		5   yellow	  this or a related keyword is likely required
		3   green	  many people use this regularly
		1   blue-green	  many people use this at least	occasionally
		0   white	  less frequently used

	   Note	that only values from the above	list are understood by
	   tentmaker.  If you use other	values,	they will be treated as	zero.

       method_types
	   This	tells tentmaker	which method types understand a	keyword.  It
	   is a	hash.  They key	are individual method types.  The values are
	   1.  There is	one special key	'all'.	If it has a true value,	then
	   the keyword is available to all methods regardless of type.

       field_type
	   Not yet used.  Meant	to tell	tentmaker that a field keyword only
	   applies to a	certain	html_form_type.

       type
	   Essentially the tentmaker html form element for the keyword.	 Note
	   that	literal	keywords do not	need to	set this key (and if they do,
	   it will be ignored).	 They always get a textarea for	their input.
	   For other keyword levels choose from	these input types (in order by
	   utility):

	   text
	       This is the most	common type.  It tells tentmaker to use	a text
	       input box for the keyword.

	   boolean
	       Indicates that the value	is either 1 or 0 and tells tentmaker
	       to use a	checkbox for the keyword.

	   pair
	       Indicates that the keyword admits either	single values or
	       pairs.  A pair is two things separated by =>, like

		   name	=> `email@example.com`

	       You want	to use the pair_labels and pair_required keys if you
	       use this	type, trust me.

	   textarea
	       Indicates that typical values for this keyword are large	text
	       blocks, so tentmaker should use a textarea for their input.

	   select
	       Indicates that only certain values are legal so tentmaker users
	       should pick them	from a list.  You must use the options key
	       with this type.	You might also want to use the multiple	key.

	   deprecated
	       Tells tentmaker not to show this	keyword, which is usually an
	       archaic spelling	for a keyword.

   KEYWORD LEVELS
       There are several levels	in the parse tree where	keywords may appear.
       These are the levels:

       config
	   Keywords in the bigtop level	config block (where the	backends are
	   defined).

       app Keywords at the top level of	the bigtop app block.

       app_literal
	   The legal names of literal statements at the	bigtop app block
	   level.

       table
	   Keywords at the top level of	table blocks.

       field
	   Keywords in field blocks (inside table blocks).

       controller
	   Keywords at the top level of	controller blocks.

       controller_literal
	   The legal names of literal statements at the	controller block
	   level.

       method
	   Keywords in method blocks (inside controller	blocks).

       There are no other valid	keyword	locations in the current grammar.
       Adding new levels will require substantial change to the	grammar, the
       parser, and all the backends.  Thus, such changes are extremely
       unlikely	(though	some are in the	back of	my mind).

METHODS
       There is	only one method	defined	in this	module.	 Use it	as shown in
       the SYNOPSIS above.

       get_docs_for
	   Parameters:

	       keyword_level
	       list of keywords

	   Returns:

	   an array whose first	element	is the keyword_level and whose
	   remaining elements are keyword hashes.  This	return is designed for
	   direct passing to the add_valid_keywords method of Bigtop::Parser

       get_full_doc_hash
	   Parameters: none

	   Returns: the	entire internal	hash representation of all the
	   keywords.  This is useful for automated tools, like
	   "scripts/vimsyntax" that builds the vim syntax file.

AUTHOR
       Phil Crow <crow.phil@gmail.com>

COPYRIGHT and LICENSE
       Copyright (C) 2006-7 by 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.24.1			  2017-07-03		   Bigtop::Keywords(3)

NAME | SYNOPSIS | DESCRIPTION | DEFINING KEYWORDS | METHODS | AUTHOR | COPYRIGHT and LICENSE

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

home | help