1tepam(n) Tcl's Enhanced Procedure and Argument Manager tepam(n)
2______________________________________________________________________________
6
8 tepam - An introduction into TEPAM, Tcl's Enhanced Procedure and Argu‐
9 ment Manager
10
12 This document is an informal introduction into TEPAM, the Tcl's En‐
13 hanced 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
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, op‐
21 tions, unnamed arguments, optional and mandatory options and arguments,
22 default values, etc. Procedure declarations can be enriched with de‐
23 tailed information about the procedure and its arguments. This informa‐
24 tion is used for the following purposes:
25 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 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 al‐
41 lows creating code efficiently complex parameter entry forms that are
42 usable independently from TEPAM's new procedure definition method.
43 Here is a short overview about all major TEPAM features:
45 • 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 • 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 • Flexible usage of flags (switches), options (named arguments)
57 and unnamed arguments. Option names are optionally automatically
58 completed.
59 • Support for default values, mandatory/optional options and argu‐
61 ments, choice lists, value ranges, multiple usable options/argu‐
62 ments.
63 • 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 • 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 • 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 • Many predefined types exist (integer, boolean, double, color,
80 file, font, ...). Other application specific types can easily be
81 added.
82 • Automatic help and usage text generation if a procedure is
84 called with the -help flag.
85 • Automatic generation of an interactive argument definition form,
87 in case a procedure is called with the -interactive flag.
88 • Procedure calls can be logged which is useful to get for inter‐
90 actively called procedures the command call lines.
91 • Powerful and code efficient generation of complex parameter def‐
93 inition forms.
94
96 TEPAM's procedure declaration syntax is simple and self-explaining. In‐
97 stead of declaring a procedure with the Tcl key word proc, a procedure
98 is declared with the TEPAM command procedure which takes as proc also 3
99 arguments: The procedure name, the procedure header and the procedure
100 body.
101 The following example declares the subcommand message of the procedure
103 display. This command has several named and unnamed arguments:
104 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 in‐
128 voke the TEPAM argument manager, before the procedure body is executed.
129 The argument manager parses the provided arguments, validates them,
130 completes them eventually with some default values, and makes them fi‐
131 nally available to the procedure body as local variables. In case an
132 argument is missing or has a wrong type, the argument manager generates
133 an error message that explains the reason for the error.
134 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 de‐
139 clared with proc and a command declared with procedure.
140 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 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 at‐
149 tributes.
150 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 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 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
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 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
200 The specified procedure can be called in many ways. The following list‐
201 ing shows some valid procedure calls:
202 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 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 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 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 display message -font {Courier 12}
241 -> display message: Required argument is missing: text
242 Only known arguments are accepted:
243 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 display message -fg MyColor "Hello"
250 -> display message: Argument 'fg' requires type 'color'. Provided value: 'MyColor'
251 Selection choices have to be respected ...
252 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 display message -level 12 Hello
258 -> display message: Argument (level) has to be between 1 and 10
259
261 The most intuitive way to call the procedure is using an form that al‐
262 lows 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 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 se‐
271 lected with dedicated browsers.
272 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 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
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 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 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 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 Many entry widget types are available: Beside the simple generic en‐
313 tries, 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, ad‐
316 ditional entry widgets can be defined.
317 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 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 set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"}
332 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 en‐
369 tered 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 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
405 tepam::argument_dialogbox(n), tepam::procedure(n)
406
408 argument integrity, argument validation, arguments, entry mask, parame‐
409 ter entry form, procedure, subcommand
410
412 Procedures, arguments, parameters, options
413
415 Copyright (c) 2009-2013, Andreas Drollinger
416tcllib 0.5.0 tepam(n)