1tepam::procedure(nT)cl's Enhanced Procedure and Argument Managteerpam::procedure(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tepam::procedure - TEPAM procedure, reference manual
9

SYNOPSIS

11       package require Tcl  8.3
12
13       package require tepam  ?0.5?
14
15       tepam::procedure name attributes body
16
17______________________________________________________________________________
18

DESCRIPTION

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
31       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
40       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

TERMINOLOGY

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
48       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
53              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
57              string length string
58              string compare string string
59              string range string first last
60              ...
61
62       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
68              string is alnum string
69              string is integer string
70              string is double string
71              ...
72
73       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
78              defined in form of a procedure attribute.
79
80       Argument
81              TEPAM uses the term argument for the parameters of a procedure.
82
83              The following example calls the subcommand string  compare  with
84              several arguments:
85
86              string compare -nocase -length 3 "emphasized" "emphasised"
87
88              The following paragraphs discuss these different argument types.
89
90       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
95              TEPAM  uses  the term named argument for such options as well as
96              for the flags (see next item).
97
98       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
104              Flags are considered by TEPAM like a special form of named argu‐
105              ments.
106
107       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
113       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
122       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
128              string compare -nocase -length 3 Water $Text
129
130              This is the usual Tcl style (exceptions exist) which is referred
131              in  the  TEPAM  documentation  as named arguments first, unnamed
132              arguments later style.
133
134       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
137              arguments have to be provided first, before the named  arguments
138              have to be provided:
139
140              pack .ent1 .ent2 -fill x -expand yes -side left
141
142              This  style  is  referred  in the TEPAM documentation as unnamed
143              arguments first, named arguments later style.
144

PROCEDURE DECLARATION

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
150       tepam::procedure name attributes body
151
152       The TEPAM procedure declaration syntax is demonstrated by the following
153       example:
154
155              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
178       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
184              Here  are some valid procedure declarations using different pro‐
185              cedure names (the attribute and body  arguments  are  empty  for
186              simplicity):
187
188              # 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
197       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
201              description, but also the procedure  arguments  are  defined  in
202              form of a procedure attribute.
203
204              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
209              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
212              information  is  in  fact  used by the TEPAM argument manager to
213              handle 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
217       body   This is the normal procedure body. The declared  arguments  will
218              be available to the procedure body in form of variables.
219
220              The  procedure body will only be executed if the provided set of
221              arguments could be validated by the TEPAM argument manager.
222
223              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
233       The commands procedure as well as argument_dialogbox are exported  from
234       the  namespace  tepam. To use these commands without the tepam:: names‐
235       pace prefix, it is sufficient to import them into the main namespace:
236
237              namespace import tepam::*
238
239              procedure {display_message} {
240                 -args {
241                    ...
242
243   PROCEDURE ATTRIBUTES
244       The first group of attributes affect the behavior of the declared  pro‐
245       cedure:
246
247       -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
255       -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
264       -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
268              argument  values. There are two display modes for these interac‐
269              tive forms. While the extended mode is more  adapted  for  small
270              procedure  argument  sets,  the  short form is more adequate for
271              huge procedure argument sets.
272
273              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
278       -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
285              The  argument definition syntax will be described more in detail
286              in the following sub section.
287
288       The next attributes allow specifying custom argument checks as well  as
289       custom error messages in case these checks are failing:
290
291       -validatecommand script
292              Custom  argument validations can be performed via specific vali‐
293              dation commands  that  are  defined  with  the  -validatecommand
294              attribute.
295
296              Validation command declaration example:
297
298              tepam::procedure {display_message} {
299                 -args {
300                    {text -type string -description "Message text"} }
301                 -validatecommand {IllegalWordDetector $text}
302              } {
303              }
304
305              The  validation  command  is  executed  in  the  context  of the
306              declared procedure  body.  The  different  argument  values  are
307              accessed  via the argument names. Note there is also an argument
308              attribute -validatecommand that allows declaring  custom  checks
309              for specific arguments.
310
311              The attribute -validatecommand can be repeated to declare multi‐
312              ple custom checks.
313
314       -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
320       The  following attribute allows controlling the logging settings for an
321       individual procedure:
322
323       -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
329              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
334       The next group of procedure attributes is just used for the purpose  of
335       documentation and help text generation:
336
337       -category string
338              A category can be assigned to a procedure for documentation pur‐
339              poses. Any string is accepted as category.
340
341       -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
346       -description string
347              The (full) description assigned to a procedure is used to create
348              user manual and help pages.
349
350       -return string
351              The  -return attribute allows defining the expected return value
352              of a procedure (used for documentation purposes).
353
354       -example string
355              A help text or manual page of a procedure can be  enriched  with
356              eventual examples, using the -example attribute.
357
358   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
362              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
377              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
386       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
392              "<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
398                     tepam::procedure {print_string} {
399                        -args {
400                           {text -type string -description "This is an unnamed argument"}
401                        }
402                     } {
403                        puts $text
404                     }
405
406                     print_string "Hello"
407                      -> Hello
408
409              "-<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
415                     tepam::procedure {print_string} {
416                        -args {
417                           {-text -type string -description "This is a named argument"}
418                        }
419                     } {
420                        puts $text
421                     }
422
423                     print_string -text "Hello"
424                      -> Hello
425
426              "--"   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
431                     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
436              "-" or ""
437                     A blank argument name (either '-' or '') starts a comment
438                     for the following arguments.
439
440                     tepam::procedure {print_time} {
441                        -interactive_display_format short
442                        -args {
443                           {hours -type integer -description "Hour"}
444                           {minutes -type integer -description "Minute"}
445
446                           {- 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
454                     Argument comments are basically  used  in  the  graphical
455                     argument definition forms that are created if a procedure
456                     is called interactively.
457
458              "#*"   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
461                     remaining string will be used as section comment.
462
463                     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
468                     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
475                           {#### 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
483       Argument attributes (<arg_attr_name_<mn>> <arg_attr_value_<mn>>)
484              The following argument attributes are supported:
485
486              -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
491              -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
498                     The section ARGUMENT TYPES provides a list of  predefined
499                     data  types  and  explains how application specific types
500                     can be specified.
501
502                     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
508              -default value
509                     Eventual default values can be defined with the  -default
510                     argument  attribute.  Arguments  with  default values are
511                     automatically optional arguments.
512
513              -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
518                     In case an optional argument is not defined during a pro‐
519                     cedure  call,  the  corresponding  variable  will  not be
520                     defined.   The  flag  -mandatory  is  the   opposite   to
521                     -optional.  This  flag exists only for completion reason,
522                     since an argument is anyway mandatory by default.
523
524              -multiple
525                     Arguments  that  have  the  -multiple  attribute  can  be
526                     defined  multiple times during a procedure call. The val‐
527                     ues that are provided during a procedure call for such an
528                     argument  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
532                     The  -multiple  attribute  can  be  attributed to unnamed
533                     arguments 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
540              -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
546              -choicelabels list
547                     An eventual short description can be attributed  to  each
548                     choice  option  with  the  -choicelabels attribute. These
549                     descriptions will be used in the generated help texts and
550                     as radio and check box labels for the interactive calls.
551
552                     The  -choicelabels  attribute  is  optional, but if it is
553                     defined, its list needs to have the identical size as the
554                     -choices argument list.
555
556              -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
561                     numerical arguments, like integers and doubles.
562
563              -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
570                     Validation command declaration example:
571
572                     tepam::procedure {display_message} {
573                        -args {
574                           {text -type string -description "Message text" \
575                                 -validatecommand {IllegalWordDetector %P}}
576                     } {
577                     }
578
579                     While  the  purpose  of  this  custom argument validation
580                     attribute 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
584              -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
589              -widget string
590                     The widgets that allow defining the  different  arguments
591                     in  case  of  an  interactive procedure call are normally
592                     selected automatically in function of the argument  type.
593                     The -widget attribute allows specifying explicitly a cer‐
594                     tain widget type for an argument.
595
596
597              -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
603                     -auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \
604                               -<arg_attr_name_1b> <arg_attr_value_1b>
605                               ...
606                     }
607
608                     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
614                     tepam::procedure LoadPicture {
615                        -args {
616                           {FileName -type existingfile -description "Picture file" \
617                                      -auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}}
618                        }
619                     } {
620                     }
621
622              -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
627                     attribute  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
631                     -auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \
632                                        -<arg_attr_name_1b> <arg_attr_command_1b>
633                                        ...
634                     }
635

VARIABLES

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
641       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
646              By  setting  this  variable  to  0,  the  named arguments first,
647              unnamed arguments later style is globally selected (Tk style):
648
649              set tepam::named_arguments_first 0
650
651       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
655       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
659              argument names with the declared argument names.
660
661              By setting this variable to 0 the automatic argument name match‐
662              ing mode is disabled:
663
664              set tepam::auto_argument_name_completion 0
665
666       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
670       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
676              There  are  two  display  modes for these interactive forms. The
677              extended mode which is the default  mode  is  more  adapted  for
678              small  procedure  argument sets. The short form is more adequate
679              for huge procedure argument sets:
680
681              set tepam::interactive_display_format "short"
682
683       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
688       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
694              set tepam::help_line_length 120
695
696              Since this variable is applied directly  during  the  help  text
697              generation, its value can continuously be adapted to the current
698              need.
699
700       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
706              ·      0: Disables any procedure call loggings
707
708              ·      1: Enables any procedure call loggings
709
710
711              ·      "interactive":  Will  log  any procedures called interac‐
712                     tively (e.g.  procedures  called  with  the  -interactive
713                     flag). This is the default configuration.
714
715              This  default  logging configuration can be changed individually
716              for each procedure with the -command_log attribute.
717

ARGUMENT TYPES

719       TEPAM provides a comprehensive set of procedure  argument  types.  They
720       can easily be completed with application specific types if necessary.
721
722   PREDEFINED ARGUMENT TYPES
723       To  remember,  a type can be assigned to each specified procedure argu‐
724       ment:
725
726              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
739       ·      none
740
741              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
747              tepam::procedure flag_test {
748                 -args {
749                    {-flag -type none -description "This is a flag"}
750                 }
751              } {
752                 puts $flag
753              }
754
755              flag_test
756              -> 0
757
758              flag_test -flag
759              -> 1
760
761       Since  no  argument  value  has  to be provided to a flag, also no data
762       check is performed for this argument type.
763
764       ·      string
765
766              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
771       ·      text
772
773              Text  is  identical  to  string with the only difference that it
774              allows entering multi line strings during interactive  procedure
775              calls.
776
777       ·      {}
778
779              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
782              behaves identically than an argument that  has  a  string  type,
783              e.g.  no argument data checks are performed. The only difference
784              is that the data type string is mentioned in the generated  help
785              documentation, while this is not the case for the blank type.
786
787       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
792       applied are:
793
794              string is <type_to_check> -strict <argument_value>
795
796       ·      boolean
797
798
799       ·      integer
800
801
802       ·      double
803
804
805       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
809              string is <type_to_check> <argument_value>
810
811       ·      alnum
812
813
814       ·      alpha
815
816
817       ·      ascii
818
819
820       ·      control
821
822
823       ·      digit
824
825
826       ·      graph
827
828
829       ·      lower
830
831
832       ·      print
833
834
835       ·      punct
836
837
838       ·      space
839
840
841       ·      upper
842
843
844       ·      wordchar
845
846
847       ·      xdigit
848
849
850       In addition to the data types checked with the string  is  <type>  com‐
851       mands, TEPAM specifies some other useful data types:
852
853       ·      char
854
855              Each string that has a length of 1 character meets the character
856              type. The type check is made with the following expression:
857
858              expr [string length <argument_value>]==1
859
860       ·      color
861
862              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
867              expr ![catch {winfo rgb . <argument_value>}]
868
869       ·      font
870
871              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
876              expr ![catch {font measure <argument_value> ""}]
877
878       ·      file
879
880              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
885              The following expression is used to validate the file names:
886
887              expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>]
888
889       ·      existingfile
890
891              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
895              file exists <argument_value>
896
897       ·      directory
898
899              The  directory  argument is validated exactly in the same way as
900              the file arguments.
901
902       ·      existingdirectory
903
904              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
908              file isdirectory <argument_value>
909
910   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
917       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
921       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
925              proc tepam::Validate(two_char) {v} {expr {[string length $v]==2}}
926

PROCEDURE CALLS

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
933       Taking the first  procedure  declared  in  PROCEDURE  CALLS,  the  help
934       request and the printed help text would be:
935
936              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
957              display message -mtype Info "It is 7:00" -help
958       On the other hand, the following call will result in an error:
959
960              display message -help -mtype Info "It is 7:00"
961              ->
962              display message: Argument '-help' not known
963
964   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
971              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
975       before  the -interactive flag will be ignored. The following example is
976       therefore also a valid interactive procedure call:
977
978              display message -mtype Info "It is 7:00" -interactive
979
980   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
988              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
998              display_message Info "It is PM 7:00."
999              -> Info: It is PM 7:00.
1000
1001              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
1007              display_message -mtype Info -text "It is PM 7:00."
1008              -> Info: It is PM 7:00.
1009
1010              display_message -text "It is PM 7:00." -mtype Info
1011              -> Info: It is PM 7:00.
1012
1013              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
1016              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
1019   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
1025       The following declared procedure ...
1026
1027              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
1037              display_message -mtype Info -text "It is PM 7:00."
1038              -> Info: It is PM 7:00.
1039
1040              display_message -text "It is PM 7:00." -mtype Info
1041              -> Info: It is PM 7:00.
1042
1043              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
1046              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
1052              display_message -mtype Info -text "It is PM 7:00." -mtype Warning
1053              -> Warning: It is PM 7:00.
1054
1055   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
1062              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
1076              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
1082              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
1087       retained:
1088
1089              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
1097              my_proc -n1 N1 -n2 N2 "->" "<-"
1098              -> my_proc: Argument '->' not known
1099
1100              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
1107              my_proc -n1 N1 -n2 N2 -- "->" "<-"
1108              -> n1:'N1', n2:'N2', u1:'->', u2:'<-'
1109
1110              set U1 "->"
1111              my_proc -n1 N1 -n2 N2 -- $U1 U2
1112              -> n1:'N1', n2:'N2', u1:'->', u2:'<-'
1113
1114   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
1120              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
1134              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
1138       behavior changes a bit if there are unnamed arguments that are optional
1139       or that can take multiple values.
1140
1141       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
1147       Argument  values  are  assigned  to  an argument that has the -multiple
1148       attribute as long as the parameter value doesn't starts  with  the  '-'
1149       character.
1150
1151       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
1157       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
1162              my_proc
1163              -> my_proc: Required argument is missing: u1
1164       The procedure call is valid if one parameter is provided for u1:
1165
1166              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
1172              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
1177       beginning with '-' is assigned to an unnamed argument:
1178
1179              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
1185       intention in the following example:
1186
1187              my_proc -n1 N1
1188              -> n1:'', n2:'', u1:'-n1', u2:'N1'
1189       The  situation  is  completely  different  if  values have already been
1190       assigned 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
1194              my_proc U1 -n1 N1
1195              -> n1:'N1', n2:'', u1:'U1', u2:''
1196       No unnamed arguments are allowed behind the named arguments:
1197
1198              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
1204              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
1209              my_proc U1 -- -n1 N1
1210              -> n1:'N1', n2:'', u1:'U1', u2:''
1211
1212              my_proc U1 -n1 N1 -- -n2 N2
1213              -> n1:'N1', n2:'N2', u1:'U1', u2:''
1214
1215   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
1221              tepam::procedure {display_message} {
1222                 -args {
1223                    {-mtype -choices {Warning Error} -default Warning}
1224                    {text -type string -multiple}
1225
1226                 }
1227              } {
1228                 puts "args: $args"
1229              }
1230              display_message -mtype Warning "It is 7:00"
1231              -> args: -mtype Warning {It is 7:00}
1232

SEE ALSO

1234       tepam(n), tepam::argument_dialogbox(n)
1235

KEYWORDS

1237       argument integrity, argument validation, arguments, procedure,  subcom‐
1238       mand
1239

CATEGORY

1241       Procedures, arguments, parameters, options
1242
1244       Copyright (c) 2009-2013, Andreas Drollinger
1245
1246
1247
1248
1249tcllib                               0.5.0                 tepam::procedure(n)
Impressum