tepam(3tcl)					   Tcl's Enhanced Procedure and Argument Manager				       tepam(3tcl)

__________________________________________________________________________________________________________________________________________________

NAME

       tepam - An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager

DESCRIPTION

       This  document  is an informal introduction into version 0.2 of TEPAM, the Tcl's Enhanced Procedure and Argument Manager. Detailed informa-
       tion to the TEPAM package is provided in the tepam::procedure and tepam::argument_dialogbox reference manuals.

OVERVIEW

       This package provides a new Tcl procedure declaration syntax that simplifies the implementation of procedure subcommands and  the  handling
       of  the different types of procedure arguments like flags or switches, options, unnamed arguments, optional and mandatory options and argu-
       ments, default values, etc. Procedure declarations can be enriched with detailed information about the procedure and  its  arguments.  This
       information is used later for the following purposes:

       First  of  all,	an argument manager that is automatically added to a procedure implemented with TEPAM checks the argument types and values
       before the procedure body is executed. Then, the information is used to generate help and usage texts if requested, or  to  generate  clear
       error  message  in  case  an argument validation fails. The information also allows generating automatically graphical forms that allows an
       interactive definition of all arguments, in case a procedure is called interactively. And finally, the additional information  helps  self-
       commenting in a clean way the declaration of a procedure and of all its arguments.

       The  graphical form generator that creates the necessary argument specification forms for the interactive procedure calls is also available
       for other purposes than for procedure argument specifications. It allows creating code efficiently complex parameter entry forms  that  are
       usable independently from TEPAM's new procedure definition feature.

       Here is a short overview about all major TEPAM features:

       o      New self-documenting procedure declaration syntax: The additional information to declare properly a procedure has not to be provided
	      with additional statements, but can be added in a natural syntax directly into the procedure header.

       o      Easy way to specify subcommands: A subcommand is declared like a procedure, simply with a procedure name composed  by  a	base  name
	      followed by a subcommand name. Sub-subcommands are created identically using simply procedure names composed by 3 words.

       o      Flexible	usage of flags (switches), options (named arguments) and unnamed arguments. Option names are optionally automatically com-
	      pleted.

       o      Support for  default  values,  mandatory/optional  options  and  arguments,  choice  lists,  valid  value  ranges,  multiple  usable
	      options/arguments.

       o      Choice of a named arguments first, unnamed arguments later procedure calling style (typical for Tcl commands) or of an unnamed argu-
	      ments first, named arguments later procedure calling style (typical for Tk commands).

       o      In case the named arguments first, unnamed arguments later style (Tcl) is selected:  Clear separation between options and  arguments
	      via the "--" flag. The unnamed arguments can optionally be accessed as options (named arguments).

       o      Automatic type and value check before the procedure body is executed, taking into account validation ranges, choice lists and custom
	      validation commands. Generation of clear error message if necessary.

       o      Many predefined types exist (integer, boolean, double, color, file, font, ...). Other  application  specific  types  can	easily	be
	      added.

       o      Automatic help and usage text generation when a procedure is called with the -help flag.

       o      Automatic generation of an interactive argument definition form, in case a procedure is called with the -interactive flag.

       o      Powerful and code efficient generation of complex parameter definition forms.

PROCEDURE DECLARATION

       TEPAM's	procedure  declaration syntax is simple and self-explaining. Instead of declaring a procedure with the Tcl key word proc, a proce-
       dure is declared with the TEPAM command procedure which takes as proc also 3 arguments: The procedure name, the procedure  header  and  the
       procedure body.

       The following example declares the subcommand message of the procedure display. This command has several named and unnamed arguments:

	      tepam::procedure {display message} {
		 -return	    -
		 -short_description "Displays a simple message box"
		 -description	    "This procedure allows displaying a configurable message box.
		 -args {
		    {-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
		    {-font -type font -default {Arial 10 italic} -description "Message text font"}
		    {-level -type integer -optional -range {1 10} -description "Message level"}
		    {-fg -type color -default black -description "Message color"}
		    {-bg -type color -optional -description "Background color"}
		    {-no_border -type none -description "Use a splash window style (no border)"}
		    {-log_file -type file -optional -description "Optional message log file"}
		    {text -type string -multiple -description "Multiple text lines to display"}
		 }
	      } {
		 puts "display message:"
		 foreach var {mtype font level fg bg no_border log_file text} {
		    if {[info exists $var]} {
		       puts  "	$var=[set $var]"
		    }
		 }
	      }
       When  a	procedure  that  has been declared in this way is called, the TEPAM argument manager is automatically invoked before the procedure
       body is executed. The argument manager parses the provided arguments, validates them, completes them eventually with some  default  values,
       and makes them finally available to the procedure body as local variables. In case an argument is missing or has a wrong type, the argument
       manager generates an error message that explains the reason for the error.

       As the example above shows, the TEPAM command procedure accepts subcommand definitions as procedure name  and  allows  defining	much  more
       information  than  just	the argument list inside the procedure header. The procedure body on the other hand is identical between a command
       declared with proc or with procedure.

       The procedure header allows defining in addition to the arguments some procedure attributes, like a description, information concerning the
       return value, etc. This information is basically used for the automatic generation of comprehensive help and usage texts.

       A  list	of  argument  definition  statements  assigned to the -args argument is defining the procedure arguments. Each argument definition
       statement starts with the argument name, optionally followed by some argument attributes.

       Three types of arguments can be defined: Unnamed arguments, named arguments and flags. The distinction between the named and unnamed  argu-
       ments  is made by the first argument name character which is simply "-" for named arguments. Flags are defined as named argument that has a
       type set to none.

       Named and unnamed arguments are mandatory, unless they are declared with the -optional flag and unless they have a default value  specified
       with  the  -default  option.  Named  arguments and the last unnamed argument can have the attribute -multiple, which means that they can be
       defined multiple times. The expected argument data type is specified with the -type option. TEPAM defines a  large  set	of  standard  data
       types which can easily be completed with application specific data types.

       The  argument  declaration  order  has  only  an importance for unnamed arguments that are by default parsed after the named arguments (Tcl
       style). A variable allows changing this behavior in a way that unnamed arguments are parsed first, before the named arguments (Tk style).

PROCEDURE HELP

       The declared procedure can simply be called with the -help option to get the information about the usage of the	procedure  and	its  argu-
       ments:

	      display message -help
		->
	      NAME
		    display message - Displays a simple message box
	      SYNOPSYS
		    display message
			  [-mtype <mtype>] :
			     Message type, default: "Warning", choices: {Info Warning Error}
			  [-font <font>] :
			     Message text font, type: font, default: Arial 10 italic
			  [-level <level>] :
			     Message level, type: integer, range: 1..10
			  [-fg <fg>] :
			     Message color, type: color, default: black
			  [-bg <bg>] :
			     Background color, type: color
			  [-no_border ] :
			     Use a splash window style (no border)
			  [-log_file <log_file>] :
			     Optional message log file, type: file
			  <text> :
			     Multiple text lines to display, type: string
	      DESCRIPTION
		    This procedure allows displaying a configurable message box.

PROCEDURE CALL

       The specified procedure can be called in many ways. The following listing shows some valid procedure calls:

	      display message "The document hasn't yet been saved!"
	      -> display message:
		   mtype=Warning
		   font=Arial 10 italic
		   fg=black
		   no_border=0
		   text={The document hasn't yet been saved!}

	      display message -fg red -bg black "Please save first the document"
	      -> display message:
		   mtype=Warning
		   font=Arial 10 italic
		   fg=red
		   bg=black
		   no_border=0
		   text={Please save first the document}

	      display message -mtype Error -no_border "Why is here no border?"
	      -> display message:
		   mtype=Error
		   font=Arial 10 italic
		   fg=black
		   no_border=1
		   text={Why is here no border?}

	      display message -font {Courier 12} -level 10 
		 "Is there enough space?" "Reduce otherwise the font size!"
	      -> display message:
		   mtype=Warning
		   font=Courier 12
		   level=10
		   fg=black
		   no_border=0
		   text={Is there enough space?} {Reduce otherwise the font size!}
       The next lines show how wrong arguments are recognized. The text argument that is mandatory is missing in the first procedure call:

	      display message -font {Courier 12}
		-> display message: Required argument is missing: text
       Only valid arguments are accepted:

	      display message -category warning Hello
		-> display message: Argument '-category' not known
       Argument types are automatically checked and an error message is generated in case the argument type is not satisfied.

	      display message -fg MyColor "Hello"
		-> display message: Argument 'fg' requires type 'color'. 
			  Provided value: 'MyColor'
       Selection choices have to be respected...

	      display message -mtype Fatal Hello
		-> display message: Argument (mtype) has to be one of the 
			  following elements: Info, Warning, Error
       ... as well as valid value ranges:

	      display message -level 12 Hello
		-> display message: Argument (level) has to be between 1 and 10

INTERACTIVE ARGUMENT DEFINITION

       The  most  intuitive  way to call the procedure is using an interactive form that allows specifying all arguments. This form will automati-
       cally be generated when the declared procedure is called with the -interactive flag.

	      display message -interactive
       The generated form contains for each argument a data entry widget that is adapted to the argument type. Check buttons are used  to  specify
       flags,  radio  boxes  for  tiny	choice	lists, disjoint list boxes for larger choice lists and files, directories, fonts and colors can be
       selected with dedicated browsers.

       After acknowledging the specified argument data via an OK button, the entered data are first validated, before the provided  arguments  are
       transformed  into  local variables and the procedure body is executed. In case the entered data are invalid, a message appears and the user
       can correct them until they are valid.

FLEXIBLE ARGUMENT DIALOG BOX

       The form generator that creates in the previous example the argument dialog box for the interactive procedure call is  also  available  for
       other  purposes than for the definition of procedure arguments. Even if Tk is well known for its code efficient way to build GUIs, the pre-
       sented argument dialog box allows crating complex parameter definition forms in a still much more efficient way.

       The following example tries to illustrate the simplicity to create complex data entry forms. It creates an input mask that allows  specify-
       ing a file to copy, a destination folder as well as a checkbox that allows specifying if an eventual existing file can be overwritten. Com-
       fortable browsers can be used to select files and directories. And finally, the form offers also the possibility to accept and decline  the
       selection. Here is the code snippet that is doing all this:

	      tepam::argument_dialogbox 
		 -existingfile {-label "Source file" -variable SourceFile} 
		 -existingdirectory {-label "Destination folder" -variable DestDir} 
		 -checkbutton {-label "Overwrite existing file" -variable Overwrite}
       The  argument_dialogbox	returns ok when the entered data are validated and cancel when the data entry has been canceled. After the valida-
       tion of the entered data, the argument_dialogbox defines all the specified variables with the entered data inside the calling context.

       A pair of arguments has to be provided to argument_dialogbox for each variable that has to be specified by this last one. The  first  argu-
       ment defines the entry widget type to use to select the variable's data and the second one is a lists of attributes related to the variable
       and the entry widget.

       Many entry widget types are available: Beside the simple generic entries, there are different kinds of  list  and  combo  boxes	available,
       browsers  for  existing	and new files and directories, check and radio boxes and buttons, as well as color and font pickers. If necessary,
       additional entry widget types can be defined.

       The attribute list contains pairs of attribute names and attribute data. The primary attribute is -variable used to specify the variable in
       the  calling context into which the entered data has to be stored. Another often used attribute is -label that allows adding a label to the
       data entry widget. Other attributes are available that allows specifying default values, the expected data types, valid data ranges, etc.

       The next example of a more complex argument dialog box provides a good overview about the different available entry widget types and param-
       eter  attributes.  The  example contains also some formatting instructions like -frame and -sep which allows organizing the different entry
       widgets in frames and sections:

	      set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"}

	      set Result [tepam::argument_dialogbox 
		 -title "System configuration" 
		 -context test_1 
		 -frame {-label "Entries"} 
		    -entry {-label Entry1 -variable Entry1} 
		    -entry {-label Entry2 -variable Entry2 -default "my default"} 
		 -frame {-label "Listbox & combobox"} 
		    -listbox {-label "Listbox, single selection" -variable Listbox1 
			      -choices {1 2 3 4 5 6 7 8} -default 1 -height 3} 
		    -listbox {-label "Listbox, multiple selection" -variable Listbox2
			      -choicevariable ChoiceList -default {"Choice 2" "Choice 3"}
			      -multiple_selection 1 -height 3} 
		    -disjointlistbox {-label "Disjoined listbox" -variable DisJntListbox
				      -choicevariable ChoiceList 
				      -default {"Choice 3" "Choice 5"} -height 3} 
		    -combobox {-label "Combobox" -variable Combobox 
			       -choices {1 2 3 4 5 6 7 8} -default 3} 
		 -frame {-label "Checkbox, radiobox and checkbutton"} 
		    -checkbox {-label Checkbox -variable Checkbox
			       -choices {bold italic underline} -choicelabels {Bold Italic Underline} 
			       -default italic} 
		    -radiobox {-label Radiobox -variable Radiobox
			       -choices {bold italic underline} -choicelabels {Bold Italic Underline} 
			       -default underline} 
		    -checkbutton {-label CheckButton -variable Checkbutton -default 1} 
		 -frame {-label "Files & directories"} 
		    -existingfile {-label "Input file" -variable InputFile} 
		    -file {-label "Output file" -variable OutputFile} 
		    -sep {} 
		    -existingdirectory {-label "Input directory" -variable InputDirectory} 
		    -directory {-label "Output irectory" -variable OutputDirectory} 
		 -frame {-label "Colors and fonts"} 
		    -color {-label "Background color" -variable Color -default red} 
		    -sep {} 
		    -font {-label "Font" -variable Font -default {Courier 12 italic}}]
       The validation status is in this case stored inside the Result variable. If the entered data are validated, Result will contain 0  and  the
       calling program can read the entered data via the variables that have been specified:

	      if {$Result=="cancel"} {
		 puts "Canceled"
	      } else {
		 puts "Arguments: "
		 foreach Var {
		    Entry1 Entry2
		    Listbox1 Listbox2 DisJntListbox
		    Combobox Checkbox Radiobox Checkbutton
		    InputFile OutputFile InputDirectory OutputDirectory
		    Color Font
		 } {
		    puts "  $Var: '[set $Var]'"
		 }
	      }
	      -> Arguments:
		 Entry1: 'Hello, this is a trial'
		 Entry2: 'my default'
		 Listbox1: '1'
		 Listbox2: '{Choice 2} {Choice 3}'
		 DisJntListbox: '{Choice 3} {Choice 5}'
		 Combobox: '3'
		 Checkbox: 'italic'
		 Radiobox: 'underline'
		 Checkbutton: '1'
		 InputFile: 'c:	epamin.txt'
		 OutputFile: 'c:	epamout.txt'
		 InputDirectory: 'c:	epaminput'
		 OutputDirectory: 'c:	epamoutput'
		 Color: 'red'
		 Font: 'Courier 12 italic'

SEE ALSO

       tepam::argument_dialogbox(3tcl), tepam::procedure(3tcl)

KEYWORDS

       argument integrity, argument validation, arguments, entry mask, parameter entry form, procedure, subcommand

CATEGORY

       Procedures, arguments, parameters, options

COPYRIGHT

       Copyright (c) 2009/2010, Andreas Drollinger

tepam								       0.2.0							       tepam(3tcl)