1tepam(n)         Tcl's Enhanced Procedure and Argument Manager        tepam(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tepam  - An introduction into TEPAM, Tcl's Enhanced Procedure and Argu‐
9       ment Manager
10

DESCRIPTION

12       This document  is  an  informal  introduction  into  TEPAM,  the  Tcl's
13       Enhanced  Procedure  and  Argument Manager. Detailed information to the
14       TEPAM package is provided  in  the  tepam::procedure  and  tepam::argu‐
15       ment_dialogbox reference manuals.
16

OVERVIEW

18       This  package provides a new Tcl procedure declaration syntax that sim‐
19       plifies the implementation of procedure subcommands and the handling of
20       the  different  types  of  procedure  arguments like flags or switches,
21       options, unnamed arguments, optional and mandatory  options  and  argu‐
22       ments, default values, etc. Procedure declarations can be enriched with
23       detailed information about the procedure and its arguments. This infor‐
24       mation is used for the following purposes:
25
26       First  of  all, a preamble is added in front of the body of a procedure
27       that is declared with TEPAM. This preamble calls  an  argument  manager
28       that  that  uses  the provided information to check the validity of the
29       argument types and values before the procedure body is executed.  Then,
30       the  information is used to generate help and usage texts if requested,
31       or to generate clear error  message  in  case  an  argument  validation
32       fails.  The  information also allows generating automatically graphical
33       forms that allows an interactive definition of all arguments, in case a
34       procedure is called interactively. And finally, the additional informa‐
35       tion helps self-commenting in a clean way the declaration of  a  proce‐
36       dure and of all its arguments.
37
38       The graphical form generator that creates the necessary argument speci‐
39       fication forms for the interactive procedure calls  is  also  available
40       for  other  purposes  than  for  procedure  argument specifications. It
41       allows creating code efficiently complex parameter entry forms that are
42       usable independently from TEPAM's new procedure definition method.
43
44       Here is a short overview about all major TEPAM features:
45
46       ·      New  self-documenting  procedure  declaration  syntax: The addi‐
47              tional information to declare properly a procedure has not to be
48              provided with additional statements, but can be added in a natu‐
49              ral syntax directly into the procedure header.
50
51       ·      Easy way to specify subcommands: A subcommand is declared like a
52              procedure,  simply with a procedure name composed by a base name
53              followed by a subcommand name. Sub-subcommands are created iden‐
54              tically using simply procedure names composed by 3 words.
55
56       ·      Flexible  usage  of  flags (switches), options (named arguments)
57              and unnamed arguments. Option names are optionally automatically
58              completed.
59
60       ·      Support for default values, mandatory/optional options and argu‐
61              ments, choice lists, value ranges, multiple usable options/argu‐
62              ments.
63
64       ·      Choice  of a named arguments first, unnamed arguments later pro‐
65              cedure calling style (typical for Tcl commands) or of an unnamed
66              arguments  first,  named arguments later procedure calling style
67              (typical for Tk commands).
68
69       ·      In case the named arguments first, unnamed arguments later style
70              (Tcl)  is  selected:  Clear separation between options and argu‐
71              ments via the "--" flag. The unnamed arguments can optionally be
72              accessed as options (named arguments).
73
74       ·      Automatic type and value check before the procedure body is exe‐
75              cuted, taking into account validation ranges, choice  lists  and
76              custom validation commands. Generation of clear error message if
77              necessary.
78
79       ·      Many predefined types exist (integer,  boolean,  double,  color,
80              file, font, ...). Other application specific types can easily be
81              added.
82
83       ·      Automatic help and usage  text  generation  if  a  procedure  is
84              called with the -help flag.
85
86       ·      Automatic generation of an interactive argument definition form,
87              in case a procedure is called with the -interactive flag.
88
89       ·      Procedure calls can be logged which is useful to get for  inter‐
90              actively called procedures the command call lines.
91
92       ·      Powerful and code efficient generation of complex parameter def‐
93              inition forms.
94

PROCEDURE DECLARATION

96       TEPAM's procedure declaration syntax  is  simple  and  self-explaining.
97       Instead  of  declaring a procedure with the Tcl key word proc, a proce‐
98       dure is declared with the TEPAM command procedure which takes  as  proc
99       also 3 arguments: The procedure name, the procedure header and the pro‐
100       cedure body.
101
102       The following example declares the subcommand message of the  procedure
103       display. This command has several named and unnamed arguments:
104
105              tepam::procedure {display message} {
106                 -return            -
107                 -short_description "Displays a simple message box"
108                 -description       "This procedure allows displaying a configurable message box."
109                 -args {
110                    {-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
111                    {-font -type font -default {Arial 10 italic} -description "Message text font"}
112                    {-level -type integer -optional -range {1 10} -description "Message level"}
113                    {-fg -type color -default black -description "Message color"}
114                    {-bg -type color -optional -description "Background color"}
115                    {-no_border -type none -description "Use a splash window style (no border)"}
116                    {-log_file -type file -optional -description "Optional message log file"}
117                    {text -type string -multiple -description "Multiple text lines to display"}
118                 }
119              } {
120                 puts "display message:"
121                 foreach var {mtype font level fg bg no_border log_file text} {
122                    if {[info exists $var]} {
123                       puts  "  $var=[set $var]"
124                    }
125                 }
126              }
127       A  call  of  procedure  that  has  been declared in this way will first
128       invoke the TEPAM argument manager, before the procedure  body  is  exe‐
129       cuted.  The  argument  manager parses the provided arguments, validates
130       them, completes them eventually with some  default  values,  and  makes
131       them  finally  available  to  the procedure body as local variables. In
132       case an argument is missing or has a wrong type, the  argument  manager
133       generates an error message that explains the reason for the error.
134
135       As the example above shows, the TEPAM command procedure accepts subcom‐
136       mand definitions as procedure name and allows defining much more infor‐
137       mation  than  just  the  argument list inside the procedure header. The
138       procedure body on  the  other  hand  is  identical  between  a  command
139       declared with proc and a command declared with procedure.
140
141       The  procedure header allows defining in addition to the arguments some
142       procedure attributes, like a description,  information  concerning  the
143       return value, etc. This information is basically used for the automatic
144       generation of comprehensive help and usage texts.
145
146       A list of argument definition statements assigned to the -args argument
147       is defining the procedure arguments. Each argument definition statement
148       starts with the argument name, optionally  followed  by  some  argument
149       attributes.
150
151       Three types of arguments can be defined: Unnamed arguments, named argu‐
152       ments and flags. The distinction between the named  and  unnamed  argu‐
153       ments  is made by the first argument name character which is simply "-"
154       for named arguments. A flag is defined as named argument that  has  the
155       type  none.
156
157       Named  and  unnamed  arguments  are mandatory, unless they are declared
158       with the -optional flag and unless they have a default value  specified
159       with the -default option. Named arguments and the last unnamed argument
160       can have the attribute -multiple, which means that they can be  defined
161       multiple  times.  The expected argument data type is specified with the
162       -type option. TEPAM defines a large set of standard  data  types  which
163       can easily be completed with application specific data types.
164
165       The argument declaration order has only an importance for unnamed argu‐
166       ments that are by default parsed after the named arguments (Tcl style).
167       A  variable  allows  changing this behavior in a way that unnamed argu‐
168       ments are parsed first, before the named arguments (Tk style).
169

PROCEDURE HELP

171       The declared procedure can simply be called with the  -help  option  to
172       get the information about the usage of the procedure and its arguments:
173
174              display message -help
175                ->
176              NAME
177                    display message - Displays a simple message box
178              SYNOPSYS
179                    display message
180                          [-mtype <mtype>] :
181                             Message type, default: "Warning", choices: {Info Warning Error}
182                          [-font <font>] :
183                             Message text font, type: font, default: Arial 10 italic
184                          [-level <level>] :
185                             Message level, type: integer, range: 1..10
186                          [-fg <fg>] :
187                             Message color, type: color, default: black
188                          [-bg <bg>] :
189                             Background color, type: color
190                          [-no_border ] :
191                             Use a splash window style (no border)
192                          [-log_file <log_file>] :
193                             Optional message log file, type: file
194                          <text> :
195                             Multiple text lines to display, type: string
196              DESCRIPTION
197                    This procedure allows displaying a configurable message box.
198

PROCEDURE CALL

200       The specified procedure can be called in many ways. The following list‐
201       ing shows some valid procedure calls:
202
203              display message "The document hasn't yet been saved!"
204              -> display message:
205                   mtype=Warning
206                   font=Arial 10 italic
207                   fg=black
208                   no_border=0
209                   text={The document hasn't yet been saved!}
210
211              display message -fg red -bg black "Please save first the document"
212              -> display message:
213                   mtype=Warning
214                   font=Arial 10 italic
215                   fg=red
216                   bg=black
217                   no_border=0
218                   text={Please save first the document}
219
220              display message -mtype Error -no_border "Why is here no border?"
221              -> display message:
222                   mtype=Error
223                   font=Arial 10 italic
224                   fg=black
225                   no_border=1
226                   text={Why is here no border?}
227
228              display message -font {Courier 12} -level 10 \
229                 "Is there enough space?" "Reduce otherwise the font size!"
230              -> display message:
231                   mtype=Warning
232                   font=Courier 12
233                   level=10
234                   fg=black
235                   no_border=0
236                   text={Is there enough space?} {Reduce otherwise the font size!}
237       The next lines show how wrong arguments are recognized. The text  argu‐
238       ment that is mandatory is missing in the first procedure call:
239
240              display message -font {Courier 12}
241                -> display message: Required argument is missing: text
242       Only known arguments are accepted:
243
244              display message -category warning Hello
245                -> display message: Argument '-category' not known
246       Argument types are automatically checked and an error message is gener‐
247       ated in case the argument value has not the expected type:
248
249              display message -fg MyColor "Hello"
250                -> display message: Argument 'fg' requires type 'color'.  Provided value: 'MyColor'
251       Selection choices have to be respected ...
252
253              display message -mtype Fatal Hello
254                -> display message: Argument (mtype) has to be one of the  following elements: Info, Warning, Error
255       ... as well as valid value ranges:
256
257              display message -level 12 Hello
258                -> display message: Argument (level) has to be between 1 and 10
259

INTERACTIVE PROCEDURE CALLS

261       The most intuitive way to call the procedure  is  using  an  form  that
262       allows specifying all arguments interactively. This form will automati‐
263       cally be generated if the declared procedure is called with the -inter‐
264       active flag. To use this feature the Tk library has to be loaded.
265
266              display message -interactive
267       The  generated form contains for each argument a data entry widget that
268       is adapted to the argument type. Check  buttons  are  used  to  specify
269       flags,  radio  boxes  for  tiny  choice  lists, disjoint list boxes for
270       larger choice lists and files, directories, fonts  and  colors  can  be
271       selected with dedicated browsers.
272
273       After  acknowledging  the specified argument data via an OK button, the
274       entered data are first validated, before  the  provided  arguments  are
275       transformed into local variables and the procedure body is executed. In
276       case the entered data are invalid, a message appears and the  user  can
277       correct them until they are valid.
278
279       The procedure calls can optionally be logged in a variable. This is for
280       example useful to get the command call lines  of  interactively  called
281       procedures.
282

FLEXIBLE ARGUMENT DIALOG BOX

284       The  form  generator  that creates in the previous example the argument
285       dialog box for the interactive procedure call  is  also  available  for
286       other  purposes  than  for the definition of procedure arguments. If Tk
287       has been loaded TEPAM provides and argument dialog box that allows cre‐
288       ating complex parameter definition forms in a very efficient way.
289
290       The following example tries to illustrate the simplicity to create com‐
291       plex data entry forms. It creates an input mask that allows  specifying
292       a  file to copy, a destination folder as well as a checkbox that allows
293       specifying if an eventual existing file can be overwritten. Comfortable
294       browsers  can be used to select files and directories. And finally, the
295       form offers also the possibility to accept and decline  the  selection.
296       Here is the code snippet that is doing all this:
297
298              tepam::argument_dialogbox \
299                 -existingfile {-label "Source file" -variable SourceFile} \
300                 -existingdirectory {-label "Destination folder" -variable DestDir} \
301                 -checkbutton {-label "Overwrite existing file" -variable Overwrite}
302       The argument_dialogbox returns ok if the entered data are validated. It
303       will return cancel if the data entry has been canceled. After the vali‐
304       dation  of  the  entered  data,  the argument_dialogbox defines all the
305       specified variables with the entered data inside the calling context.
306
307       An argument_dialogbox requires a pair of arguments  for  each  variable
308       that it has to handle. The first argument defines the entry widget type
309       used to select the variable's value and the second one is  a  lists  of
310       attributes related to the variable and the entry widget.
311
312       Many  entry  widget  types  are  available:  Beside  the simple generic
313       entries, there are different kinds of list and combo  boxes  available,
314       browsers  for  existing  and new files and directories, check and radio
315       boxes and buttons, as well as color and  font  pickers.  If  necessary,
316       additional entry widgets can be defined.
317
318       The  attribute  list  contains  pairs  of attribute names and attribute
319       data. The primary attribute is -variable used to specify  the  variable
320       in  the  calling  context into which the entered data has to be stored.
321       Another often used attribute is -label that allows adding  a  label  to
322       the data entry widget. Other attributes are available that allow speci‐
323       fying default values, the expected data types, valid data ranges, etc.
324
325       The next example of a more complex argument dialog box provides a  good
326       overview about the different available entry widget types and parameter
327       attributes. The example contains also some formatting instructions like
328       -frame  and -sep which allows organizing the different entry widgets in
329       frames and sections:
330
331              set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"}
332
333              set Result [tepam::argument_dialogbox \
334                 -title "System configuration" \
335                 -context test_1 \
336                 -frame {-label "Entries"} \
337                    -entry {-label Entry1 -variable Entry1} \
338                    -entry {-label Entry2 -variable Entry2 -default "my default"} \
339                 -frame {-label "Listbox & combobox"} \
340                    -listbox {-label "Listbox, single selection" -variable Listbox1 \
341                              -choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \
342                    -listbox {-label "Listbox, multiple selection" -variable Listbox2
343                              -choicevariable ChoiceList -default {"Choice 2" "Choice 3"}
344                              -multiple_selection 1 -height 3} \
345                    -disjointlistbox {-label "Disjoined listbox" -variable DisJntListbox
346                                      -choicevariable ChoiceList \
347                                      -default {"Choice 3" "Choice 5"} -height 3} \
348                    -combobox {-label "Combobox" -variable Combobox \
349                               -choices {1 2 3 4 5 6 7 8} -default 3} \
350                 -frame {-label "Checkbox, radiobox and checkbutton"} \
351                    -checkbox {-label Checkbox -variable Checkbox
352                               -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
353                               -default italic} \
354                    -radiobox {-label Radiobox -variable Radiobox
355                               -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
356                               -default underline} \
357                    -checkbutton {-label CheckButton -variable Checkbutton -default 1} \
358                 -frame {-label "Files & directories"} \
359                    -existingfile {-label "Input file" -variable InputFile} \
360                    -file {-label "Output file" -variable OutputFile} \
361                    -sep {} \
362                    -existingdirectory {-label "Input directory" -variable InputDirectory} \
363                    -directory {-label "Output irectory" -variable OutputDirectory} \
364                 -frame {-label "Colors and fonts"} \
365                    -color {-label "Background color" -variable Color -default red} \
366                    -sep {} \
367                    -font {-label "Font" -variable Font -default {Courier 12 italic}}]
368       The argument_dialogbox defines all the  specified  variables  with  the
369       entered  data and returns ok if the data have been validated via the Ok
370       button. If the data entry is cancelled by activating the Cancel button,
371       the argument_dialogbox returns cancel.
372
373              if {$Result=="cancel"} {
374                 puts "Canceled"
375              } else { # $Result=="ok"
376                 puts "Arguments: "
377                 foreach Var {
378                    Entry1 Entry2
379                    Listbox1 Listbox2 DisJntListbox
380                    Combobox Checkbox Radiobox Checkbutton
381                    InputFile OutputFile InputDirectory OutputDirectory
382                    Color Font
383                 } {
384                    puts "  $Var: '[set $Var]'"
385                 }
386              }
387              -> Arguments:
388                 Entry1: 'Hello, this is a trial'
389                 Entry2: 'my default'
390                 Listbox1: '1'
391                 Listbox2: '{Choice 2} {Choice 3}'
392                 DisJntListbox: '{Choice 3} {Choice 5}'
393                 Combobox: '3'
394                 Checkbox: 'italic'
395                 Radiobox: 'underline'
396                 Checkbutton: '1'
397                 InputFile: 'c:\tepam\in.txt'
398                 OutputFile: 'c:\tepam\out.txt'
399                 InputDirectory: 'c:\tepam\input'
400                 OutputDirectory: 'c:\tepam\output'
401                 Color: 'red'
402                 Font: 'Courier 12 italic'
403

SEE ALSO

405       tepam::argument_dialogbox(n), tepam::procedure(n)
406

KEYWORDS

408       argument integrity, argument validation, arguments, entry mask, parame‐
409       ter entry form, procedure, subcommand
410

CATEGORY

412       Procedures, arguments, parameters, options
413
415       Copyright (c) 2009-2013, Andreas Drollinger
416
417
418
419
420tcllib                               0.5.0                            tepam(n)
Impressum