Provided by: tcllib_1.15-dfsg-2_all 
NAME
tepam::procedure - TEPAM procedure, reference manual
SYNOPSIS
package require Tcl 8.3
package require tepam ?0.4?
tepam::procedure name attributes body
_________________________________________________________________
DESCRIPTION
This package provides an alternative way to declare Tcl procedures and to manage its
arguments. There is a lot of benefit to declare a procedure with TEPAM rather than with
the Tcl standard command proc: TEPAM allows specifying inside the procedure declaration
all information that is required to generate comprehensive documentations and help
support. The information is also used by an automatically invoked argument checker that
validates the provided procedure arguments before the procedure body is executed. Finally,
a procedure can be called interactively which will open a graphical form that allows
specifying the procedure arguments.
TEPAM simplifies also the handling of the different types of argument, like the named
arguments (often also called options) and the unnamed arguments. TEPAM supports the named
first, unnamed later style (typical Tcl command style) as well as also the unnamed first,
named later style (typical Tk command style). TEPAM takes care about default values for
arguments, optional arguments, multiple applicable arguments, etc. and eliminates the need
to check the validity of the argument inside the procedure bodies.
An informal overview of all the TEPAM procedure declaration and calling features as well
as a short introduction into TEPAM is provided by tepam(3tcl).
TERMINOLOGY
The exact meaning of several terms that are used in this document will be shortly
explained to avoid any ambiguities and misunderstandings.
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.
The string command is an example of such a command that implements for example
subcommands to check a character string's length, to compare strings, to extract
substrings, etc:
string length string
string compare string string
string range string first last
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 string command's class check could be implemented as independent
sub-sub-commands of the string command:
string is alnum string
string is integer string
string is double string
Procedure attribute
TEPAM allows attaching to a declared procedure different kind of attributes. Some
of these attributes are just used for documentation purposes, but other attributes
specify the way how the procedure has to be called. Also the procedure arguments
are defined in form of a procedure attribute.
Argument
TEPAM uses the term argument for the parameters of a procedure.
The following example calls the subcommand string compare with several arguments:
string compare -nocase -length 3 "emphasized" "emphasised"
The following paragraphs discuss these different argument types.
Named argument
Some parameters, as -length 3 of the subcommand string compare have to be provided
as pairs of argument names and argument values. This parameter type is often also
called option.
TEPAM uses the term named argument for such options as well as for the flags (see
next item).
Flag, switch
Another parameter type is the flag or the switch. Flags are provided simply by
naming the flag leading with the '-' character. The -nocase of the previous string
compare example is such a flag.
Flags are considered by TEPAM like a special form of named arguments.
Unnamed argument
For the other parameters, e.g. the ones for which the argument name has not to be
mentioned, TEPAM uses the term unnamed argument. The previous string compare
example uses for the two provided character strings two unnamed arguments.
Argument attribute
TEPAM allows describing the purpose of each procedure argument with argument
attributes. While some of them are just documenting the attributes, most attributes
are used by an argument manager to control and validate the arguments that are
provided during a procedure call. Argument attributes are used to specify default
values, parameter classes (integer, xdigit, font, ...), choice validation lists,
value ranges, etc.
Named arguments first, unnamed arguments later
The string compare command of the previous example requires that the named
arguments (options, flags) are provided first. The two mandatory (unnamed)
arguments have to be provided as last argument.
This is the usual Tcl style (exceptions exist) which is referred in the TEPAM
documentation as named arguments first, unnamed arguments later style.
Unnamed arguments first, named arguments later
In contrast to most Tcl commands, Tk uses generally (exceptions exist also here) a
different calling style where the unnamed arguments have to be provided first,
before the named arguments have to be provided:
pack .ent1 .ent2 -fill x -expand yes -side left
This style is referred in the TEPAM documentation as unnamed arguments first, named
arguments later style.
PROCEDURE DECLARATION
TEPAM allows declaring new Tcl procedures with the command tepam::procedure that has
similar to the standard Tcl command proc also 3 arguments:
tepam::procedure name attributes body
The TEPAM procedure declaration syntax is demonstrated by the following example:
tepam::procedure {display message} {
-short_description
"Displays a simple message box"
-description
"This procedure allows displaying a configurable\
message box. The default message type that is\
created is a warning, but also errors and info can\
be generated.
The procedure accepts multiple text lines."
-example
{display message -mtype Warning "Save first your job"}
-args {
{-mtype -choices {Info Warning Error} \
-default Warning -description "Message type"}
{text -type string -multiple \
-description "Multiple text lines to display"}
}
} {
puts "Message type: $mtype"
puts "Message: $text"
}
The 3 arguments of procedure are:
name The procedure name can be used in very flexible ways. Procedure names can have
namespace qualifiers. By providing a two element name list as procedure name, a
subcommand of a procedure will be declared. It is even possible to declare sub-sub-
commands of a procedure by providing name lists with three elements.
Here are some valid procedure declarations using different procedure names (the
attribute and body arguments are empty for simplicity):
# Simple procedure name:
tepam::procedure display_message {} {}
# Procedure declared in the main namespace:
tepam::procedure ::display_message {} {}
# Procedure in the namespace ::ns:
tepam::procedure ::ns::display_message {} {}
# Declaration of the subcommand message of the procedure display:
tepam::procedure {display message} {} {}
attributes
All procedure attributes are provided in form of an option list that contains pairs
of option names and option values. The example above has as procedure attribute a
short and a normal description, but also the procedure arguments are defined in
form of a procedure attribute.
Most procedure attributes are providing information for documentation purposes. But
some of them affect also the way how the procedure can be called. The section
Procedure Attributes discusses in detail the available procedure attributes.
The procedure arguments are defined in form of a special procedure attribute. Most
of the information provided in the argument definition is not just used for
documentation purposes. This information is in fact used by the TEPAM argument
manager to handle and validate the various forms of arguments that are provided
during the procedure calls. The section Argument Declaration discusses in detail
all the argument definition attributes.
body This is the normal procedure body. The declared arguments will be available to the
procedure body in form of variables.
The procedure body will only be executed if the provided set of arguments could be
validated by the TEPAM argument manager.
tepam::procedure {display_message} {
-args {
{-mtype -default Warning -choices {Warning Error}}
{text -type string}
}
} {
puts "Message type: $mtype"
puts "Message: $text"
}
The commands procedure as well as argument_dialogbox are exported from the namespace
tepam. To use these commands without the tepam:: namespace prefix, it is sufficient to
import them into the main namespace:
namespace import tepam::*
procedure {display_message} {
-args {
PROCEDURE ATTRIBUTES
The first group of procedure attributes is not affecting the behavior of the declared
procedure. These attributes are just used for the purpose of documentation and help text
generation:
-category string
A category can be assigned to a procedure for documentation purposes. Any string is
accepted as category.
-short_description string
The short description of a procedure is used in the documentation summary of a
generated procedure list as well as in the NAME section of a generated procedure
manual page.
-description string
The (full) description assigned to a procedure is used to create user manual and
help pages.
-return string
The -return attribute allows defining the expected return value of a procedure
(used for documentation purposes).
-example string
A help text or manual page of a procedure can be enriched with eventual examples,
using the -example attribute.
The following attributes are not relevant for the documentation and help text generation,
but they affect the behavior of the declared procedure:
-named_arguments_first 0|1
This attribute defines the calling style of a procedure. TEPAM uses by default the
named arguments first, unnamed arguments later style (Tcl). This default behavior
can globally be changed by setting the variable tepam::named_arguments_first to 0.
This global calling style can be changed individually for a procedure with the
procedure's -named_arguments_first attribute.
-auto_argument_name_completion 0|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
tepam::auto_argument_name_completion to 0. This global setting of the automatic
argument name completion can be changed individually for a procedure with the
-auto_argument_name_completion procedure attribute.
-interactive_display_format extended|short
A procedure declared with the TEPAM procedure command can always be called with the
-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 extended mode is more adapted for small procedure
argument sets, the short form is more adequate for huge procedure argument sets.
The choice to use short or extended forms can be globally configured via the
variable tepam::interactive_display_format. This global setting can then be changed
individually for a procedure with the -interactive_display_format procedure
attribute.
-args list
The procedure's arguments are declared via the -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 procedure's -args attribute.
The argument definition syntax will be described more in detail in the following
sub section.
The following attribute allows controlling the logging settings for an individual
procedure:
-command_log 0|1|"interactive"
This argument configures the logging of the procedure calls into the list variable
tepam::ProcedureCallLogList. The default configuration defined by the variable
tepam::command_log will be used if this argument is not defined in a procedure
declaration.
Setting this argument to 0 will disable any procedure call loggings, setting it to
1 will log any procedure calls and setting it to interactive will log just the
procedures that are called interactively (procedures called with the -interactive
flag).
ARGUMENT DECLARATION
The following example shows the structure that is used for the argument definitions in the
context of a procedure declaration:
tepam::procedure {display_message} {
-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 -optional -description "Message color"}
{-log_file -type file -optional -description "Optional message log file"}
{text -type string -multiple -description "Multiple text lines to display"}
}
} {
}
Each of the procedure arguments is declared with a list that has as first element the
argument name, followed by eventual attributes. The argument definition syntax can be
formalized in the following way:
tepam::procedure <name> {
-args {
{<argument_name_1> <arg_attr_name_1a> <arg_attr_value_1a> \
<arg_attr_name_1b> <arg_attr_value_1b> ...}
{<argument_name_2> <arg_attr_name_2a> <arg_attr_value_2a> \
<arg_attr_name_2b> <arg_attr_value_2b> ...}
}
} <body>
The argument names and attributes have to be used in the following way:
Argument name (<argument_name_<n>>)
The provided argument name specifies whether the argument is an unnamed argument or
a named argument. In addition to this, an argument name can also be blank to
indicate an argument comment, or it can start with # to indicate a section comment.
"<Name>"
This is the simplest form of an argument name: An argument whose name is not
starting with '-' is an unnamed argument. The parameter provided during a
procedure call will be assigned to a variable with the name <Name>.
tepam::procedure {print_string} {
-args {
{text -type string -description "This is an unnamed argument"}
}
} {
puts $text
}
print_string "Hello"
-> Hello
"-<Name>"
An argument whose name starts with '-' is a named argument (also called
option). The parameter provided during a procedure call will be assigned to
a variable with the name <Name> (not -<Name>).
tepam::procedure {print_string} {
-args {
{-text -type string -description "This is a named argument"}
}
} {
puts $text
}
print_string -text "Hello"
-> Hello
"--" This flag allows clearly specifying the end of the named arguments and the
beginning of the unnamed arguments, in case the named arguments first,
unnamed arguments later style (Tcl) has been selected.
If the unnamed arguments first, named arguments later style (Tk) style is
selected, this flag is ignored if the unnamed arguments have already been
parsed. Otherwise it will be assigned to the corresponding unnamed argument.
"-" or ""
A blank argument name (either '-' or '') starts a comment for the following
arguments.
tepam::procedure {print_time} {
-interactive_display_format short
-args {
{hours -type integer -description "Hour"}
{minutes -type integer -description "Minute"}
{- The following arguments are optional:}
{seconds -type integer -default 0 -description "Seconds"}
{milliseconds -type integer -default 0 -description "Milliseconds"}
}
} {
puts "${hour}h${minutes}:[expr $seconds+0.001*$milliseconds]"
}
Argument comments are basically used in the graphical argument definition
forms that are created if a procedure is called interactively.
"#*" An argument definition list that starts with '#' is considered as a section
comment. The argument definition list will be trimmed from the '#'
characters and the remaining string will be used as section comment.
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.
tepam::procedure {complex_multiply} {
-description "This function perform a complex multiplication"
-args {
{#### First complex number ####}
{-r0 -type double -description "First number's real part"}
{-i0 -type double -description "First number's imaginary part"}
{#### Second complex number ####}
{-r1 -type double -description "Second number's real part"}
{-i1 -type double -description "Second number's imaginary part"}
}
} {
return [expr $r0*$r1 - $i0*$i1]
}
Argument attributes (<arg_attr_name_<mn>> <arg_attr_value_<mn>>)
The following argument attributes are supported:
-description string
The description argument attribute is used for documentation purpose.
Interactive argument definition forms use this attribute to provide
explanations for an argument.
-type type
The type argument attribute allows assigning the argument either to a
predefined data type, or to an application specific data type. The argument
values that are provided during a procedure call are automatically checked
with respect to the defined argument type.
The section ARGUMENT TYPES provides a list of predefined data types and
explains how application specific types can be specified.
The argument type none has a special meaning. An argument that has the type
none is handled as a flag. A flag is always optional and its related
variable contains the logical value 1 if the flag has been defined during
the procedure call, or otherwise 0.
-default value
Eventual default values can be defined with the -default argument attribute.
Arguments with default values are automatically optional arguments.
-optional|-mandatory
Arguments are by default mandatory, unless a default value is defined. The
flag -optional transforms an argument into an optional argument.
In case an optional argument is not defined during a procedure call, the
corresponding variable will not be defined. The flag -mandatory is the
opposite to -optional. This flag exists only for completion reason, since an
argument is anyway mandatory by default.
-multiple
Arguments that have the -multiple attribute can be defined multiple times
during a procedure call. The values that are provided during a procedure
call for such an argument are stored in a list variable. This is even the
case if such an argument is only defined once during a procedure call.
The -multiple attribute can be attributed to unnamed arguments and to named
arguments. The pair of argument name/argument value has to be repeated for
each provided value in case of a named argument. In case the argument with
the -multiple attribute is an unnamed argument, this one has to be the
absolute last one of all unnamed arguments.
-choices list
A possible set of valid argument values can be attributed to an argument via
the -choices attribute. The argument value provided during a procedure call
will be checked against the provided choice values.
-choicelabels list
An eventual short description can be attributed to each choice option with
the -choicelabels attribute. These descriptions will be used in the
generated help texts and as radio and check box labels for the interactive
calls.
The -choicelabels attribute is optional, but if it is defined, its list
needs to have the identical size as the -choices argument list.
-range {double double}
Another argument constraint can be defined with the -range attribute. The
valid range is defined with a list containing the minimum valid value and a
maximum valid value. The -range attribute has to be used only for numerical
arguments, like integers and doubles.
-validatecommand script
Eventual more complex argument value validations can be performed via
specific validation commands that are assigned to the -validatecommand
attribute. The provided validation command can be a complete script in which
the pattern %P is replaced by the argument value that has to be validated.
An example of a validation command declaration is:
tepam::procedure {display_message} {
-args {
{text -type string -description "Message text" \
-validatecommand "IllegalWordDetector %P"}
} {
}
-widget string
The widgets that allow defining the different arguments in case of an
interactive procedure call are normally selected automatically in function
of the argument type. The -widget attribute allows specifying explicitly a
certain widget type for an argument.
-auxargs list
In case a procedure is called interactively, additional argument attributes
can be provided to the interactive argument definition form via the -auxargs
attribute that is itself a list of attribute name/attribute value pairs:
-auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \
-<arg_attr_name_1b> <arg_attr_value_1b>
}
For example, if a procedure takes as argument a file name it may be
beneficial to specify the required file type for the interactive argument
definition form. This information can be provided via the -auxargs attribute
to the argument definition form:
tepam::procedure LoadPicture {
-args {
{FileName -type existingfile -description "Picture file" \
-auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}}
}
} {
}
-auxargs_commands script
If the auxiliary argument attributes are not static but have to be
dynamically adaptable, the -auxargs_commands allows defining them via
commands that are executed during a procedure call. A list of pairs of
auxiliary attribute names and commands has to be provided to the
-auxargs_commands attribute. The provided commands are executed in the
context of the calling procedure.
-auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \
-<arg_attr_name_1b> <arg_attr_command_1b>
}
VARIABLES
Several variables defined inside the ::tepam namespace are impacting the mode of operation
of the procedures that have been declared with TEPAM' procedure command.
named_arguments_first
This variable defines the general calling style of the procedures. It is by default
set to 1 which selects the named arguments first, unnamed arguments later style
(Tcl style).
By setting this variable to 0, the named arguments first, unnamed arguments later
style is globally selected (Tk style):
set tepam::named_arguments_first 0
While this variable defines the general calling style, the procedure attribute
-named_arguments_first can adapt this style individually for each declared procedure.
auto_argument_name_completion
This variable controls the general automatic argument name matching mode. By
default it is set to 1, meaning that the called procedures are trying to match
eventually abbreviated argument names with the declared argument names.
By setting this variable to 0 the automatic argument name matching mode is
disabled:
set tepam::auto_argument_name_completion 0
While this variable defines the general matching mode, the procedure attribute
-auto_argument_name_completion can adapt this mode individually for each declared
procedure.
interactive_display_format
A procedure declared via the TEPAM procedure command can always be called with the
-interactive switch. By doing so, a graphical form will be generated that allows
entering interactively all procedure arguments.
There are two display modes for these interactive forms. The extended mode which is
the default mode is more adapted for small procedure argument sets. The short form
is more adequate for huge procedure argument sets:
set tepam::interactive_display_format "short"
The choice to use short or extended forms can be globally configured via the variable
interactive_display_format. This global setting can be changed individually for a
procedure with the procedure attribute -interactive_display_format.
help_line_length
The maximum line length used by the procedure help text generator can be specified
with this variable. The default length which is set to 80 (characters) can easily
be adapted to the need of an application:
set tepam::help_line_length 120
Since this variable is applied directly during the help text generation, its value
can continuously be adapted to the current need.
command_log
Procedure calls can be logged inside the list variable tepam::ProcedureCallLogList.
The variable tepam::command_log controls the default logging settings for any
procedures. The following configurations are supported:
• 0: Disables any procedure call loggings
• 1: Enables any procedure call loggings
• "interactive": Will log any procedures called interactively (e.g. procedures
called with the -interactive flag). This is the default configuration.
This default logging configuration can be changed individually for each procedure
with the -command_log attribute.
ARGUMENT TYPES
A comprehensive set of procedure argument types that is already predefined by TEPAM can
easily be completed with additional types that are required for a specific application.
PREDEFINED ARGUMENT TYPES
To remember, a type can be assigned to each specified procedure argument:
tepam::procedure {warning} {
-args {
{-font -type font -default {Arial 10 italic}}
{-severity_level -type integer -optional -range {1 10}}
{-fg -type color -optional -description "Message color"}
{text -type string -multiple -description "Multiple text lines to display"}
}
} {
}
There are some special purpose types that are building the first category of predefined
argument types:
• none
A flag, also called switch, is defined as a named argument that has the type none.
Flags are always optional and the default value of the assigned variable is set to
0. In contrast to the (normal) named arguments, no argument value has to be
provided to a flag.
tepam::procedure flag_test {
-args {
{-flag -type none -description "This is a flag"}
}
} {
puts $flag
}
flag_test
-> 0
flag_test -flag
-> 1
Since no argument value has to be provided to a flag, also no data check is performed for
this argument type.
• string
String is a generic argument data type. Any data string can be provided to a string
type argument and no data type checks are therefore performed. The string type
allows defining single line strings during the interactive procedure calls.
• text
Text is identical to string with the exception that it allows entering multi line
strings during interactive procedure calls.
• {}
A blank argument type signifies an undefined argument type. This is the default
argument type that will be used if no type has been explicitly specified. An
argument that has a blank type behaves identically than an argument that has a
string type, e.g. no argument data checks are performed. The only difference is
that the data type string is mentioned in the generated help documentation, while
this is not the case for blank type.
Several numerical types are defined by TEPAM. The type validation procedures are using the
string is <type> -strict commands to check the validity of the provided arguments, which
assures that no empty strings are accepted as argument value. The type validation
expression for the numerical types and the argument types to which this expression is
applied are:
string is <type_to_check> -strict <argument_value>
• boolean
• integer
• double
Empty strings are accepted as argument value for all the alpha numeric argument types. The
argument types that are falling into this category and validation expression used for them
are:
string is <type_to_check> <argument_value>
• alnum
• alpha
• ascii
• control
• digit
• graph
• lower
• print
• punct
• space
• upper
• wordchar
• xdigit
In addition to the data types checked with the string is <type> commands, TEPAM specifies
some other useful data types:
• char
Each string that has a length of 1 character meets the character type. The type
check is made with the following expression:
expr [string length <argument_value>]==1
• color
Any character strings that are accepted by Tk as a color are considered as valid
color argument. Please note that the Tk package has to be loaded to use the type
color. TEPAM is using the following command to validate the color type:
expr ![catch {winfo rgb . <argument_value>}]
• font
Any character strings that are accepted by Tk as a font are considered as valid
font argument. Please note that the Tk package has to be loaded to use the font
type. TEPAM is using the following command to validate the color type:
expr ![catch {font measure <argument_value> ""}]
• file
Any strings that are not containing one of the following characters are considered
as valid file names: * ? " < >. It is not necessary that the file and its
containing directory exist. Zero-length strings are not considered as valid file
names.
The following expression is used to validate the file names:
expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>]
• existingfile
The argument is valid if it matches with an existing file. The following check is
performed to validate the arguments of this type:
file exists <argument_value>
• directory
The directory argument is validated exactly in the same way as the file arguments.
• existingdirectory
The argument is valid if it matches with an existing directory. The following check
is performed to validate the arguments of this type:
file isdirectory <argument_value>
DEFINING APPLICATION SPECIFIC ARGUMENT TYPES
To add support for a new application specific argument type it is just necessary to add
into the namespace tepam a validation function Validation(<type>). This function requires
one argument. It has to returns 1 if the provided argument matches with the relevant data
type. The function has to return otherwise 0.
The validation command section of the "tepam.tcl" package provides sufficient examples of
validation functions, since it implements the ones for the standard TEPAM types.
The following additional code snippet shows the validation function for a custom argument
type that requires values that have a character string length of exactly 2:
proc tepam::Validate(two_char) {v} {expr [string length $v]==2}
PROCEDURE CALLS
HELP
Each procedure can be called with the -help flag. The procedure will then print a
generated help text to stdout and will then return without performing any additional
actions.
Taking the first procedure declared in PROCEDURE CALLS, the help request and the printed
help text would be:
display message -help
->
NAME
display message - Displays a simple message box
SYNOPSIS
display message
[-mtype <mtype>]
Message type, default: "Warning", choices: {Info, Warning, Error}
<text>
Multiple text lines to display, type: string
DESCRIPTION
This procedure allows displaying a configurable message box. The default
message type that is created is a warning, but also errors and info can
be generated.
The procedure accepts multiple text lines.
EXAMPLE
display message -mtype Warning "Save first your job"
The argument manager is checking if the last provided argument is -help and generates the
requested help message if this is the case. So, also the following example will print the
help message:
display message -mtype Info "It is 7:00" -help
On the other hand, the following call will result in an error:
display message -help -mtype Info "It is 7:00"
->
display message: Argument '-help' not known
INTERACTIVE PROCEDURE CALL
Calling a procedure with the -interactive flag will open a graphical form that allows
specifying interactively all procedure arguments. The Tk library has to be loaded to use
the interactive call. The following example assures that the Tk library is loaded and
shows the command line to call interactively the procedure declared in PROCEDURE CALLS:
package require Tk
display message -interactive
Also the -interactive flag has to be placed at the last argument position as this is also
required for the -help flag. Arguments defined before the -interactive flag will be
ignored. The following example is therefore also a valid interactive procedure call:
display message -mtype Info "It is 7:00" -interactive
UNNAMED ARGUMENTS
Unnamed arguments are typically provided to the called procedure as simple parameters.
This procedure calling form requires that the provided arguments are strictly following
the order of the specified arguments. Several parameters can be assigned to the last
argument if this one has the -multiple attribute. So, the following declared procedure ...
tepam::procedure {display_message} {
-args {
{mtype -choices {Info Warning Error}}
{text -type string -multiple}
}
} {
puts "$mtype: [join $text]"
}
display_message Info "It is PM 7:00."
-> Info: It is PM 7:00.
display_message Info "It is PM 7:00." "You should go home."
-> Info: It is PM 7:00. You should go home.
The nice thing is that unnamed arguments can also be called as named arguments, which can
be handy, for example if the exact specified argument order is not known to a user:
display_message -mtype Info -text "It is PM 7:00."
-> Info: It is PM 7:00.
display_message -text "It is PM 7:00." -mtype Info
-> Info: It is PM 7:00.
display_message -mtype Info -text "It is PM 7:00." -text "You should go home."
-> Info: It is PM 7:00. You should go home.
display_message -text "It is PM 7:00." -text "You should go home." -mtype Info
-> Info: It is PM 7:00. You should go home.
NAMED ARGUMENTS
Named arguments have to be provided to a procedure in form of a parameter pairs composed
by the argument names and the argument values. The order how they are provided during a
procedure call is irrelevant and has not to match with the argument specification order.
The following declared procedure ...
tepam::procedure {display_message} {
-args {
{-mtype -choices {Info Warning Error}}
{-text -type string -multiple}
}
} {
puts "$mtype: [join $text]"
}
display_message -mtype Info -text "It is PM 7:00."
-> Info: It is PM 7:00.
display_message -text "It is PM 7:00." -mtype Info
-> Info: It is PM 7:00.
display_message -mtype Info -text "It is PM 7:00." -text "You should go home."
-> Info: It is PM 7:00. You should go home.
display_message -text "It is PM 7:00." -text "You should go home." -mtype Info
-> Info: It is PM 7:00. You should go home.
Also named arguments that have not the -multiple attribute can be provided multiple times.
Only the last provided argument will be retained in such a case:
display_message -mtype Info -text "It is PM 7:00." -mtype Warning
-> Warning: It is PM 7:00.
UNNAMED ARGUMENTS FIRST, NAMED ARGUMENTS LATER (TK STYLE)
A procedure that has been defined while the variable tepam::named_arguments_first was set
to 1, or with the procedure attribute -named_arguments_first set to 1 has to be called in
the Tcl style. The following procedure declaration will be used in this section to
illustrate the meaning of this calling style:
set tepam::named_arguments_first 1
tepam::procedure my_proc {
-args {
{-n1 -default ""}
{-n2 -default ""}
{u1 -default ""}
{u2 -default ""}
}
} {
puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
}
The unnamed arguments are placed at the end of procedure call, after the named arguments:
my_proc -n1 N1 -n2 N2 U1 U2
-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'
The argument parser considers the first argument that doesn't start with the '-' character
as well as all following arguments as unnamed argument:
my_proc U1 U2
-> n1:'', n2:'', u1:'U1', u2:'U2'
Named arguments can be defined multiple times. If the named argument has the -multiply
attribute, all argument values will be collected in a list. Otherwise, only the last
provided attribute value will be retained:
my_proc -n1 N1 -n2 N2 -n1 M1 U1 U2
-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'
The name of the first unnamed argument has therefore not to start with the '-' character.
The unnamed argument is otherwise considered as name of another named argument. This is
especially important if the first unnamed argument is given by a variable that can contain
any character strings:
my_proc -n1 N1 -n2 N2 "->" "<-"
-> my_proc: Argument '->' not known
set U1 "->"
my_proc -n1 N1 -n2 N2 $U1 U2}]
my_proc: Argument '->' not known
The '--' flag allows separating unambiguously the unnamed arguments from the named
arguments. All data after the '--' flag will be considered as unnamed argument:
my_proc -n1 N1 -n2 N2 -- "->" "<-"
-> n1:'N1', n2:'N2', u1:'->', u2:'<-'
set U1 "->"
my_proc -n1 N1 -n2 N2 -- $U1 U2
-> n1:'N1', n2:'N2', u1:'->', u2:'<-'
NAMED ARGUMENTS FIRST, UNNAMED ARGUMENTS LATER (TCL STYLE)
The Tk calling style will be chosen if a procedure is defined while the variable
tepam::named_arguments_first is set to 0, or if the procedure attribute
-named_arguments_first has been set to 0. The following procedure will be used in this
section to illustrate this calling style:
set tepam::named_arguments_first 0
tepam::procedure my_proc {
-args {
{-n1 -default ""}
{-n2 -default ""}
{u1}
{u2 -default "" -multiple}
}
} {
puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
}
The unnamed arguments have to be provided first in this case. The named arguments are
provided afterwards:
my_proc U1 U2 -n1 N1 -n2 N2
-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'
The argument parser will assign to each defined unnamed argument a value before it
switches to read the named arguments. This default behavior changes a bit if there are
unnamed arguments that are optional or that can take multiple values.
An argument value will only be assigned to an unnamed argument that is optional (that has
either the -optional attribute or that has a default value), if the value is not beginning
with the '-' character or if no named arguments are defined. The value that starts with
'-' is otherwise considered as the name of a named argument.
Argument values are assigned to an argument that has the -multiple attribute as long as
the parameter value doesn't starts with the '-' character.
Values that start with the '-' character can therefore not be assigned to optional unnamed
arguments, which restricts the usage of the Tcl procedure calling style. The Tk style may
be preferable in some cases, since it allows separating unambiguously the named arguments
from the unnamed ones with the '--' flag.
Let's explore in a bit less theoretically the ways how the previously defined procedure
can be called: The first example calls the procedure without any parameters, which leads
to an error since u1 is a mandatory argument:
my_proc
-> my_proc: Required argument is missing: u1
The procedure call is valid if one parameter is provided for u1:
my_proc U1
-> n1:'', n2:'', u1:'U1', u2:''
If more parameters are provided that are not starting with the '-' character, they will be
attributed to the unnamed arguments. U2 will receive 3 of these parameters, since it
accepts multiple values:
my_proc U1 U2 U3 U4
-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'
As soon as one parameter starts with '-' and all unnamed arguments have been assigned, the
argument manager tries to interpret the parameter as name of a named argument. The
procedure call will fail if a value beginning with '-' is assigned to an unnamed argument:
my_proc U1 U2 U3 U4 -U5
-> my_proc: Argument '-U5' not known
The attribution of a parameter to a named argument will fail if there are undefined
unnamed (non optional) arguments. The name specification will in this case simply be
considered as a parameter value that is attributed to the next unnamed argument. This was
certainly not the intention in the following example:
my_proc -n1 N1
-> n1:'', n2:'', u1:'-n1', u2:'N1'
The situation is completely different if values have already been assigned to all
mandatory unnamed arguments. A parameter beginning with the '-' character will in this
case be considered as a name identifier for a named argument:
my_proc U1 -n1 N1
-> n1:'N1', n2:'', u1:'U1', u2:''
No unnamed arguments are allowed behind the named arguments:
my_proc U1 -n1 N1 U2
-> my_proc: Argument 'U2' is not an option
The '--' flag has no special meaning if not all mandatory arguments have got assigned a
value. This flag will simply be attributed to one of the unnamed arguments:
my_proc -- -n1 N1
-> n1:'N1', n2:'', u1:'--', u2:''
But the '--' flag is simply ignored if the argument parser has started to handle the named
arguments:
my_proc U1 -- -n1 N1
-> n1:'N1', n2:'', u1:'U1', u2:''
my_proc U1 -n1 N1 -- -n2 N2
-> n1:'N1', n2:'N2', u1:'U1', u2:''
RAW ARGUMENT LIST
It may be necessary sometimes that the procedure body is able to access the entire list of
arguments provided during a procedure call. This can happen via the args variable that
contains always the unprocessed argument list:
tepam::procedure {display_message} {
-args {
{-mtype -choices {Warning Error} -default Warning}
{text -type string -multiple}
}
} {
puts "args: $args"
}
display_message -mtype Warning "It is 7:00"
-> args: -mtype Warning {It is 7:00}
SEE ALSO
tepam(3tcl), tepam::argument_dialogbox(3tcl)
KEYWORDS
argument integrity, argument validation, arguments, procedure, subcommand
CATEGORY
Procedures, arguments, parameters, options
COPYRIGHT
Copyright (c) 2009/2010, Andreas Drollinger