1tepam::procedure(nT)cl's Enhanced Procedure and Argument Managteerpam::procedure(n)
2______________________________________________________________________________
6
8 tepam::procedure - TEPAM procedure, reference manual
9
11 package require Tcl 8.3
12 package require tepam ?0.5?
14 tepam::procedure name attributes body
16______________________________________________________________________________
18
20 This package provides an alternative way to declare Tcl procedures and
21 to manage its arguments. There is a lot of benefit to declare a proce‐
22 dure with TEPAM rather than with the Tcl standard command proc: TEPAM
23 allows specifying inside the procedure declaration all information that
24 is required to generate comprehensive documentations and help support.
25 The information is also used by an automatically invoked argument
26 checker that validates the provided procedure arguments before the pro‐
27 cedure body is executed. Finally, a procedure can be called interac‐
28 tively which will open a graphical form that allows specifying the pro‐
29 cedure arguments.
30 TEPAM simplifies also the handling of the different types of argument,
32 like the named arguments (often also called options) and the unnamed
33 arguments. TEPAM supports the named first, unnamed later style (typical
34 Tcl command style) as well as also the unnamed first, named later style
35 (typical Tk command style). TEPAM takes care about default values for
36 arguments, optional arguments, multiple applicable arguments, etc. and
37 eliminates the need to check the validity of the argument inside the
38 procedure bodies.
39 An informal overview of all the TEPAM procedure declaration and calling
41 features as well as a short introduction into TEPAM is provided by
42 tepam(n).
43
45 The exact meaning of several terms that are used in this document will
46 be shortly explained to avoid any ambiguities and misunderstandings.
47 Subcommand
49 The usage of subcommands is heavily used in the Tcl language.
50 Several commands are incorporated into a single main command and
51 are selectable via the first argument.
52 The string command is an example of such a command that imple‐
54 ments for example subcommands to check a character string
55 length, to compare strings, to extract substrings, etc:
56 string length string
58 string compare string string
59 string range string first last
60 ...
61 TEPAM provides a framework that allows implementing easily such subcom‐
63 mands in form of Tcl procedures. It allows not only defining a first
64 level of subcommands, but also a higher level of subcommands. The
65 string command class check could be implemented as independent sub-sub-
66 commands of the string command:
67 string is alnum string
69 string is integer string
70 string is double string
71 ...
72 Procedure attribute
74 TEPAM allows attaching to a declared procedure different kind of
75 attributes. Some of these attributes are just used for documen‐
76 tation purposes, but other attributes specify the way how the
77 procedure has to be called. Also the procedure arguments are de‐
78 fined in form of a procedure attribute.
79 Argument
81 TEPAM uses the term argument for the parameters of a procedure.
82 The following example calls the subcommand string compare with
84 several arguments:
85 string compare -nocase -length 3 "emphasized" "emphasised"
87 The following paragraphs discuss these different argument types.
89 Named argument
91 Some parameters, as -length 3 of the subcommand string compare
92 have to be provided as pairs of argument names and argument val‐
93 ues. This parameter type is often also called option.
94 TEPAM uses the term named argument for such options as well as
96 for the flags (see next item).
97 Flag, switch
99 Another parameter type is the flag or the switch. Flags are pro‐
100 vided simply by naming the flag leading with the '-' character.
101 The -nocase of the previous string compare example is such a
102 flag.
103 Flags are considered by TEPAM like a special form of named argu‐
105 ments.
106 Unnamed argument
108 For the other parameters, e.g. the ones for which the argument
109 name has not to be mentioned, TEPAM uses the term unnamed argu‐
110 ment. The previous string compare example uses for the two pro‐
111 vided character strings two unnamed arguments.
112 Argument attribute
114 TEPAM allows describing the purpose of each procedure argument
115 with argument attributes. While some of them are just document‐
116 ing the attributes, most attributes are used by an argument man‐
117 ager to control and validate the arguments that are provided
118 during a procedure call. Argument attributes are used to specify
119 default values, parameter classes (integer, xdigit, font, ...),
120 choice validation lists, value ranges, etc.
121 Named arguments first, unnamed arguments later
123 The string compare command of the previous example requires that
124 the named arguments (options, flags) are provided first. The two
125 mandatory (unnamed) arguments have to be provided as last argu‐
126 ment.
127 string compare -nocase -length 3 Water $Text
129 This is the usual Tcl style (exceptions exist) which is referred
131 in the TEPAM documentation as named arguments first, unnamed ar‐
132 guments later style.
133 Unnamed arguments first, named arguments later
135 In contrast to most Tcl commands, Tk uses generally (exceptions
136 exist also here) a different calling style where the unnamed ar‐
137 guments have to be provided first, before the named arguments
138 have to be provided:
139 pack .ent1 .ent2 -fill x -expand yes -side left
141 This style is referred in the TEPAM documentation as unnamed ar‐
143 guments first, named arguments later style.
144
146 TEPAM allows declaring new Tcl procedures with the command tepam::pro‐
147 cedure that has similar to the standard Tcl command proc also 3 argu‐
148 ments:
149 tepam::procedure name attributes body
151 The TEPAM procedure declaration syntax is demonstrated by the following
153 example:
154 tepam::procedure {display message} {
156 -short_description
157 "Displays a simple message box"
158 -description
159 "This procedure allows displaying a configurable\
160 message box. The default message type that is\
161 created is a warning, but also errors and info can\
162 be generated.
163 The procedure accepts multiple text lines."
164 -example
165 {display message -mtype Warning "Save first your job"}
166 -args {
167 {-mtype -choices {Info Warning Error} \
168 -default Warning -description "Message type"}
169 {text -type string -multiple \
170 -description "Multiple text lines to display"}
171 }
172 } {
173 puts "Message type: $mtype"
174 puts "Message: $text"
175 }
176 The 3 arguments of procedure are:
177 name The procedure name can be used in very flexible ways. Procedure
179 names can have namespace qualifiers. By providing a two element
180 name list as procedure name, a subcommand of a procedure will be
181 declared. It is even possible to declare sub-sub-commands of a
182 procedure by providing name lists with three elements.
183 Here are some valid procedure declarations using different pro‐
185 cedure names (the attribute and body arguments are empty for
186 simplicity):
187 # Simple procedure name:
189 tepam::procedure display_message {} {}
190 # Procedure declared in the main namespace:
191 tepam::procedure ::display_message {} {}
192 # Procedure in the namespace ::ns:
193 tepam::procedure ::ns::display_message {} {}
194 # Declaration of the subcommand message of the procedure display:
195 tepam::procedure {display message} {} {}
196 attributes
198 All procedure attributes are provided in form of an option list
199 that contains pairs of option names and option values. The exam‐
200 ple above has as procedure attribute a short and a normal de‐
201 scription, but also the procedure arguments are defined in form
202 of a procedure attribute.
203 Most procedure attributes are providing information for documen‐
205 tation purposes. But some of them affect also the way how the
206 procedure can be called. The section Procedure Attributes dis‐
207 cusses in detail the available procedure attributes.
208 The procedure arguments are defined in form of a special proce‐
210 dure attribute. Most of the information provided in the argument
211 definition is not just used for documentation purposes. This in‐
212 formation is in fact used by the TEPAM argument manager to han‐
213 dle and validate the various forms of arguments that are pro‐
214 vided during the procedure calls. The section Argument Declara‐
215 tion discusses in detail all the argument definition attributes.
216 body This is the normal procedure body. The declared arguments will
218 be available to the procedure body in form of variables.
219 The procedure body will only be executed if the provided set of
221 arguments could be validated by the TEPAM argument manager.
222 tepam::procedure {display_message} {
224 -args {
225 {-mtype -default Warning -choices {Warning Error}}
226 {text -type string}
227 }
228 } {
229 puts "Message type: $mtype"
230 puts "Message: $text"
231 }
232 The commands procedure as well as argument_dialogbox are exported from
234 the namespace tepam. To use these commands without the tepam:: name‐
235 space prefix, it is sufficient to import them into the main namespace:
236 namespace import tepam::*
238 procedure {display_message} {
240 -args {
241 ...
242 PROCEDURE ATTRIBUTES
244 The first group of attributes affect the behavior of the declared pro‐
245 cedure:
246 -named_arguments_first 0|1
248 This attribute defines the calling style of a procedure. TEPAM
249 uses by default the named arguments first, unnamed arguments
250 later style (Tcl). This default behavior can globally be changed
251 by setting the variable tepam::named_arguments_first to 0. This
252 global calling style can be changed individually for a procedure
253 with the -named_arguments_first attribute.
254 -auto_argument_name_completion 0|1
256 The declared procedures will by default automatically try to
257 match eventually abbreviated argument names to the defined argu‐
258 ments names. This default behavior can globally be changed by
259 setting the variable tepam::auto_argument_name_completion to 0.
260 This global setting of the automatic argument name completion
261 can be changed individually for a procedure with the -auto_argu‐
262 ment_name_completion procedure attribute.
263 -interactive_display_format extended|short
265 A procedure declared with the TEPAM procedure command can always
266 be called with the -interactive option. By doing so, a graphical
267 form will be generated that allows specifying all procedure ar‐
268 gument values. There are two display modes for these interactive
269 forms. While the extended mode is more adapted for small proce‐
270 dure argument sets, the short form is more adequate for huge
271 procedure argument sets.
272 The choice to use short or extended forms can be globally con‐
274 figured via the variable tepam::interactive_display_format. This
275 global setting can then be changed individually for a procedure
276 with the -interactive_display_format procedure attribute.
277 -args list
279 The procedure arguments are declared via the -args attribute. An
280 argument is defined via a list having as first element the argu‐
281 ment name, followed by eventual argument attributes. All these
282 argument definition lists are packaged themselves into a global
283 list that is assigned to the -args attribute.
284 The argument definition syntax will be described more in detail
286 in the following sub section.
287 The next attributes allow specifying custom argument checks as well as
289 custom error messages in case these checks are failing:
290 -validatecommand script
292 Custom argument validations can be performed via specific vali‐
293 dation commands that are defined with the -validatecommand at‐
294 tribute.
295 Validation command declaration example:
297 tepam::procedure {display_message} {
299 -args {
300 {text -type string -description "Message text"} }
301 -validatecommand {IllegalWordDetector $text}
302 } {
303 }
304 The validation command is executed in the context of the de‐
306 clared procedure body. The different argument values are ac‐
307 cessed via the argument names. Note there is also an argument
308 attribute -validatecommand that allows declaring custom checks
309 for specific arguments.
310 The attribute -validatecommand can be repeated to declare multi‐
312 ple custom checks.
313 -validatecommand_error_text string
315 This attribute allows overriding the default error message for a
316 custom argument validation (defined by -validatecommand). Also
317 this attribute can be repeated in case multiple argument checks
318 are declared.
319 The following attribute allows controlling the logging settings for an
321 individual procedure:
322 -command_log 0|1|"interactive"
324 This argument configures the logging of the procedure calls into
325 the list variable tepam::ProcedureCallLogList. The default con‐
326 figuration defined by the variable tepam::command_log will be
327 used if this argument is not defined in a procedure declaration.
328 Setting this argument to 0 will disable any procedure call log‐
330 gings, setting it to 1 will log any procedure calls and setting
331 it to interactive will log just the procedures that are called
332 interactively (procedures called with the -interactive flag).
333 The next group of procedure attributes is just used for the purpose of
335 documentation and help text generation:
336 -category string
338 A category can be assigned to a procedure for documentation pur‐
339 poses. Any string is accepted as category.
340 -short_description string
342 The short description of a procedure is used in the documenta‐
343 tion summary of a generated procedure list as well as in the
344 NAME section of a generated procedure manual page.
345 -description string
347 The (full) description assigned to a procedure is used to create
348 user manual and help pages.
349 -return string
351 The -return attribute allows defining the expected return value
352 of a procedure (used for documentation purposes).
353 -example string
355 A help text or manual page of a procedure can be enriched with
356 eventual examples, using the -example attribute.
357 ARGUMENT DECLARATION
359 The following example shows the structure that is used for the argument
360 definitions in the context of a procedure declaration:
361 tepam::procedure {display_message} {
363 -args {
364 {-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
365 {-font -type font -default {Arial 10 italic} -description "Message text font"}
366 {-level -type integer -optional -range {1 10} -description "Message level"}
367 {-fg -type color -optional -description "Message color"}
368 {-log_file -type file -optional -description "Optional message log file"}
369 {text -type string -multiple -description "Multiple text lines to display"}
370 }
371 } {
372 }
373 Each of the procedure arguments is declared with a list that has as
374 first element the argument name, followed by eventual attributes. The
375 argument definition syntax can be formalized in the following way:
376 tepam::procedure <name> {
378 -args {
379 {<argument_name_1> <arg_attr_name_1a> <arg_attr_value_1a> <arg_attr_name_1b> <arg_attr_value_1b> ...}
380 {<argument_name_2> <arg_attr_name_2a> <arg_attr_value_2a> <arg_attr_name_2b> <arg_attr_value_2b> ...}
381 ...
382 }
383 } <body>
384 The argument names and attributes have to be used in the following way:
385 Argument name (<argument_name_<n>>)
387 The provided argument name specifies whether the argument is an
388 unnamed argument or a named argument. In addition to this, an
389 argument name can also be blank to indicate an argument comment,
390 or it can start with # to indicate a section comment.
391 "<Name>"
393 This is the simplest form of an argument name: An argu‐
394 ment whose name is not starting with '-' is an unnamed
395 argument. The parameter provided during a procedure call
396 will be assigned to a variable with the name <Name>.
397 tepam::procedure {print_string} {
399 -args {
400 {text -type string -description "This is an unnamed argument"}
401 }
402 } {
403 puts $text
404 }
405 print_string "Hello"
407 -> Hello
408 "-<Name>"
410 An argument whose name starts with '-' is a named argu‐
411 ment (also called option). The parameter provided during
412 a procedure call will be assigned to a variable with the
413 name <Name> (not -<Name>).
414 tepam::procedure {print_string} {
416 -args {
417 {-text -type string -description "This is a named argument"}
418 }
419 } {
420 puts $text
421 }
422 print_string -text "Hello"
424 -> Hello
425 "--" This flag allows clearly specifying the end of the named
427 arguments and the beginning of the unnamed arguments, in
428 case the named arguments first, unnamed arguments later
429 style (Tcl) has been selected.
430 If the unnamed arguments first, named arguments later
432 style (Tk) style is selected, this flag is ignored if the
433 unnamed arguments have already been parsed. Otherwise it
434 will be assigned to the corresponding unnamed argument.
435 "-" or ""
437 A blank argument name (either '-' or '') starts a comment
438 for the following arguments.
439 tepam::procedure {print_time} {
441 -interactive_display_format short
442 -args {
443 {hours -type integer -description "Hour"}
444 {minutes -type integer -description "Minute"}
445 {- The following arguments are optional:}
447 {seconds -type integer -default 0 -description "Seconds"}
448 {milliseconds -type integer -default 0 -description "Milliseconds"}
449 }
450 } {
451 puts "${hour}h${minutes}:[expr $seconds+0.001*$milliseconds]"
452 }
453 Argument comments are basically used in the graphical ar‐
455 gument definition forms that are created if a procedure
456 is called interactively.
457 "#*" An argument definition list that starts with '#' is con‐
459 sidered as a section comment. The argument definition
460 list will be trimmed from the '#' characters and the re‐
461 maining string will be used as section comment.
462 Section comments can be used to structure visually the
464 argument definition code. Section comments are also used
465 to structure the generated help texts and the interactive
466 argument definition forms.
467 tepam::procedure {complex_multiply} {
469 -description "This function perform a complex multiplication"
470 -args {
471 {#### First complex number ####}
472 {-r0 -type double -description "First number real part"}
473 {-i0 -type double -description "First number imaginary part"}
474 {#### Second complex number ####}
476 {-r1 -type double -description "Second number real part"}
477 {-i1 -type double -description "Second number imaginary part"}
478 }
479 } {
480 return [expr $r0*$r1 - $i0*$i1]
481 }
482 Argument attributes (<arg_attr_name_<mn>> <arg_attr_value_<mn>>)
484 The following argument attributes are supported:
485 -description string
487 The description argument attribute is used for documenta‐
488 tion purpose. Interactive argument definition forms use
489 this attribute to provide explanations for an argument.
490 -type type
492 The type argument attribute allows assigning the argument
493 either to a predefined data type, or to an application
494 specific data type. The argument values that are provided
495 during a procedure call are automatically checked with
496 respect to the defined argument type.
497 The section ARGUMENT TYPES provides a list of predefined
499 data types and explains how application specific types
500 can be specified.
501 The argument type none has a special meaning. An argument
503 that has the type none is handled as a flag. A flag is
504 always optional and its related variable contains the
505 logical value 1 if the flag has been defined during the
506 procedure call, or otherwise 0.
507 -default value
509 Eventual default values can be defined with the -default
510 argument attribute. Arguments with default values are au‐
511 tomatically optional arguments.
512 -optional|-mandatory
514 Arguments are by default mandatory, unless a default
515 value is defined. The flag -optional transforms an argu‐
516 ment into an optional argument.
517 In case an optional argument is not defined during a pro‐
519 cedure call, the corresponding variable will not be de‐
520 fined. The flag -mandatory is the opposite to -optional.
521 This flag exists only for completion reason, since an ar‐
522 gument is anyway mandatory by default.
523 -multiple
525 Arguments that have the -multiple attribute can be de‐
526 fined multiple times during a procedure call. The values
527 that are provided during a procedure call for such an ar‐
528 gument are stored in a list variable. This is even the
529 case if such an argument is only defined once during a
530 procedure call.
531 The -multiple attribute can be attributed to unnamed ar‐
533 guments and to named arguments. The pair of argument
534 name/argument value has to be repeated for each provided
535 value in case of a named argument. In case the argument
536 with the -multiple attribute is an unnamed argument, this
537 one has to be the absolute last one of all unnamed argu‐
538 ments.
539 -choices list
541 A possible set of valid argument values can be attributed
542 to an argument via the -choices attribute. The argument
543 value provided during a procedure call will be checked
544 against the provided choice values.
545 -choicelabels list
547 An eventual short description can be attributed to each
548 choice option with the -choicelabels attribute. These de‐
549 scriptions will be used in the generated help texts and
550 as radio and check box labels for the interactive calls.
551 The -choicelabels attribute is optional, but if it is de‐
553 fined, its list needs to have the identical size as the
554 -choices argument list.
555 -range {double double}
557 Another argument constraint can be defined with the
558 -range attribute. The valid range is defined with a list
559 containing the minimum valid value and a maximum valid
560 value. The -range attribute has to be used only for nu‐
561 merical arguments, like integers and doubles.
562 -validatecommand script
564 Custom argument value validations can be performed via
565 specific validation commands that are defined with the
566 -validatecommand attribute. The provided validation com‐
567 mand can be a complete script in which the pattern %P is
568 replaced by the argument value that has to be validated.
569 Validation command declaration example:
571 tepam::procedure {display_message} {
573 -args {
574 {text -type string -description "Message text" \
575 -validatecommand {IllegalWordDetector %P}}
576 } {
577 }
578 While the purpose of this custom argument validation at‐
580 tribute is the validation of a specific argument, there
581 is also a global attribute -validatecommand that allows
582 performing validation that involves multiple arguments.
583 -validatecommand_error_text string
585 This attribute allows overriding the default error mes‐
586 sage for a custom argument validation (defined by -vali‐
587 datecommand).
588 -widget string
590 The widgets that allow defining the different arguments
591 in case of an interactive procedure call are normally se‐
592 lected automatically in function of the argument type.
593 The -widget attribute allows specifying explicitly a cer‐
594 tain widget type for an argument.
595 -auxargs list
598 In case a procedure is called interactively, additional
599 argument attributes can be provided to the interactive
600 argument definition form via the -auxargs attribute that
601 is itself a list of attribute name/attribute value pairs:
602 -auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \
604 -<arg_attr_name_1b> <arg_attr_value_1b>
605 ...
606 }
607 For example, if a procedure takes as argument a file name
609 it may be beneficial to specify the required file type
610 for the interactive argument definition form. This infor‐
611 mation can be provided via the -auxargs attribute to the
612 argument definition form:
613 tepam::procedure LoadPicture {
615 -args {
616 {FileName -type existingfile -description "Picture file" \
617 -auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}}
618 }
619 } {
620 }
621 -auxargs_commands script
623 If the auxiliary argument attributes are not static but
624 have to be dynamically adaptable, the -auxargs_commands
625 allows defining them via commands that are executed dur‐
626 ing a procedure call. A list of pairs of auxiliary attri‐
627 bute names and commands has to be provided to the
628 -auxargs_commands attribute. The provided commands are
629 executed in the context of the calling procedure.
630 -auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \
632 -<arg_attr_name_1b> <arg_attr_command_1b>
633 ...
634 }
635
637 Several variables defined inside the ::tepam namespace impact the mode
638 of operation of the procedures that have been declared with the TEPAM
639 procedure command.
640 named_arguments_first
642 This variable defines the general calling style of the proce‐
643 dures. It is by default set to 1 which selects the named argu‐
644 ments first, unnamed arguments later style (Tcl style).
645 By setting this variable to 0, the named arguments first, un‐
647 named arguments later style is globally selected (Tk style):
648 set tepam::named_arguments_first 0
650 While this variable defines the general calling style, the procedure
652 attribute -named_arguments_first can adapt this style individually for
653 each declared procedure.
654 auto_argument_name_completion
656 This variable controls the general automatic argument name
657 matching mode. By default it is set to 1, meaning that the
658 called procedures are trying to match eventually abbreviated ar‐
659 gument names with the declared argument names.
660 By setting this variable to 0 the automatic argument name match‐
662 ing mode is disabled:
663 set tepam::auto_argument_name_completion 0
665 While this variable defines the general matching mode, the procedure
667 attribute -auto_argument_name_completion can adapt this mode individu‐
668 ally for each declared procedure.
669 interactive_display_format
671 A procedure declared via the TEPAM procedure command can always
672 be called with the -interactive switch. By doing so, a graphical
673 form will be generated that allows entering interactively all
674 procedure arguments.
675 There are two display modes for these interactive forms. The ex‐
677 tended mode which is the default mode is more adapted for small
678 procedure argument sets. The short form is more adequate for
679 huge procedure argument sets:
680 set tepam::interactive_display_format "short"
682 The choice to use short or extended forms can be globally configured
684 via the variable interactive_display_format. This global setting can
685 be changed individually for a procedure with the procedure attribute
686 -interactive_display_format.
687 help_line_length
689 The maximum line length used by the procedure help text genera‐
690 tor can be specified with this variable. The default length
691 which is set to 80 (characters) can easily be adapted to the
692 need of an application:
693 set tepam::help_line_length 120
695 Since this variable is applied directly during the help text
697 generation, its value can continuously be adapted to the current
698 need.
699 command_log
701 Procedure calls can be logged inside the list variable
702 tepam::ProcedureCallLogList. The variable tepam::command_log
703 controls the default logging settings for any procedures. The
704 following configurations are supported:
705 • 0: Disables any procedure call loggings
707 • 1: Enables any procedure call loggings
709 • "interactive": Will log any procedures called interac‐
712 tively (e.g. procedures called with the -interactive
713 flag). This is the default configuration.
714 This default logging configuration can be changed individually
716 for each procedure with the -command_log attribute.
717
719 TEPAM provides a comprehensive set of procedure argument types. They
720 can easily be completed with application specific types if necessary.
721 PREDEFINED ARGUMENT TYPES
723 To remember, a type can be assigned to each specified procedure argu‐
724 ment:
725 tepam::procedure {warning} {
727 -args {
728 {-font -type font -default {Arial 10 italic}}
729 {-severity_level -type integer -optional -range {1 10}}
730 {-fg -type color -optional -description "Message color"}
731 {text -type string -multiple -description "Multiple text lines to display"}
732 }
733 } {
734 ...
735 }
736 There are some special purpose types that are building the first cate‐
737 gory of predefined argument types:
738 • none
740 A flag, also called switch, is defined as a named argument that
742 has the type none. Flags are always optional and the default
743 value of the assigned variable is set to 0. In contrast to the
744 (normal) named arguments, no argument value has to be provided
745 to a flag.
746 tepam::procedure flag_test {
748 -args {
749 {-flag -type none -description "This is a flag"}
750 }
751 } {
752 puts $flag
753 }
754 flag_test
756 -> 0
757 flag_test -flag
759 -> 1
760 Since no argument value has to be provided to a flag, also no data
762 check is performed for this argument type.
763 • string
765 String is a generic argument data type. Any data string can be
767 provided to a string type argument and no data type checks are
768 therefore performed. The string type allows defining single line
769 strings during the interactive procedure calls.
770 • text
772 Text is identical to string with the only difference that it al‐
774 lows entering multi line strings during interactive procedure
775 calls.
776 • {}
778 A blank argument type signifies an undefined argument type. This
780 is the default argument type that will be used if no type has
781 been explicitly specified. An argument that has a blank type be‐
782 haves identically than an argument that has a string type, e.g.
783 no argument data checks are performed. The only difference is
784 that the data type string is mentioned in the generated help
785 documentation, while this is not the case for the blank type.
786 Several numerical types are defined by TEPAM. The type validation pro‐
788 cedures are using the string is <type> -strict commands to check the
789 validity of the provided arguments, which assures that no empty strings
790 are accepted as argument value. The type validation expression for the
791 numerical types and the argument types to which this expression is ap‐
792 plied are:
793 string is <type_to_check> -strict <argument_value>
795 • boolean
797 • integer
800 • double
803 Empty strings are accepted as argument value for all the alpha numeric
806 argument types. The argument types that are falling into this category
807 and validation expression used for them are:
808 string is <type_to_check> <argument_value>
810 • alnum
812 • alpha
815 • ascii
818 • control
821 • digit
824 • graph
827 • lower
830 • print
833 • punct
836 • space
839 • upper
842 • wordchar
845 • xdigit
848 In addition to the data types checked with the string is <type> com‐
851 mands, TEPAM specifies some other useful data types:
852 • char
854 Each string that has a length of 1 character meets the character
856 type. The type check is made with the following expression:
857 expr [string length <argument_value>]==1
859 • color
861 Any character strings that are accepted by Tk as a color are
863 considered as valid color argument. Please note that the Tk
864 package has to be loaded to use the type color. TEPAM is using
865 the following command to validate the color type:
866 expr ![catch {winfo rgb . <argument_value>}]
868 • font
870 Any character strings that are accepted by Tk as a font are con‐
872 sidered as valid font argument. Please note that the Tk package
873 has to be loaded to use the font type. TEPAM is using the fol‐
874 lowing command to validate the color type:
875 expr ![catch {font measure <argument_value> ""}]
877 • file
879 Any strings that are not containing one of the following charac‐
881 ters are considered as valid file names: * ? " < >. It is not
882 necessary that the file and its containing directory exist.
883 Zero-length strings are not considered as valid file names.
884 The following expression is used to validate the file names:
886 expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>]
888 • existingfile
890 The argument is valid if it matches with an existing file. The
892 following check is performed to validate the arguments of this
893 type:
894 file exists <argument_value>
896 • directory
898 The directory argument is validated exactly in the same way as
900 the file arguments.
901 • existingdirectory
903 The argument is valid if it matches with an existing directory.
905 The following check is performed to validate the arguments of
906 this type:
907 file isdirectory <argument_value>
909 DEFINING APPLICATION SPECIFIC ARGUMENT TYPES
911 To add support for a new application specific argument type it is just
912 necessary to add into the namespace tepam a validation function Valida‐
913 tion(<type>). This function requires one argument. It has to returns 1
914 if the provided argument matches with the relevant data type. The func‐
915 tion has to return otherwise 0.
916 The validation command section of the "tepam.tcl" package provides suf‐
918 ficient examples of validation functions, since it implements the ones
919 for the standard TEPAM types.
920 The following additional code snippet shows the validation function for
922 a custom argument type that requires values that have a character
923 string length of exactly 2:
924 proc tepam::Validate(two_char) {v} {expr {[string length $v]==2}}
926
928 HELP
929 Each procedure can be called with the -help flag. The procedure will
930 then print a generated help text to stdout and will then return without
931 performing any additional actions.
932 Taking the first procedure declared in PROCEDURE CALLS, the help re‐
934 quest and the printed help text would be:
935 display message -help
937 ->
938 NAME
939 display message - Displays a simple message box
940 SYNOPSIS
941 display message
942 [-mtype <mtype>]
943 Message type, default: "Warning", choices: {Info, Warning, Error}
944 <text>
945 Multiple text lines to display, type: string
946 DESCRIPTION
947 This procedure allows displaying a configurable message box. The default
948 message type that is created is a warning, but also errors and info can
949 be generated.
950 The procedure accepts multiple text lines.
951 EXAMPLE
952 display message -mtype Warning "Save first your job"
953 The argument manager is checking if the last provided argument is -help
954 and generates the requested help message if this is the case. So, also
955 the following example will print the help message:
956 display message -mtype Info "It is 7:00" -help
958 On the other hand, the following call will result in an error:
959 display message -help -mtype Info "It is 7:00"
961 ->
962 display message: Argument '-help' not known
963 INTERACTIVE PROCEDURE CALL
965 If Tk has been loaded a procedure can be called with the -interactive
966 flag to open a graphical form that allows specifying interactively all
967 procedure arguments. The following example assures that the Tk library
968 is loaded and shows the command line to call interactively the proce‐
969 dure declared in PROCEDURE CALLS:
970 package require Tk
972 display message -interactive
973 Also the -interactive flag has to be placed at the last argument posi‐
974 tion as this is also required for the -help flag. Arguments defined be‐
975 fore the -interactive flag will be ignored. The following example is
976 therefore also a valid interactive procedure call:
977 display message -mtype Info "It is 7:00" -interactive
979 UNNAMED ARGUMENTS
981 Unnamed arguments are typically provided to the called procedure as
982 simple parameters. This procedure calling form requires that the pro‐
983 vided arguments are strictly following the order of the specified argu‐
984 ments. Several parameters can be assigned to the last argument if this
985 one has the -multiple attribute. So, the following declared procedure
986 ...
987 tepam::procedure {display_message} {
989 -args {
990 {mtype -choices {Info Warning Error}}
991 {text -type string -multiple}
992 }
993 } {
994 puts "$mtype: [join $text]"
995 }
996 ... can for example be called in the following ways:
997 display_message Info "It is PM 7:00."
999 -> Info: It is PM 7:00.
1000 display_message Info "It is PM 7:00." "You should go home."
1002 -> Info: It is PM 7:00. You should go home.
1003 The nice thing is that unnamed arguments can also be called as named
1004 arguments, which can be handy, for example if the exact specified argu‐
1005 ment order is not known to a user:
1006 display_message -mtype Info -text "It is PM 7:00."
1008 -> Info: It is PM 7:00.
1009 display_message -text "It is PM 7:00." -mtype Info
1011 -> Info: It is PM 7:00.
1012 display_message -mtype Info -text "It is PM 7:00." -text "You should go home."
1014 -> Info: It is PM 7:00. You should go home.
1015 display_message -text "It is PM 7:00." -text "You should go home." -mtype Info
1017 -> Info: It is PM 7:00. You should go home.
1018 NAMED ARGUMENTS
1020 Named arguments have to be provided to a procedure in form of a parame‐
1021 ter pairs composed by the argument names and the argument values. The
1022 order how they are provided during a procedure call is irrelevant and
1023 has not to match with the argument specification order.
1024 The following declared procedure ...
1026 tepam::procedure {display_message} {
1028 -args {
1029 {-mtype -choices {Info Warning Error}}
1030 {-text -type string -multiple}
1031 }
1032 } {
1033 puts "$mtype: [join $text]"
1034 }
1035 ... can be called in the following ways:
1036 display_message -mtype Info -text "It is PM 7:00."
1038 -> Info: It is PM 7:00.
1039 display_message -text "It is PM 7:00." -mtype Info
1041 -> Info: It is PM 7:00.
1042 display_message -mtype Info -text "It is PM 7:00." -text "You should go home."
1044 -> Info: It is PM 7:00. You should go home.
1045 display_message -text "It is PM 7:00." -text "You should go home." -mtype Info
1047 -> Info: It is PM 7:00. You should go home.
1048 Also named arguments that have not the -multiple attribute can be pro‐
1049 vided multiple times. Only the last provided argument will be retained
1050 in such a case:
1051 display_message -mtype Info -text "It is PM 7:00." -mtype Warning
1053 -> Warning: It is PM 7:00.
1054 UNNAMED ARGUMENTS FIRST, NAMED ARGUMENTS LATER (TK STYLE)
1056 A procedure that has been defined while the variable tepam::named_argu‐
1057 ments_first was set to 1, or with the procedure attribute -named_argu‐
1058 ments_first set to 1 has to be called in the Tcl style. The following
1059 procedure declaration will be used in this section to illustrate the
1060 meaning of this calling style:
1061 set tepam::named_arguments_first 1
1063 tepam::procedure my_proc {
1064 -args {
1065 {-n1 -default ""}
1066 {-n2 -default ""}
1067 {u1 -default ""}
1068 {u2 -default ""}
1069 }
1070 } {
1071 puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
1072 }
1073 The unnamed arguments are placed at the end of procedure call, after
1074 the named arguments:
1075 my_proc -n1 N1 -n2 N2 U1 U2
1077 -> n1:'N1', n2:'N2', u1:'U1', u2:'U2'
1078 The argument parser considers the first argument that doesn't start
1079 with the '-' character as well as all following arguments as unnamed
1080 argument:
1081 my_proc U1 U2
1083 -> n1:'', n2:'', u1:'U1', u2:'U2'
1084 Named arguments can be defined multiple times. If the named argument
1085 has the -multiply attribute, all argument values will be collected in a
1086 list. Otherwise, only the last provided attribute value will be re‐
1087 tained:
1088 my_proc -n1 N1 -n2 N2 -n1 M1 U1 U2
1090 -> n1:'M1', n2:'N2', u1:'U1', u2:'U2'
1091 The name of the first unnamed argument has therefore not to start with
1092 the '-' character. The unnamed argument is otherwise considered as name
1093 of another named argument. This is especially important if the first
1094 unnamed argument is given by a variable that can contain any character
1095 strings:
1096 my_proc -n1 N1 -n2 N2 "->" "<-"
1098 -> my_proc: Argument '->' not known
1099 set U1 "->"
1101 my_proc -n1 N1 -n2 N2 $U1 U2
1102 my_proc: Argument '->' not known
1103 The '--' flag allows separating unambiguously the unnamed arguments
1104 from the named arguments. All data after the '--' flag will be consid‐
1105 ered as unnamed argument:
1106 my_proc -n1 N1 -n2 N2 -- "->" "<-"
1108 -> n1:'N1', n2:'N2', u1:'->', u2:'<-'
1109 set U1 "->"
1111 my_proc -n1 N1 -n2 N2 -- $U1 U2
1112 -> n1:'N1', n2:'N2', u1:'->', u2:'<-'
1113 NAMED ARGUMENTS FIRST, UNNAMED ARGUMENTS LATER (TCL STYLE)
1115 The Tk calling style will be chosen if a procedure is defined while the
1116 variable tepam::named_arguments_first is set to 0, or if the procedure
1117 attribute -named_arguments_first has been set to 0. The following pro‐
1118 cedure will be used in this section to illustrate this calling style:
1119 set tepam::named_arguments_first 0
1121 tepam::procedure my_proc {
1122 -args {
1123 {-n1 -default ""}
1124 {-n2 -default ""}
1125 {u1}
1126 {u2 -default "" -multiple}
1127 }
1128 } {
1129 puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
1130 }
1131 The unnamed arguments have to be provided first in this case. The named
1132 arguments are provided afterwards:
1133 my_proc U1 U2 -n1 N1 -n2 N2
1135 -> n1:'N1', n1:'N1', u1:'U1', u2:'U2'
1136 The argument parser will assign to each defined unnamed argument a
1137 value before it switches to read the named arguments. This default be‐
1138 havior changes a bit if there are unnamed arguments that are optional
1139 or that can take multiple values.
1140 An argument value will only be assigned to an unnamed argument that is
1142 optional (that has either the -optional attribute or that has a default
1143 value), if the value is not beginning with the '-' character or if no
1144 named arguments are defined. The value that starts with '-' is other‐
1145 wise considered as the name of a named argument.
1146 Argument values are assigned to an argument that has the -multiple at‐
1148 tribute as long as the parameter value doesn't starts with the '-'
1149 character.
1150 Values that start with the '-' character can therefore not be assigned
1152 to optional unnamed arguments, which restricts the usage of the Tcl
1153 procedure calling style. The Tk style may be preferable in some cases,
1154 since it allows separating unambiguously the named arguments from the
1155 unnamed ones with the '--' flag.
1156 Let's explore in a bit less theoretically the ways how the previously
1158 defined procedure can be called: The first example calls the procedure
1159 without any parameters, which leads to an error since u1 is a mandatory
1160 argument:
1161 my_proc
1163 -> my_proc: Required argument is missing: u1
1164 The procedure call is valid if one parameter is provided for u1:
1165 my_proc U1
1167 -> n1:'', n2:'', u1:'U1', u2:''
1168 If more parameters are provided that are not starting with the '-'
1169 character, they will be attributed to the unnamed arguments. U2 will
1170 receive 3 of these parameters, since it accepts multiple values:
1171 my_proc U1 U2 U3 U4
1173 -> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'
1174 As soon as one parameter starts with '-' and all unnamed arguments have
1175 been assigned, the argument manager tries to interpret the parameter as
1176 name of a named argument. The procedure call will fail if a value be‐
1177 ginning with '-' is assigned to an unnamed argument:
1178 my_proc U1 U2 U3 U4 -U5
1180 -> my_proc: Argument '-U5' not known
1181 The attribution of a parameter to a named argument will fail if there
1182 are undefined unnamed (non optional) arguments. The name specification
1183 will in this case simply be considered as a parameter value that is at‐
1184 tributed to the next unnamed argument. This was certainly not the in‐
1185 tention in the following example:
1186 my_proc -n1 N1
1188 -> n1:'', n2:'', u1:'-n1', u2:'N1'
1189 The situation is completely different if values have already been as‐
1190 signed to all mandatory unnamed arguments. A parameter beginning with
1191 the '-' character will in this case be considered as a name identifier
1192 for a named argument:
1193 my_proc U1 -n1 N1
1195 -> n1:'N1', n2:'', u1:'U1', u2:''
1196 No unnamed arguments are allowed behind the named arguments:
1197 my_proc U1 -n1 N1 U2
1199 -> my_proc: Argument 'U2' is not an option
1200 The '--' flag has no special meaning if not all mandatory arguments
1201 have got assigned a value. This flag will simply be attributed to one
1202 of the unnamed arguments:
1203 my_proc -- -n1 N1
1205 -> n1:'N1', n2:'', u1:'--', u2:''
1206 But the '--' flag is simply ignored if the argument parser has started
1207 to handle the named arguments:
1208 my_proc U1 -- -n1 N1
1210 -> n1:'N1', n2:'', u1:'U1', u2:''
1211 my_proc U1 -n1 N1 -- -n2 N2
1213 -> n1:'N1', n2:'N2', u1:'U1', u2:''
1214 RAW ARGUMENT LIST
1216 It may be necessary sometimes that the procedure body is able to access
1217 the entire list of arguments provided during a procedure call. This can
1218 happen via the args variable that contains always the unprocessed argu‐
1219 ment list:
1220 tepam::procedure {display_message} {
1222 -args {
1223 {-mtype -choices {Warning Error} -default Warning}
1224 {text -type string -multiple}
1225 }
1227 } {
1228 puts "args: $args"
1229 }
1230 display_message -mtype Warning "It is 7:00"
1231 -> args: -mtype Warning {It is 7:00}
1232
1234 tepam(n), tepam::argument_dialogbox(n)
1235
1237 argument integrity, argument validation, arguments, procedure, subcom‐
1238 mand
1239
1241 Procedures, arguments, parameters, options
1242
1244 Copyright (c) 2009-2013, Andreas Drollinger
1245tcllib 0.5.0 tepam::procedure(n)