Tcl Library Source Code

2016/08/14  Andreas Drollinger  <droll>

   * TEPAM version 0.5.2
      Fix of bug 21c45cb4c4bff37adeac400189809c7f25cea1ea (TEPAM doesn't require 
      Tk package before using Tk commands): The updated TEPAM revision checks if 
      Tk has been loaded prior of using Tk commands. If this is not the case an 
      adequate error will be generated.

2016/03/05  Andreas Drollinger  <droll>

   * TEPAM version 0.5.1
      Help generation
       - Correction of bug a0e091b25d (Mis formatted description in auto-generated 
         help text)

2013/10/14  Andreas Drollinger  <droll>

   * TEPAM version 0.5.0
      tepam::procedure command
       - New procedure attributes: -validatecommand_error_text, -validatecommand
       - Updated argument attribute: -validatecommand (the command is now 
         executed in the context of the procedure body which allows accessing 
         argument variables)

     - adbox_all.test, adbox_widgets.test, proc_call_arg_type.test
     - tepam_argument_dialogbox.man, tepam_introductin.man, tepam_procedure.man 

2012/03/26  Andreas Drollinger  <[email protected]>
 
   * TEPAM version 0.3.0
   * tepam.tcl: Add support to log the called procedures inside an array variable.
   * tepam.tcl: Simplify the value validation procedures using the -strict option
     of 'string is <class>'.
   * tepam.tcl: Keep the original value list in the right list of the 
     'disjointlistbox'.
   * tepam.tcl: Add the procedure 'ConfigureWindowsGeometry' to handle window 
     sizes and positions.
   * Cleanup the manuals.
   * tepam_demo.tcl: TEPAM version 0.3.0
   * tepam_demo.tcl: Replaces the control buttons by a menu.

if {![package vsatisfies [package provide Tcl] 8.3]} {return}
package ifneeded tepam          0.5.2 [list source [file join $dir tepam.tcl]]
package ifneeded tepam::doc_gen 0.1.1 [list source [file join $dir tepam_doc_gen.tcl]]

##########################################################################
# TEPAM - Tcl's Enhanced Procedure and Argument Manager
##########################################################################
# tepam.tcl - TEPAM main Tcl package
# 
# TEPAM offers an alternative way to declare Tcl procedures. It provides 
# enhanced argument handling features like automatically generatehd, 
# graphical entry forms and checkers for the procedure arguments.
#
# Copyright (C) 2009/2010/2011 Andreas Drollinger
# 

   #          return -code error $ProcedureArgumentEvaluationResult;
   #       }
   #       if {$SubProcedure!=""} {return [$SubProcedure]};
   #
   #       puts $message; # Procedure body
   #    }
   #
   # ProcedureArgumentEvaluation uses the TCL procedure args argument to read all the provided
   # arguments. It evaluates first if a sub procedure has to be called. This information and the
   # argument validation result are provided to the calling procedure respectively via the 
   # variables SubProcedure and ProcedureArgumentEvaluationResult. In case the result evaluation
   # was not successful, the calling procedure body will simply return. In case the procedure
   # call refers to a sub-procedure, this one will be called. Otherwise, if a valid argument set
   # has been provided to the procedure, and if no sub-procedure has to be called, the original
   # procedure body is executed.
   # Procedure behaves slightly differently in case one or multiple sub-procedures have been 
   # declared without declaring the main procedure itself:
   #
   #    procedure {my_func sub_func} {
   #       -args {message}
   #    } {
   #       puts $message; # Procedure body
   #    }
   #
   # Procedure creates in this case for the main procedure a Tcl procedure as well as for the sub
   # procedure. The main procedure creates an error when it directly called. The sub-procedure
   # is executed within the main procedure context using the uplevel command.
   #
   #    proc my_proc {args} {
   #       ::tepam::ProcedureArgumentEvaluation;
   #       if {$ProcedureArgumentEvaluationResult!=""} {
   #         if {$ProcedureArgumentEvaluationResult=="cancel"} return;
   #         return -code error $ProcedureArgumentEvaluationResult;
   #       }

      return ""
   }

   ######## ProcedureArgumentEvaluation ########

   # ProcedureArgumentEvaluation is the argument evaluator that is embedded by the procedure
   # declaration command 'procedure' into the procedure body in the following way:
   #
   #    proc my_proc {args} {
   #       ::tepam::ProcedureArgumentEvaluation;
   #       if {$ProcedureArgumentEvaluationResult!=""} {
   #         if {$ProcedureArgumentEvaluationResult=="cancel"} return;
   #         return -code error $ProcedureArgumentEvaluationResult;
   #       }

         # Return an empty string if the main procedure has been called and if only sub-commands 
         # have been defined, but not the main procedure itself.
         if {![info exists ProcDef($ProcName,VarList)]} {
            ProcedureArgumentEvaluationReturn ""
         }

      #### Call an argument_dialogbox if the procedure has been called with '-interactive' ####
         set NewArgs {}
         if {$InteractiveCall} {
            # Generate an error if Tk hasn't been loaded
            if {[catch {package present Tk}]} {
               ProcedureArgumentEvaluationReturn "[PureProcName]: Interactive calls are only supported if Tk is loaded!"
            }

            # Start creating the argument_dialogbox argument list with the title attribute:
            set DialogBoxArguments [list -title $ProcName -context $ProcName]

            # Add eventual global validation commands
            foreach ValidateCommand $ProcDef($ProcName,-validatecommand) {
               lappend DialogBoxArguments -validatecommand2 $ValidateCommand
            }
            foreach ValidateCommandErrorText $ProcDef($ProcName,-validatecommand_error_text) {

      
      ProcedureArgumentEvaluationReturn ""
   }

   ######## Validation commands ########
   
   # For each of the standard argument types supported by TEPAM, the validation command 
   # 'Validate(<Type>)' specified in the following section. These commands have to return '1' in
   # case the provided value correspond to the relevant type and '0' if not. Additional user or
   # application specific types can easily be supported simply by adding a validation command
   # for the new type into the 'tepam' namespace.

   proc Validate()         {v} {return 1}
   proc Validate(none)     {v} {return 1}
   proc Validate(string)   {v} {return 1}

   # The following variable can contain a script that is executed for test purposes, before
   # the argument dialog box waits on user interactions. The script is executed in the context
   # of the argument dialog box. Entire user interaction actions can be emulated together 
   # with the previous variable.
   set argument_dialogbox(test,script) {}
   
   # The array variable 'last_parameters' is only used by an argument dialog box when its context 
   # has been specified via the -context attribute. The argument dialog box position and size as 
   # well as its entered data are stored inside this variable when the data are acknowledged and 
   # the form is closed. This allows the form to restore its previous state once it is called 
   # another time.
   array set last_parameters {}
   

   ######## Argument_dialogbox help text ########

   # Eliminate leading tabs in the help text and replace eventual tabs through spaces
   regsub -all -line {^\t\t} $ArgumentDialogboxHelp "" ArgumentDialogboxHelp
   regsub -all -line {\t} $ArgumentDialogboxHelp "   " ArgumentDialogboxHelp

   ######## argument_dialogbox ########

   # The argument dialog box allows a very easy generation of complex dialog boxes that can be 
   # used for tool configuration purposes or to control actions. This command is only available
   # if Tk has been loaded.
   # The argument dialog box accepts only named arguments, e.g. all arguments have to be defined 
   # as argument pairs (-<ArgumentName> <ArgumentValue>). There are some view arguments like -title,
   # -windows and -context that effect the argument dialog box general attitude and embedding. The
   # remaining argument block objective is the definition of variables. Except the two arguments 
   # -frame and -sep that are used to structure graphically the form, all other arguments have to
   # be assigned either to a local or global variable. The argument dialog box will create in the
   # procedure from which it has been called a local variable, unless the variable has not been 
   # defined explicitly as global variable, or as part of a certain namespace.
   # The argument dialog box requires for each variable that has to be controlled a separate 
   # parameter pair. The first element is indicating the entry form that will be used to control 
   # the variable, the second element provides information concerning the variable that has to be

   #      -frame {-label "Others"} \
   #         -color {-label "Background color" -variable MyColor} \

   proc argument_dialogbox {args} {
      variable argument_dialogbox
      variable ArgumentDialogboxHelp
      variable last_parameters
      
      # Generate an error if Tk hasn't been loaded
      if {[catch {package present Tk}]} {
         return -code error "argument_dialogbox requires Tk!"
      }
      
      # Call an initialization command that generates eventual required images:
      GuiEnvironmentInit

      #### Basic parameter check ####

         # Use the first element of args as args list if args contains only one element:
         if {[llength $args]==1} {
            set args [lindex $args 0]
         }
         # Check if arguments are provided and if the number of arguments is even:
         if {[llength $args]<1} {
            return -code error "argument_dialogbox: no argument is provided"
         }

               -validatecommand_error_text -
               -validatecommand2_error_text {
                  lappend ProcOption($ArgName) $ArgValue
               }
            }
         }

         # Create the dialog box top-level window. Hide it until the windows has been entirely 
         # deployed:
         catch {destroy $Wtop}
         toplevel $Wtop
         wm withdraw $Wtop
         wm title $Wtop $ProcOption(-title)
         wm transient $Wtop $ProcOption(-parent)

            ConfigureWindowsGeometry $Wtop $last_parameters($ProcOption(-context),-geometry)
         }

         wm protocol $Wtop WM_DELETE_WINDOW "set ::tepam::argument_dialogbox($Wtop,status) cancel"

         wm deiconify $Wtop

      #### Wait until the dialog box entries are acknowledged (OK button) or discarded #
      
         # Execute a script if required (only for testing purposes)
         if {$argument_dialogbox(test,script)!={}} {
            eval $argument_dialogbox(test,script)
         }
      
         # Stay in a loop until all the provided values have been validated:

                             -message "The entries could not be successfully validated:\n\n$ErrorMessage\nPlease correct the related entries."
               raise $Wtop
            } else { # Return the error message as error for test purposes
               return -code error "The entries could not be successfully validated:\n\n$ErrorMessage\nPlease correct the related entries."
            }
         }
         
         #### Save the dialog box geometry and destroy the form ####

         if {[info exists ProcOption(-context)]} {
            set last_parameters($ProcOption(-context),-geometry) [wm geometry $Wtop]
         }
         destroy $Wtop
         array unset argument_dialogbox $Wtop,*
         return $status
   }

   # The procedure 'argument_dialogbox_scroll' is used by the argument dialogbox y-scrollbar to
   # execute the scroll commands. It implements the Tk typical scroll commands like 'moveto', 
   # 'scroll x pages/units'. In addition to this it implements also an initialization (used to
   # initialize the scrolled frame) and a configuragion command that can be executed when a 
   # configuration event happens.
   proc argument_dialogbox_scroll {Wtop Command args} {
      set FrameHeight [winfo reqheight $Wtop.sf.f]
      set VisibleHeight [expr 1.0*[winfo height $Wtop.sf]/$FrameHeight]

         }
      }
   }

}; # End namespace tepam

# Specify the TEPAM version that is provided by this file:
package provide tepam 0.5.2

##########################################################################
# Id: tepam.tcl
# Modifications:
#
# TEPAM version 0.5.1 - 2016/03/05 droll
# * Help generation

[require Tk 8.3]
[require tepam [opt 0.5]]

[description]

[section "ARGUMENT DIALOGBOX CALL"]

The TEPAM [cmd argument_dialogbox] is a flexible and easily usable data entry form generator that is available if Tk has been loaded. Each data entry element of a form is defined via a [emph {data entry item}] that can be provided to [cmd argument_dialogbox] in two formats:

[list_begin definitions]
[call [cmd tepam::argument_dialogbox] [arg "item_name item_attributes [opt {item_name item_attributes}] [opt {...}]"]]

Using this first format, each [emph {data entry item}] is defined via a pair of two arguments. The first one is the [emph {item name}] that defines the entry widget that has to be used in the form. The second argument, called [emph {item attributes}], specifies the variable which is attributed to the data entry element as well as eventual formatting and context information.

[para]

   ...[example_end]

The following items are classified into this group:

[list_begin definitions]

[def "-title [arg string]"]
The dialog box window title which is by default [emph Dialog] can be changed with the [emph -title] item:
[example_begin]tepam::argument_dialogbox \
   [cmd -title] "System configuration" \
   ...[example_end]

[def "-window [arg string]"]
The argument dialog box uses by default [emph .dialog] as dialog top level window. This path can be changed with the [emph -window] item:
[example_begin]tepam::argument_dialogbox \
   [cmd -window] .dialog \
   ...[example_end]

[def "-parent [arg string]"]
By defining a parent window, the argument dialog box will be displayed beside this one. Without explicit parent window definition, the top-level window will be considered as parent window.
[example_begin]tepam::argument_dialogbox \
   [cmd -parent] .my_appl \
   ...[example_end]

[def "-context [arg string]"]
If a context is defined the dialog box state, e.g. the entered data as well as the window size and position, is  restored the next time the argument dialog box is called. The assignment of a context allows saving the dialog box state in its context to distinguish between different usages of the argument dialog box.
[example_begin]tepam::argument_dialogbox \
   [cmd -context] destination_definitions \
   ...[example_end]

[list_end]

[subsection "Formatting and Display Options"]

[def "-entry [arg list]"]
The [arg -entry] item generates the simplest but most universal data entry widget. It allows entering any kind of data in form of single line strings.
[example_begin]tepam::argument_dialogbox \
   [cmd -entry] {-label Name -variable Entry}[example_end]

[def "-text [arg list]"]
The [arg -text] item generates a multi line text entry widget. The widget height can be selected with the [arg -height] attribute.
[example_begin]tepam::argument_dialogbox \
   [cmd -text] {-label Name -variable Text -height 5}[example_end]

[def "-checkbox [arg list]"]
A group of check boxes is created with the [arg -checkbox] item. The number of check boxes and their option values are specified with a list assigned to the [arg -choices] attribute or via a variable declared with the [arg -choicevariable] attribute:
[example_begin]tepam::argument_dialogbox \
   [cmd -checkbox] {-label "Font sytle" -variable FontStyle \
               -choices {bold italic underline} -default italic}[example_end]
If the labels of the check boxes should differ from the option values, their labels can be defined with the [arg -choicelabels] attribute:
[example_begin]tepam::argument_dialogbox \
   [cmd -checkbox] {-label "Font sytle" -variable FontStyle \
              -choices {bold italic underline} \
              -choicelabels {Bold Italic Underline} \
              -default italic}[example_end]

In contrast to a radio box group, a check box group allows selecting simultaneously several choice options. The selection is stored for this reason inside the defined variable in form of a list, even if only one choice option has been selected.

[def "-radiobox [arg list]"]
A group of radio boxes is created with the [arg -radiobox] item. The number of radio boxes and their option values are specified with a list assigned to the [arg -choices] attribute or via a variable declared with the [arg -choicevariable] attribute.
[para]
In contrast to a check box group, a radio box group allows selecting simultaneously only one choice option. The selected option value is stored directly, and not in form of a list, inside the defined variable.
[example_begin]tepam::argument_dialogbox \
   [cmd -radiobox] {-label "Text adjustment" -variable Adjustment \
              -choices {left center right} -default left}[example_end]
If the labels of the radio boxes should differ from the option values, their labels can be defined with the [arg -choicelabels] attribute:
[example_begin]tepam::argument_dialogbox \
   [cmd -radiobox] {-label "Text adjustment" -variable Adjustment \
              -choices {left center right} \
              -choicelabels {Left Center Right} -default left}[example_end]

[def "-checkbutton [arg list]"]
The [arg -checkbutton] entry widget allows activating or deactivating a single choice option. The result written into the variable will either be [const 0] if the check button was not activated or [const 1] if it was activated. An eventually provided default value has also to be either [const 0] or [const 1].

And here is an example of using a variable to define the selection list:

[example_begin]set TextSizes {8 9 10 12 15 18}
tepam::argument_dialogbox \
   [cmd -combobox] {-label "Text size" -variable Size -choicevariable TextSizes -default 12}[example_end]

[def "-listbox [arg list]"]
In contrast to the combo box, the list box is always displayed by the [arg listbox] entry widget. Only one element is selectable unless the [arg -multiple_selection] attribute is set. The list box height can be selected with the [arg -height] attribute. If the height is not explicitly defined, the list box height is automatically adapted to the argument dialog box size.
The first example uses a variable to define the available choices:

[example_begin]set set AvailableSizes
for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [lb]expr 1<<$k[rb]}

tepam::argument_dialogbox \
   [cmd -listbox] {-label "Distance" -variable Distance \

[def "-label [arg string]"]
The label attribute creates left to the entry widget a label using the provided string as label text:
[example_begin]tepam::argument_dialogbox \
   -entry {[cmd {-label Name}] -variable Name}[example_end]

[def "-variable [arg string]"]
All entry widgets require a specified variable. After accepting the entered information with the OK button, the entry widget data is stored inside the defined variables.
[example_begin]tepam::argument_dialogbox \
   -existingdirectory {-label "Report directory" [cmd {-variable ReportDir}]}[example_end]

[def "-default [arg string]"]
Eventual default data for the entry widgets can be provided via the [arg -default] attribute. The default value is overridden if an argument dialog box with a defined context is called another time. The value acknowledged in a previous call will be used in this case as default value.
[example_begin]tepam::argument_dialogbox \
   -checkbox {-label "Font sytle" -variable FontStyle \

[def "-choices [arg string]"]
Choice lists can directly be defined with the [arg -choices] attribute. This way to define choice lists is especially adapted for smaller, fixed selection lists.
[example_begin]tepam::argument_dialogbox \
   -listbox {-label "Text styles" -variable Styles \
             [cmd {-choices {bold italic underline}}] -default underline[example_end]

[def "-choicelabels [arg string] [emph {(only check and radio buttons)}]"]
If the labels of the check and radio boxes should differ from the option values, they can be defined with the [arg -choicelabels] attribute:
[example_begin]tepam::argument_dialogbox \
   -checkbox {-label "Font sytle" -variable FontStyle \
              -choices {bold italic underline} \
              [cmd {-choicelabels {Bold Italic Underline}}] [example_end]

[def "-choicevariable [arg string]"]
Another way to define the choice lists is using the [arg -choicevariable] attribute. This way to define choice lists is especially adapted for huge and eventually variable selection lists.

[list_begin definitions]

[def "-height [arg string]"]
All widgets containing a selection list ([cmd -listbox], [cmd -disjointlistbox], [cmd -font]) as well as the multi line [cmd -text] widget are accepting the [arg -height] attribute that defines the number of displayed rows of the selection lists.
[example_begin]tepam::argument_dialogbox \
   -listbox {-label "Text size" -variable Size \
             -choices {8 9 10 12 15 18} -default 12 [cmd {-height 3}]}[example_end]
If the no height has been explicitly specified the height of the widget will be dynamically adapted to the argument dialog box size.
[list_end]

[section "APPLICATION SPECIFIC ENTRY WIDGETS"]

An application specific entry widget can be made available to the argument dialog box by adding a dedicated procedure to the [namespace tepam] namespace. This procedure has three arguments; the first one is the widget path, the second one a subcommand and the third argument has various purposes:

[example_begin][arg proc] tepam::ad_form(<WidgetName>) {W Command {Par ""}} {

[para]
The available selection list that is either specified with the [arg -choices] or [arg -choicevariable] attribute is provided via the [arg Par] argument to the entry widget procedure. This list can be used to initialize an available choice list.

[def [arg set]]
If a default value is either defined via the [arg -default] attribute or via a preceding call the entry widget procedure is called with the [arg set] command. The argument [arg Par] contains in this case the value to which the entry widget has to be initialized.

[def [arg get]]
The entry widget procedure command [arg get] has to return the current value of the entry widget.

[list_end]

Eventually specified entry widget item attributes are available via the [var Option] array variable of the calling procedure. This variable becomes accessible inside the entry widget procedure via the [cmd upvar] command.
[para]
There may be a need to store some information in a variable. The array variable [var argument_dialogbox] has to be used for this purpose together with array indexes starting with [emph {"$W,"}], e.g. [emph {argument_dialogbox($W,values)}].
[para]

The [cmd argument_dialogbox] is using two variables inside the namespace [namespace ::tepam]:

[list_begin definitions]
[def "[var argument_dialogbox]"]
Application specific entry widget procedures can use this array variable to store their own data, using as index the widget path provided to the procedure, e.g. [emph {argument_dialogbox($W,<sub_index>)}].

[def "[var last_parameters]"]
This array variable is only used by an argument dialog box if its context has been specified via the [arg -context] attribute. The argument dialog box position and size as well as its entered data are stored inside this variable if the data are acknowledged and the form is closed. This allows the form to restore its previous state once it is called another time.
[para]
To reuse the saved parameters not just in the actual application session but also in another one, it is sufficient to store the [var last_parameter] array variable contents in a configuration file which is loaded the next time an application is launched.

[list_end]
[manpage_end]

TEPAM's procedure declaration syntax is simple and self-explaining. Instead of declaring a procedure with the Tcl key word [cmd proc], a procedure is declared with the TEPAM command [cmd procedure] which takes as [cmd proc] also 3 arguments: The procedure name, the procedure header and the procedure body.
[para]
The following example declares the subcommand [cmd message] of the procedure [cmd display]. This command has several named and unnamed arguments:

[example_begin][cmd 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)"}

... as well as valid value ranges:

[example_begin][cmd {display message}] -level 12 Hello
[emph {  -> display message: Argument (level) has to be between 1 and 10}][example_end]

[section "INTERACTIVE PROCEDURE CALLS"]

The most intuitive way to call the procedure is using an form that allows specifying all arguments interactively. This form will automatically be generated if the declared procedure is called with the [arg -interactive] flag. To use this feature the Tk library has to be loaded.

[example_begin][cmd {display message}] -interactive[example_end]

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.
[para]
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.
[para]
The procedure calls can optionally be logged in a variable. This is for example useful to get the command call lines of interactively called procedures.

[section "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. If Tk has been loaded TEPAM provides and argument dialog box that allows creating complex parameter definition forms in a very efficient way.
[para]
The following example tries to illustrate the simplicity to create complex data entry forms. It creates an input mask that allows specifying a file to copy, a destination folder as well as a checkbox that allows specifying if an eventual existing file can be overwritten. Comfortable 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:

[example_begin][cmd tepam::argument_dialogbox] \
   [cmd -existingfile] {-label "Source file" -variable SourceFile} \
   [cmd -existingdirectory] {-label "Destination folder" -variable DestDir} \
   [cmd -checkbutton] {-label "Overwrite existing file" -variable Overwrite}[example_end]

[list_begin definitions]

[def [emph "Subcommand"]]

The usage of subcommands is heavily used in the Tcl language. Several commands are incorporated into a single main command and are selectable via the first argument.
[para]
The [fun string] command is an example of such a command that implements for example subcommands to check a character string length, to compare strings, to extract substrings, etc:

[example_begin][fun {string length}] [arg string]
[fun {string compare}] [arg string] [arg string]
[fun {string range}] [arg string] [arg first] [arg last]
...[example_end]

[para]
TEPAM provides a framework that allows implementing easily such subcommands in form of Tcl procedures. It allows not only defining a first level of subcommands, but also a higher level of subcommands. The [fun string] command class check could be implemented as independent sub-sub-commands of the [fun string] command:

[example_begin][fun {string is alnum}] [arg string]
[fun {string is integer}] [arg string]
[fun {string is double}] [arg string]
...[example_end]

[def [emph "Procedure attribute"]]

[subsection "Procedure Attributes"]

The first group of attributes affect the behavior of the declared procedure:

[list_begin definitions]
[def "-named_arguments_first [const 0]|[const 1]"]
This attribute defines the calling style of a procedure. TEPAM uses by default the [emph "named arguments first, unnamed arguments later"] style (Tcl). This default behavior can globally be changed by setting the variable [var tepam::named_arguments_first] to [const 0]. This global calling style can be changed individually for a procedure with the [arg -named_arguments_first] attribute.

[def "-auto_argument_name_completion [const 0]|[const 1]"]
The declared procedures will by default automatically try to match eventually abbreviated argument names to the defined arguments names. This default behavior can globally be changed by setting the variable [var tepam::auto_argument_name_completion] to [const 0]. This global setting of the automatic argument name completion can be changed individually for a procedure with the [arg -auto_argument_name_completion] procedure attribute.

[def "-interactive_display_format [const extended]|[const short]"]
A procedure declared with the TEPAM [fun procedure] command can always be called with the [var -interactive] option. By doing so, a graphical form will be generated that allows specifying all procedure argument values. There are two display modes for these interactive forms. While the [emph extended] mode is more adapted for small procedure argument sets, the [const short] form is more adequate for huge procedure argument sets.
[para]
The choice to use short or extended forms can be globally configured via the variable [var tepam::interactive_display_format]. This global setting can then be changed individually for a procedure with the [arg -interactive_display_format] procedure attribute.

[def "-args [arg list]"]
The procedure arguments are declared via the [arg -args] attribute. An argument is defined via a list having as first element the argument name, followed by eventual argument attributes. All these argument definition lists are packaged themselves into a global list that is assigned to the [arg -args] attribute.
[para]
The argument definition syntax will be described more in detail in the following sub section.

[list_end]

The next attributes allow specifying custom argument checks as well as custom error messages in case these checks are failing:

[list_begin definitions]

[def "-validatecommand [arg script]"]
Custom argument validations can be performed via specific validation commands that are defined with the [arg -validatecommand] attribute.
[para]
Validation command declaration example:
[example_begin]tepam::procedure {display_message} {
   -args {
      {text -type string -description "Message text"} }
   [cmd {-validatecommand {IllegalWordDetector $text}}]
} {
}[example_end]
The validation command is executed in the context of the declared procedure body. The different argument values are accessed via the argument names. Note there is also an argument attribute [arg -validatecommand] that allows declaring custom checks for specific arguments.
[para]
The attribute [arg -validatecommand] can be repeated to declare multiple custom checks.

[def "-validatecommand_error_text [arg string]"]
This attribute allows overriding the default error message for a custom argument validation (defined by [arg -validatecommand]). Also this attribute can be repeated in case multiple argument checks are declared.

[list_end]

[para]
Section comments can be used to structure visually the argument definition code. Section comments are also used to structure the generated help texts and the interactive argument definition forms.

[example_begin]tepam::procedure {complex_multiply} {
   -description "This function perform a complex multiplication"
   -args {
      [cmd {{#### First complex number ####}}]
      {-r0 -type double -description "First number real part"}
      {-i0 -type double -description "First number imaginary part"}

      [cmd {{#### Second complex number ####}}]
      {-r1 -type double -description "Second number real part"}
      {-i1 -type double -description "Second number imaginary part"}
   }
} {
   return [lb]expr $r0*$r1 - $i0*$i1[rb]
}[example_end]

[list_end]

[list_end]

[list_end]

[section "VARIABLES"]

Several variables defined inside the [namespace ::tepam] namespace impact the mode of operation of the procedures that have been declared with the TEPAM [fun procedure] command.

[list_begin definitions]
[def "[var named_arguments_first]"]
This variable defines the general calling style of the procedures. It is by default set to [const 1] which selects the [emph "named arguments first, unnamed arguments later"] style (Tcl style).
[para]
By setting this variable to [const 0], the [emph "named arguments first, unnamed arguments later"] style is globally selected (Tk style):
[example {set tepam::named_arguments_first 0}]

On the other hand, the following call will result in an error:
[example_begin][cmd {display message -help -mtype Info "It is 7:00"}]
[emph {->
display message: Argument '-help' not known}][example_end]

[subsection "Interactive Procedure Call"]

If Tk has been loaded a procedure can be called with the [arg -interactive] flag to open a graphical form that allows specifying interactively all procedure arguments. The following example assures that the Tk library is loaded and shows the command line to call interactively the procedure declared in [sectref {PROCEDURE CALLS}]:

[example_begin]package require Tk
[cmd {display message -interactive}][example_end]

Also the [arg -interactive] flag has to be placed at the last argument position as this is also required for the [arg -help] flag. Arguments defined before the [arg -interactive] flag will be ignored. The following example is therefore also a valid interactive procedure call:

[example_begin][cmd {display message}] -mtype Info "It is 7:00" [cmd {-interactive}][example_end]