tepam::procedure(Tcl's Enhanced Procedure and Argument Mtepam::procedure(3tcl)
______________________________________________________________________________
NAME
tepam::procedure - TEPAM procedure, reference manual
SYNOPSIS
package require Tcl 8.3
package require tepam ?0.5?
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 proce-
dure 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 pro-
cedure body is executed. Finally, a procedure can be called interac-
tively which will open a graphical form that allows specifying the pro-
cedure 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 imple-
ments for example subcommands to check a character string
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 subcom-
mands 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 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 documen-
tation purposes, but other attributes specify the way how the
procedure has to be called. Also the procedure arguments are de-
fined 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 val-
ues. 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 pro-
vided 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 argu-
ments.
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 argu-
ment. The previous string compare example uses for the two pro-
vided 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 document-
ing the attributes, most attributes are used by an argument man-
ager 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 argu-
ment.
string compare -nocase -length 3 Water $Text
This is the usual Tcl style (exceptions exist) which is referred
in the TEPAM documentation as named arguments first, unnamed ar-
guments 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 ar-
guments 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 ar-
guments first, named arguments later style.
PROCEDURE DECLARATION
TEPAM allows declaring new Tcl procedures with the command tepam::pro-
cedure that has similar to the standard Tcl command proc also 3 argu-
ments:
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 pro-
cedure 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 exam-
ple above has as procedure attribute a short and a normal de-
scription, but also the procedure arguments are defined in form
of a procedure attribute.
Most procedure attributes are providing information for documen-
tation purposes. But some of them affect also the way how the
procedure can be called. The section Procedure Attributes dis-
cusses in detail the available procedure attributes.
The procedure arguments are defined in form of a special proce-
dure attribute. Most of the information provided in the argument
definition is not just used for documentation purposes. This in-
formation is in fact used by the TEPAM argument manager to han-
dle and validate the various forms of arguments that are pro-
vided during the procedure calls. The section Argument Declara-
tion 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:: name-
space prefix, it is sufficient to import them into the main namespace:
namespace import tepam::*
procedure {display_message} {
-args {
...
PROCEDURE ATTRIBUTES
The first group of attributes affect the behavior of the declared pro-
cedure:
-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 -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 argu-
ments 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_argu-
ment_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 ar-
gument values. There are two display modes for these interactive
forms. While the extended mode is more adapted for small proce-
dure argument sets, the short form is more adequate for huge
procedure argument sets.
The choice to use short or extended forms can be globally con-
figured 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 arguments are declared via the -args attribute. An
argument is defined via a list having as first element the argu-
ment name, followed by eventual argument attributes. All these
argument definition lists are packaged themselves into a global
list that is assigned to the -args attribute.
The argument definition syntax will be described more in detail
in the following sub section.
The next attributes allow specifying custom argument checks as well as
custom error messages in case these checks are failing:
-validatecommand script
Custom argument validations can be performed via specific vali-
dation commands that are defined with the -validatecommand at-
tribute.
Validation command declaration example:
tepam::procedure {display_message} {
-args {
{text -type string -description "Message text"} }
-validatecommand {IllegalWordDetector $text}
} {
}
The validation command is executed in the context of the de-
clared procedure body. The different argument values are ac-
cessed via the argument names. Note there is also an argument
attribute -validatecommand that allows declaring custom checks
for specific arguments.
The attribute -validatecommand can be repeated to declare multi-
ple custom checks.
-validatecommand_error_text string
This attribute allows overriding the default error message for a
custom argument validation (defined by -validatecommand). Also
this attribute can be repeated in case multiple argument checks
are declared.
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 con-
figuration 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 log-
gings, 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).
The next group of procedure attributes is just used for the purpose of
documentation and help text generation:
-category string
A category can be assigned to a procedure for documentation pur-
poses. Any string is accepted as category.
-short_description string
The short description of a procedure is used in the documenta-
tion 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.
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 argu-
ment 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 argu-
ment (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 ar-
gument definition forms that are created if a procedure
is called interactively.
"#*" An argument definition list that starts with '#' is con-
sidered as a section comment. The argument definition
list will be trimmed from the '#' characters and the re-
maining 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 real part"}
{-i0 -type double -description "First number imaginary part"}
{#### Second complex number ####}
{-r1 -type double -description "Second number real part"}
{-i1 -type double -description "Second number 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 documenta-
tion 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 au-
tomatically optional arguments.
-optional|-mandatory
Arguments are by default mandatory, unless a default
value is defined. The flag -optional transforms an argu-
ment into an optional argument.
In case an optional argument is not defined during a pro-
cedure call, the corresponding variable will not be de-
fined. The flag -mandatory is the opposite to -optional.
This flag exists only for completion reason, since an ar-
gument is anyway mandatory by default.
-multiple
Arguments that have the -multiple attribute can be de-
fined multiple times during a procedure call. The values
that are provided during a procedure call for such an ar-
gument 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 ar-
guments 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 argu-
ments.
-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 de-
scriptions 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 de-
fined, 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 nu-
merical arguments, like integers and doubles.
-validatecommand script
Custom argument value validations can be performed via
specific validation commands that are defined with the
-validatecommand attribute. The provided validation com-
mand can be a complete script in which the pattern %P is
replaced by the argument value that has to be validated.
Validation command declaration example:
tepam::procedure {display_message} {
-args {
{text -type string -description "Message text" \
-validatecommand {IllegalWordDetector %P}}
} {
}
While the purpose of this custom argument validation at-
tribute is the validation of a specific argument, there
is also a global attribute -validatecommand that allows
performing validation that involves multiple arguments.
-validatecommand_error_text string
This attribute allows overriding the default error mes-
sage for a custom argument validation (defined by -vali-
datecommand).
-widget string
The widgets that allow defining the different arguments
in case of an interactive procedure call are normally se-
lected automatically in function of the argument type.
The -widget attribute allows specifying explicitly a cer-
tain 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 infor-
mation 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 dur-
ing a procedure call. A list of pairs of auxiliary attri-
bute 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 impact the mode
of operation of the procedures that have been declared with the TEPAM
procedure command.
named_arguments_first
This variable defines the general calling style of the proce-
dures. It is by default set to 1 which selects the named argu-
ments first, unnamed arguments later style (Tcl style).
By setting this variable to 0, the named arguments first, un-
named 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 ar-
gument names with the declared argument names.
By setting this variable to 0 the automatic argument name match-
ing 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 individu-
ally 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 ex-
tended 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 genera-
tor 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:
o 0: Disables any procedure call loggings
o 1: Enables any procedure call loggings
o "interactive": Will log any procedures called interac-
tively (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
TEPAM provides a comprehensive set of procedure argument types. They
can easily be completed with application specific types if necessary.
PREDEFINED ARGUMENT TYPES
To remember, a type can be assigned to each specified procedure argu-
ment:
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 cate-
gory of predefined argument types:
o 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.
o 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.
o text
Text is identical to string with the only difference that it al-
lows entering multi line strings during interactive procedure
calls.
o {}
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 be-
haves 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 the blank type.
Several numerical types are defined by TEPAM. The type validation pro-
cedures 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 ap-
plied are:
string is <type_to_check> -strict <argument_value>
o boolean
o integer
o 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>
o alnum
o alpha
o ascii
o control
o digit
o graph
o lower
o print
o punct
o space
o upper
o wordchar
o xdigit
In addition to the data types checked with the string is <type> com-
mands, TEPAM specifies some other useful data types:
o 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
o 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>}]
o font
Any character strings that are accepted by Tk as a font are con-
sidered as valid font argument. Please note that the Tk package
has to be loaded to use the font type. TEPAM is using the fol-
lowing command to validate the color type:
expr ![catch {font measure <argument_value> ""}]
o file
Any strings that are not containing one of the following charac-
ters 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>]
o 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>
o directory
The directory argument is validated exactly in the same way as
the file arguments.
o 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 Valida-
tion(<type>). This function requires one argument. It has to returns 1
if the provided argument matches with the relevant data type. The func-
tion has to return otherwise 0.
The validation command section of the "tepam.tcl" package provides suf-
ficient 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 re-
quest 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
If Tk has been loaded a procedure can be called with the -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 proce-
dure declared in PROCEDURE CALLS:
package require Tk
display message -interactive
Also the -interactive flag has to be placed at the last argument posi-
tion as this is also required for the -help flag. Arguments defined be-
fore 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 pro-
vided arguments are strictly following the order of the specified argu-
ments. 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]"
}
... can for example be called in the following ways:
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 argu-
ment 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 parame-
ter 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]"
}
... can be called in the following ways:
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 pro-
vided 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_argu-
ments_first was set to 1, or with the procedure attribute -named_argu-
ments_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 re-
tained:
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 consid-
ered 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 pro-
cedure 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 be-
havior 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 other-
wise considered as the name of a named argument.
Argument values are assigned to an argument that has the -multiple at-
tribute 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 be-
ginning 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 at-
tributed to the next unnamed argument. This was certainly not the in-
tention in the following example:
my_proc -n1 N1
-> n1:'', n2:'', u1:'-n1', u2:'N1'
The situation is completely different if values have already been as-
signed 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 argu-
ment 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, subcom-
mand
CATEGORY
Procedures, arguments, parameters, options
COPYRIGHT
Copyright (c) 2009-2013, Andreas Drollinger
tcllib 0.5.0 tepam::procedure(3tcl)