1 2[//000000001]: # (tepam::procedure \- Tcl's Enhanced Procedure and Argument Manager) 3[//000000002]: # (Generated from file 'tepam\_procedure\.man' by tcllib/doctools with format 'markdown') 4[//000000003]: # (Copyright © 2009\-2013, Andreas Drollinger) 5[//000000004]: # (tepam::procedure\(n\) 0\.5\.0 tcllib "Tcl's Enhanced Procedure and Argument Manager") 6 7<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a 8href="../../../toc.md">Table Of Contents</a> | <a 9href="../../../../index.md">Keyword Index</a> | <a 10href="../../../../toc0.md">Categories</a> | <a 11href="../../../../toc1.md">Modules</a> | <a 12href="../../../../toc2.md">Applications</a> ] <hr> 13 14# NAME 15 16tepam::procedure \- TEPAM procedure, reference manual 17 18# <a name='toc'></a>Table Of Contents 19 20 - [Table Of Contents](#toc) 21 22 - [Synopsis](#synopsis) 23 24 - [Description](#section1) 25 26 - [TERMINOLOGY](#section2) 27 28 - [PROCEDURE DECLARATION](#section3) 29 30 - [Procedure Attributes](#subsection1) 31 32 - [Argument Declaration](#subsection2) 33 34 - [VARIABLES](#section4) 35 36 - [ARGUMENT TYPES](#section5) 37 38 - [Predefined Argument Types](#subsection3) 39 40 - [Defining Application Specific Argument Types](#subsection4) 41 42 - [PROCEDURE CALLS](#section6) 43 44 - [Help](#subsection5) 45 46 - [Interactive Procedure Call](#subsection6) 47 48 - [Unnamed Arguments](#subsection7) 49 50 - [Named Arguments](#subsection8) 51 52 - [Unnamed Arguments First, Named Arguments Later \(Tk 53 Style\)](#subsection9) 54 55 - [Named Arguments First, Unnamed Arguments Later \(Tcl 56 Style\)](#subsection10) 57 58 - [Raw Argument List](#subsection11) 59 60 - [See Also](#seealso) 61 62 - [Keywords](#keywords) 63 64 - [Category](#category) 65 66 - [Copyright](#copyright) 67 68# <a name='synopsis'></a>SYNOPSIS 69 70package require Tcl 8\.3 71package require tepam ?0\.5? 72 73[__tepam::procedure__ *name* *attributes* *body*](#1) 74 75# <a name='description'></a>DESCRIPTION 76 77This package provides an alternative way to declare Tcl procedures and to manage 78its arguments\. There is a lot of benefit to declare a procedure with TEPAM 79rather than with the Tcl standard command __proc__: TEPAM allows specifying 80inside the procedure declaration all information that is required to generate 81comprehensive documentations and help support\. The information is also used by 82an automatically invoked argument checker that validates the provided procedure 83arguments before the procedure body is executed\. Finally, a procedure can be 84called interactively which will open a graphical form that allows specifying the 85procedure arguments\. 86 87TEPAM simplifies also the handling of the different types of argument, like the 88*named arguments* \(often also called *options*\) and the *unnamed 89arguments*\. TEPAM supports the *named first, unnamed later* style \(typical 90Tcl command style\) as well as also the *unnamed first, named later* style 91\(typical Tk command style\)\. TEPAM takes care about default values for arguments, 92optional arguments, multiple applicable arguments, etc\. and eliminates the need 93to check the validity of the argument inside the procedure bodies\. 94 95An informal overview of all the TEPAM procedure declaration and calling features 96as well as a short introduction into TEPAM is provided by *tepam\(n\)*\. 97 98# <a name='section2'></a>TERMINOLOGY 99 100The exact meaning of several terms that are used in this document will be 101shortly explained to avoid any ambiguities and misunderstandings\. 102 103 - *Subcommand* 104 105 The usage of subcommands is heavily used in the Tcl language\. Several 106 commands are incorporated into a single main command and are selectable via 107 the first argument\. 108 109 The __string__ command is an example of such a command that implements 110 for example subcommands to check a character string length, to compare 111 strings, to extract substrings, etc: 112 113 > __string length__ *string* 114 > __string compare__ *string* *string* 115 > __string range__ *string* *first* *last* 116 > \.\.\. 117 118 TEPAM provides a framework that allows implementing easily such subcommands 119 in form of Tcl procedures\. It allows not only defining a first level of 120 subcommands, but also a higher level of subcommands\. The __string__ 121 command class check could be implemented as independent sub\-sub\-commands of 122 the __string__ command: 123 124 > __string is alnum__ *string* 125 > __string is integer__ *string* 126 > __string is double__ *string* 127 > \.\.\. 128 129 - *Procedure attribute* 130 131 TEPAM allows attaching to a declared procedure different kind of attributes\. 132 Some of these attributes are *just* used for documentation purposes, but 133 other attributes specify the way how the procedure has to be called\. Also 134 the procedure arguments are defined in form of a procedure attribute\. 135 136 - *Argument* 137 138 TEPAM uses the term *argument* for the parameters of a procedure\. 139 140 The following example calls the subcommand __string compare__ with 141 several arguments: 142 143 > __string compare__ *\-nocase \-length 3 "emphasized" "emphasised"* 144 145 The following paragraphs discuss these different argument types\. 146 147 - *Named argument* 148 149 Some parameters, as *\-length 3* of the subcommand __string compare__ 150 have to be provided as pairs of argument names and argument values\. This 151 parameter type is often also called *option*\. 152 153 TEPAM uses the term *named argument* for such options as well as for the 154 flags \(see next item\)\. 155 156 - *Flag, switch* 157 158 Another parameter type is the *flag* or the *switch*\. Flags are provided 159 simply by naming the flag leading with the '\-' character\. The *\-nocase* of 160 the previous __string compare__ example is such a flag\. 161 162 *Flags* are considered by TEPAM like a special form of *named 163 arguments*\. 164 165 - *Unnamed argument* 166 167 For the other parameters, e\.g\. the ones for which the argument name has not 168 to be mentioned, TEPAM uses the term *unnamed argument*\. The previous 169 __string compare__ example uses for the two provided character strings 170 two *unnamed arguments*\. 171 172 - *Argument attribute* 173 174 TEPAM allows describing the purpose of each procedure argument with 175 *argument attributes*\. While some of them are just documenting the 176 attributes, most attributes are used by an argument manager to control and 177 validate the arguments that are provided during a procedure call\. Argument 178 attributes are used to specify default values, parameter classes \(integer, 179 xdigit, font, \.\.\.\), choice validation lists, value ranges, etc\. 180 181 - *Named arguments first, unnamed arguments later* 182 183 The __string compare__ command of the previous example requires that the 184 *named arguments* \(options, flags\) are provided first\. The two mandatory 185 \(unnamed\) arguments have to be provided as last argument\. 186 187 > __string compare__ *\-nocase \-length 3 Water $Text* 188 189 This is the usual Tcl style \(exceptions exist\) which is referred in the 190 TEPAM documentation as *named arguments first, unnamed arguments later 191 style*\. 192 193 - *Unnamed arguments first, named arguments later* 194 195 In contrast to most Tcl commands, Tk uses generally \(exceptions exist also 196 here\) a different calling style where the *unnamed arguments* have to be 197 provided first, before the *named arguments* have to be provided: 198 199 > __pack__ *\.ent1 \.ent2 \-fill x \-expand yes \-side left* 200 201 This style is referred in the TEPAM documentation as *unnamed arguments 202 first, named arguments later style*\. 203 204# <a name='section3'></a>PROCEDURE DECLARATION 205 206TEPAM allows declaring new Tcl procedures with the command 207__tepam::procedure__ that has similar to the standard Tcl command 208__proc__ also 3 arguments: 209 210 - <a name='1'></a>__tepam::procedure__ *name* *attributes* *body* 211 212The TEPAM procedure declaration syntax is demonstrated by the following example: 213 214> __tepam::procedure__ \{display message\} \{ 215> \-short\_description 216> "Displays a simple message box" 217> \-description 218> "This procedure allows displaying a configurable\\ 219> message box\. The default message type that is\\ 220> created is a warning, but also errors and info can\\ 221> be generated\. 222> The procedure accepts multiple text lines\." 223> \-example 224> \{display message \-mtype Warning "Save first your job"\} 225> \-args \{ 226> \{\-mtype \-choices \{Info Warning Error\} \\ 227> \-default Warning \-description "Message type"\} 228> \{text \-type string \-multiple \\ 229> \-description "Multiple text lines to display"\} 230> \} 231> \} \{ 232> puts "Message type: $mtype" 233> puts "Message: $text" 234> \} 235 236The 3 arguments of __procedure__ are: 237 238 - *name* 239 240 The procedure name can be used in very flexible ways\. Procedure names can 241 have namespace qualifiers\. By providing a two element name list as procedure 242 name, a subcommand of a procedure will be declared\. It is even possible to 243 declare sub\-sub\-commands of a procedure by providing name lists with three 244 elements\. 245 246 Here are some valid procedure declarations using different procedure names 247 \(the attribute and body arguments are empty for simplicity\): 248 249> *\# Simple procedure name:* 250> tepam::procedure __display\_message__ \{\} \{\} 251> ** 252> *\# Procedure declared in the main namespace:* 253> tepam::procedure __::display\_message__ \{\} \{\} 254> ** 255> *\# Procedure in the namespace* __::ns__*:* 256> tepam::procedure __::ns::display\_message__ \{\} \{\} 257> ** 258> *\# Declaration of the subcommand* __message__ *of the procedure* __display__*:* 259> tepam::procedure __\{display message\}__ \{\} \{\} 260 261 - *attributes* 262 263 All procedure attributes are provided in form of an option list that 264 contains pairs of option names and option values\. The example above has as 265 procedure attribute a short and a normal description, but also the procedure 266 arguments are defined in form of a procedure attribute\. 267 268 Most procedure attributes are providing information for documentation 269 purposes\. But some of them affect also the way how the procedure can be 270 called\. The section [Procedure Attributes](#subsection1) discusses in 271 detail the available procedure attributes\. 272 273 The procedure arguments are defined in form of a special procedure 274 attribute\. Most of the information provided in the argument definition is 275 not just used for documentation purposes\. This information is in fact used 276 by the TEPAM argument manager to handle and validate the various forms of 277 arguments that are provided during the procedure calls\. The section 278 [Argument Declaration](#subsection2) discusses in detail all the 279 argument definition attributes\. 280 281 - *body* 282 283 This is the normal procedure body\. The declared arguments will be available 284 to the procedure body in form of variables\. 285 286 The procedure body will only be executed if the provided set of arguments 287 could be validated by the TEPAM argument manager\. 288 289> tepam::procedure \{display\_message\} \{ 290> \-args \{ 291> \{\-__mtype__ \-default Warning \-choices \{Warning Error\}\} 292> \{__text__ \-type string\} 293> \} 294> \} \{ 295> puts "Message type: __$mtype__" 296> puts "Message: __$text__" 297> \} 298 299The commands __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ as well as 300__argument\_dialogbox__ are exported from the namespace __tepam__\. To use 301these commands without the __tepam::__ namespace prefix, it is sufficient to 302import them into the main namespace: 303 304> __namespace import tepam::\*__ 305> 306> __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ \{display\_message\} \{ 307> \-args \{ 308> \.\.\. 309 310## <a name='subsection1'></a>Procedure Attributes 311 312The first group of attributes affect the behavior of the declared procedure: 313 314 - \-named\_arguments\_first __0__|__1__ 315 316 This attribute defines the calling style of a procedure\. TEPAM uses by 317 default the *named arguments first, unnamed arguments later* style \(Tcl\)\. 318 This default behavior can globally be changed by setting the variable 319 __tepam::named\_arguments\_first__ to __0__\. This global calling style 320 can be changed individually for a procedure with the 321 *\-named\_arguments\_first* attribute\. 322 323 - \-auto\_argument\_name\_completion __0__|__1__ 324 325 The declared procedures will by default automatically try to match 326 eventually abbreviated argument names to the defined arguments names\. This 327 default behavior can globally be changed by setting the variable 328 __tepam::auto\_argument\_name\_completion__ to __0__\. This global 329 setting of the automatic argument name completion can be changed 330 individually for a procedure with the *\-auto\_argument\_name\_completion* 331 procedure attribute\. 332 333 - \-interactive\_display\_format __extended__|__short__ 334 335 A procedure declared with the TEPAM __procedure__ command can always be 336 called with the __\-interactive__ option\. By doing so, a graphical form 337 will be generated that allows specifying all procedure argument values\. 338 There are two display modes for these interactive forms\. While the 339 *extended* mode is more adapted for small procedure argument sets, the 340 __short__ form is more adequate for huge procedure argument sets\. 341 342 The choice to use short or extended forms can be globally configured via the 343 variable __tepam::interactive\_display\_format__\. This global setting can 344 then be changed individually for a procedure with the 345 *\-interactive\_display\_format* procedure attribute\. 346 347 - \-args *list* 348 349 The procedure arguments are declared via the *\-args* attribute\. An 350 argument is defined via a list having as first element the argument name, 351 followed by eventual argument attributes\. All these argument definition 352 lists are packaged themselves into a global list that is assigned to the 353 *\-args* attribute\. 354 355 The argument definition syntax will be described more in detail in the 356 following sub section\. 357 358The next attributes allow specifying custom argument checks as well as custom 359error messages in case these checks are failing: 360 361 - \-validatecommand *script* 362 363 Custom argument validations can be performed via specific validation 364 commands that are defined with the *\-validatecommand* attribute\. 365 366 Validation command declaration example: 367 368> tepam::procedure \{display\_message\} \{ 369> \-args \{ 370> \{text \-type string \-description "Message text"\} \} 371> __\-validatecommand \{IllegalWordDetector $text\}__ 372> \} \{ 373> \} 374 375 The validation command is executed in the context of the declared procedure 376 body\. The different argument values are accessed via the argument names\. 377 Note there is also an argument attribute *\-validatecommand* that allows 378 declaring custom checks for specific arguments\. 379 380 The attribute *\-validatecommand* can be repeated to declare multiple 381 custom checks\. 382 383 - \-validatecommand\_error\_text *string* 384 385 This attribute allows overriding the default error message for a custom 386 argument validation \(defined by *\-validatecommand*\)\. Also this attribute 387 can be repeated in case multiple argument checks are declared\. 388 389The following attribute allows controlling the logging settings for an 390individual procedure: 391 392 - \-command\_log __0__|__1__|__"interactive"__ 393 394 This argument configures the logging of the procedure calls into the list 395 variable __tepam::ProcedureCallLogList__\. The default configuration 396 defined by the variable __tepam::command\_log__ will be used if this 397 argument is not defined in a procedure declaration\. 398 399 Setting this argument to __0__ will disable any procedure call loggings, 400 setting it to __1__ will log any procedure calls and setting it to 401 __interactive__ will log just the procedures that are called 402 interactively \(procedures called with the __\-interactive__ flag\)\. 403 404The next group of procedure attributes is just used for the purpose of 405documentation and help text generation: 406 407 - \-category *string* 408 409 A category can be assigned to a procedure for documentation purposes\. Any 410 string is accepted as category\. 411 412 - \-short\_description *string* 413 414 The short description of a procedure is used in the documentation summary of 415 a generated procedure list as well as in the NAME section of a generated 416 procedure manual page\. 417 418 - \-description *string* 419 420 The \(full\) description assigned to a procedure is used to create user manual 421 and help pages\. 422 423 - \-return *string* 424 425 The *\-return* attribute allows defining the expected return value of a 426 procedure \(used for documentation purposes\)\. 427 428 - \-example *string* 429 430 A help text or manual page of a procedure can be enriched with eventual 431 examples, using the *\-example* attribute\. 432 433## <a name='subsection2'></a>Argument Declaration 434 435The following example shows the structure that is used for the argument 436definitions in the context of a procedure declaration: 437 438> tepam::procedure \{display\_message\} \{ 439> \-args __\{__ 440> __\{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}__ 441> __\{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}__ 442> __\{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}__ 443> __\{\-fg \-type color \-optional \-description "Message color"\}__ 444> __\{\-log\_file \-type file \-optional \-description "Optional message log file"\}__ 445> __\{text \-type string \-multiple \-description "Multiple text lines to display"\}__ 446> __\}__ 447> 448> \} \{ 449> \} 450 451Each of the procedure arguments is declared with a list that has as first 452element the argument name, followed by eventual attributes\. The argument 453definition syntax can be formalized in the following way: 454 455> tepam::procedure <name> \{ 456> \-args __\{__ 457> __\{<argument\_name\_1> <arg\_attr\_name\_1a> <arg\_attr\_value\_1a> <arg\_attr\_name\_1b> <arg\_attr\_value\_1b> \.\.\.\}__ 458> __\{<argument\_name\_2> <arg\_attr\_name\_2a> <arg\_attr\_value\_2a> <arg\_attr\_name\_2b> <arg\_attr\_value\_2b> \.\.\.\}__ 459> __\.\.\.__ 460> __\}__ 461> 462> \} <body> 463 464The argument names and attributes have to be used in the following way: 465 466 - Argument name \(*<argument\_name\_<n>>*\) 467 468 The provided argument name specifies whether the argument is an *unnamed 469 argument* or a *named argument*\. In addition to this, an argument name 470 can also be blank to indicate an argument comment, or it can start with \# to 471 indicate a section comment\. 472 473 * *"<Name>"* 474 475 This is the simplest form of an argument name: An argument whose name is 476 not starting with '\-' is an *unnamed argument*\. The parameter provided 477 during a procedure call will be assigned to a variable with the name 478 *<Name>*\. 479 480> tepam::procedure \{print\_string\} \{ 481> \-args \{ 482> \{__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ \-type string \-description "This is an unnamed argument"\} 483> \} 484> \} \{ 485> puts __$text__ 486> \} 487> 488> print\_string __"Hello"__ 489> *\-> Hello* 490 491 * *"\-<Name>"* 492 493 An argument whose name starts with '\-' is a *named argument* \(also 494 called *option*\)\. The parameter provided during a procedure call will 495 be assigned to a variable with the name *<Name>* \(not *\-<Name>*\)\. 496 497> tepam::procedure \{print\_string\} \{ 498> \-args \{ 499> \{__\-text__ \-type string \-description "This is a named argument"\} 500> \} 501> \} \{ 502> puts __$text__ 503> \} 504> 505> print\_string __\-text "Hello"__ 506> *\-> Hello* 507 508 * *"\-\-"* 509 510 This flag allows clearly specifying the end of the named arguments and 511 the beginning of the unnamed arguments, in case the *named arguments 512 first, unnamed arguments later style \(Tcl\)* has been selected\. 513 514 If the *unnamed arguments first, named arguments later style \(Tk\)* 515 style is selected, this flag is ignored if the unnamed arguments have 516 already been parsed\. Otherwise it will be assigned to the corresponding 517 unnamed argument\. 518 519 * *"\-"* or *""* 520 521 A blank argument name \(either '\-' or *''*\) starts a comment for the 522 following arguments\. 523 524> tepam::procedure \{print\_time\} \{ 525> \-interactive\_display\_format short 526> \-args \{ 527> \{hours \-type integer \-description "Hour"\} 528> \{minutes \-type integer \-description "Minute"\} 529> 530> __\{\- The following arguments are optional:\}__ 531> \{seconds \-type integer \-default 0 \-description "Seconds"\} 532> \{milliseconds \-type integer \-default 0 \-description "Milliseconds"\} 533> \} 534> \} \{ 535> puts "$\{hour\}h$\{minutes\}:\[expr $seconds\+0\.001\*$milliseconds\]" 536> \} 537 538 Argument comments are basically used in the graphical argument 539 definition forms that are created if a procedure is called 540 interactively\. 541 542 * *"\#\*"* 543 544 An argument definition list that starts with '\#' is considered as a 545 section comment\. The argument definition list will be trimmed from the 546 '\#' characters and the remaining string will be used as section comment\. 547 548 Section comments can be used to structure visually the argument 549 definition code\. Section comments are also used to structure the 550 generated help texts and the interactive argument definition forms\. 551 552> tepam::procedure \{complex\_multiply\} \{ 553> \-description "This function perform a complex multiplication" 554> \-args \{ 555> __\{\#\#\#\# First complex number \#\#\#\#\}__ 556> \{\-r0 \-type double \-description "First number real part"\} 557> \{\-i0 \-type double \-description "First number imaginary part"\} 558> 559> __\{\#\#\#\# Second complex number \#\#\#\#\}__ 560> \{\-r1 \-type double \-description "Second number real part"\} 561> \{\-i1 \-type double \-description "Second number imaginary part"\} 562> \} 563> \} \{ 564> return \[expr $r0\*$r1 \- $i0\*$i1\] 565> \} 566 567 - Argument attributes \(*<arg\_attr\_name\_<mn>> <arg\_attr\_value\_<mn>>*\) 568 569 The following argument attributes are supported: 570 571 * \-description *string* 572 573 The description argument attribute is used for documentation purpose\. 574 Interactive argument definition forms use this attribute to provide 575 explanations for an argument\. 576 577 * \-type *type* 578 579 The type argument attribute allows assigning the argument either to a 580 predefined data type, or to an application specific data type\. The 581 argument values that are provided during a procedure call are 582 automatically checked with respect to the defined argument type\. 583 584 The section [ARGUMENT TYPES](#section5) provides a list of 585 predefined data types and explains how application specific types can be 586 specified\. 587 588 The argument type *none* has a special meaning\. An argument that has 589 the type *none* is handled as a *flag*\. A flag is always optional 590 and its related variable contains the logical value __1__ if the 591 flag has been defined during the procedure call, or otherwise __0__\. 592 593 * \-default *value* 594 595 Eventual default values can be defined with the \-default argument 596 attribute\. Arguments with default values are automatically optional 597 arguments\. 598 599 * \-optional|\-mandatory 600 601 Arguments are by default mandatory, unless a default value is defined\. 602 The flag *\-optional* transforms an argument into an optional argument\. 603 604 In case an optional argument is not defined during a procedure call, the 605 corresponding variable will not be defined\. The flag *\-mandatory* is 606 the opposite to *\-optional*\. This flag exists only for completion 607 reason, since an argument is anyway mandatory by default\. 608 609 * \-multiple 610 611 Arguments that have the *\-multiple* attribute can be defined multiple 612 times during a procedure call\. The values that are provided during a 613 procedure call for such an argument are stored in a list variable\. This 614 is even the case if such an argument is only defined once during a 615 procedure call\. 616 617 The *\-multiple* attribute can be attributed to unnamed arguments and 618 to named arguments\. The pair of argument name/argument value has to be 619 repeated for each provided value in case of a named argument\. In case 620 the argument with the *\-multiple* attribute is an unnamed argument, 621 this one has to be the absolute last one of all unnamed arguments\. 622 623 * \-choices *list* 624 625 A possible set of valid argument values can be attributed to an argument 626 via the *\-choices* attribute\. The argument value provided during a 627 procedure call will be checked against the provided choice values\. 628 629 * \-choicelabels *list* 630 631 An eventual short description can be attributed to each choice option 632 with the *\-choicelabels* attribute\. These descriptions will be used in 633 the generated help texts and as radio and check box labels for the 634 interactive calls\. 635 636 The *\-choicelabels* attribute is optional, but if it is defined, its 637 list needs to have the identical size as the *\-choices* argument list\. 638 639 * \-range *\{double double\}* 640 641 Another argument constraint can be defined with the *\-range* 642 attribute\. The valid range is defined with a list containing the minimum 643 valid value and a maximum valid value\. The *\-range* attribute has to 644 be used only for numerical arguments, like integers and doubles\. 645 646 * \-validatecommand *script* 647 648 Custom argument value validations can be performed via specific 649 validation commands that are defined with the *\-validatecommand* 650 attribute\. The provided validation command can be a complete script in 651 which the pattern *%P* is replaced by the argument value that has to 652 be validated\. 653 654 Validation command declaration example: 655 656> tepam::procedure \{display\_message\} \{ 657> \-args \{ 658> \{text \-type string \-description "Message text" \\ 659> __\-validatecommand \{IllegalWordDetector %P\}__\} 660> \} \{ 661> \} 662 663 While the purpose of this custom argument validation attribute is the 664 validation of a specific argument, there is also a global attribute 665 *\-validatecommand* that allows performing validation that involves 666 multiple arguments\. 667 668 * \-validatecommand\_error\_text *string* 669 670 This attribute allows overriding the default error message for a custom 671 argument validation \(defined by *\-validatecommand*\)\. 672 673 * \-widget *string* 674 675 The widgets that allow defining the different arguments in case of an 676 interactive procedure call are normally selected automatically in 677 function of the argument type\. The *\-widget* attribute allows 678 specifying explicitly a certain widget type for an argument\. 679 680 * \-auxargs *list* 681 682 In case a procedure is called interactively, additional argument 683 attributes can be provided to the interactive argument definition form 684 via the *\-auxargs* attribute that is itself a list of attribute 685 name/attribute value pairs: 686 687 -auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \ 688 -<arg_attr_name_1b> <arg_attr_value_1b> 689 ... 690 } 691 692 For example, if a procedure takes as argument a file name it may be 693 beneficial to specify the required file type for the interactive 694 argument definition form\. This information can be provided via the 695 *\-auxargs* attribute to the argument definition form: 696 697> tepam::procedure LoadPicture \{ 698> \-args \{ 699> \{FileName \-type existingfile \-description "Picture file" \\ 700> __\-auxargs \{\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\} \}\}__\} 701> \} 702> \} \{ 703> \} 704 705 * \-auxargs\_commands *script* 706 707 If the auxiliary argument attributes are not static but have to be 708 dynamically adaptable, the *\-auxargs\_commands* allows defining them 709 via commands that are executed during a procedure call\. A list of pairs 710 of auxiliary attribute names and commands has to be provided to the 711 *\-auxargs\_commands* attribute\. The provided commands are executed in 712 the context of the calling procedure\. 713 714 -auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \ 715 -<arg_attr_name_1b> <arg_attr_command_1b> 716 ... 717 } 718 719# <a name='section4'></a>VARIABLES 720 721Several variables defined inside the __::tepam__ namespace impact the mode 722of operation of the procedures that have been declared with the TEPAM 723__procedure__ command\. 724 725 - __named\_arguments\_first__ 726 727 This variable defines the general calling style of the procedures\. It is by 728 default set to __1__ which selects the *named arguments first, unnamed 729 arguments later* style \(Tcl style\)\. 730 731 By setting this variable to __0__, the *named arguments first, unnamed 732 arguments later* style is globally selected \(Tk style\): 733 734 set tepam::named_arguments_first 0 735 736 While this variable defines the general calling style, the procedure 737 attribute *\-named\_arguments\_first* can adapt this style individually for 738 each declared procedure\. 739 740 - __auto\_argument\_name\_completion__ 741 742 This variable controls the general automatic argument name matching mode\. By 743 default it is set to __1__, meaning that the called procedures are 744 trying to match eventually abbreviated argument names with the declared 745 argument names\. 746 747 By setting this variable to __0__ the automatic argument name matching 748 mode is disabled: 749 750 set tepam::auto_argument_name_completion 0 751 752 While this variable defines the general matching mode, the procedure 753 attribute *\-auto\_argument\_name\_completion* can adapt this mode 754 individually for each declared procedure\. 755 756 - __interactive\_display\_format__ 757 758 A procedure declared via the TEPAM __procedure__ command can always be 759 called with the __\-interactive__ switch\. By doing so, a graphical form 760 will be generated that allows entering interactively all procedure 761 arguments\. 762 763 There are two display modes for these interactive forms\. The *extended* 764 mode which is the default mode is more adapted for small procedure argument 765 sets\. The __short__ form is more adequate for huge procedure argument 766 sets: 767 768 set tepam::interactive_display_format "short" 769 770 The choice to use short or extended forms can be globally configured via the 771 variable __interactive\_display\_format__\. This global setting can be 772 changed individually for a procedure with the procedure attribute 773 *\-interactive\_display\_format*\. 774 775 - __help\_line\_length__ 776 777 The maximum line length used by the procedure help text generator can be 778 specified with this variable\. The default length which is set to 80 779 \(characters\) can easily be adapted to the need of an application: 780 781 set tepam::help_line_length 120 782 783 Since this variable is applied directly during the help text generation, its 784 value can continuously be adapted to the current need\. 785 786 - __command\_log__ 787 788 Procedure calls can be logged inside the list variable 789 __tepam::ProcedureCallLogList__\. The variable __tepam::command\_log__ 790 controls the default logging settings for any procedures\. The following 791 configurations are supported: 792 793 * *0*: Disables any procedure call loggings 794 795 * *1*: Enables any procedure call loggings 796 797 * *"interactive"*: Will log any procedures called interactively \(e\.g\. 798 procedures called with the \-interactive flag\)\. This is the default 799 configuration\. 800 801 This default logging configuration can be changed individually for each 802 procedure with the *\-command\_log* attribute\. 803 804# <a name='section5'></a>ARGUMENT TYPES 805 806TEPAM provides a comprehensive set of procedure argument types\. They can easily 807be completed with application specific types if necessary\. 808 809## <a name='subsection3'></a>Predefined Argument Types 810 811To remember, a type can be assigned to each specified procedure argument: 812 813> tepam::procedure \{warning\} \{ 814> \-args \{ 815> \{\-font __\-type font__ \-default \{Arial 10 italic\}\} 816> \{\-severity\_level __\-type integer__ \-optional \-range \{1 10\}\} 817> \{\-fg __\-type color__ \-optional \-description "Message color"\} 818> \{text __\-type string__ \-multiple \-description "Multiple text lines to display"\} 819> \} 820> \} \{ 821> \.\.\. 822> \} 823 824There are some *special purpose types* that are building the first category of 825predefined argument types: 826 827 - __none__ A *flag*, also called *switch*, is defined as a named 828 argument that has the type __none__\. Flags are always optional and the 829 default value of the assigned variable is set to __0__\. In contrast to 830 the \(normal\) named arguments, no argument value has to be provided to a 831 flag\. 832 833> tepam::procedure flag\_test \{ 834> \-args \{ 835> __\{\-flag \-type none \-description "This is a flag"\}__ 836> \} 837> \} \{ 838> puts __$flag__ 839> \} 840> 841> flag\_test 842> *\-> 0* 843> 844> flag\_test \-flag 845> *\-> 1* 846 847 Since no argument value has to be provided to a flag, also no data check is 848 performed for this argument type\. 849 850 - __string__ __String__ is a generic argument data type\. Any data 851 string can be provided to a string type argument and no data type checks are 852 therefore performed\. The string type allows defining single line strings 853 during the interactive procedure calls\. 854 855 - __text__ __Text__ is identical to __string__ with the only 856 difference that it allows entering multi line strings during interactive 857 procedure calls\. 858 859 - __\{\}__ A __blank__ argument type signifies an undefined argument 860 type\. This is the default argument type that will be used if no type has 861 been explicitly specified\. An argument that has a __blank__ type behaves 862 identically than an argument that has a __string__ type, e\.g\. no 863 argument data checks are performed\. The only difference is that the data 864 type __string__ is mentioned in the generated help documentation, while 865 this is not the case for the __blank__ type\. 866 867Several *numerical types* are defined by TEPAM\. The type validation procedures 868are using the __string is <type> \-strict__ commands to check the validity of 869the provided arguments, which assures that no empty strings are accepted as 870argument value\. The type validation expression for the numerical types and the 871argument types to which this expression is applied are: 872 873> string is __<type\_to\_check>__ \-strict *<argument\_value>* 874 875 - *boolean* 876 877 - *integer* 878 879 - *double* 880 881Empty strings are accepted as argument value for all the alpha numeric argument 882types\. The argument types that are falling into this category and validation 883expression used for them are: 884 885> string is *<type\_to\_check>* *<argument\_value>* 886 887 - *alnum* 888 889 - *alpha* 890 891 - *ascii* 892 893 - *control* 894 895 - *digit* 896 897 - *graph* 898 899 - *lower* 900 901 - *print* 902 903 - *punct* 904 905 - *space* 906 907 - *upper* 908 909 - *wordchar* 910 911 - *xdigit* 912 913In addition to the data types checked with the __string is <type>__ 914commands, TEPAM specifies some other useful data types: 915 916 - *char* Each string that has a length of 1 character meets the 917 *character* type\. The type check is made with the following expression: 918 919> expr \[string length *<argument\_value>*\]==1 920 921 - *color* Any character strings that are accepted by Tk as a color are 922 considered as valid color argument\. Please note that the Tk package has to 923 be loaded to use the type *color*\. TEPAM is using the following command to 924 validate the color type: 925 926> expr \!\[catch \{winfo rgb \. *<argument\_value>*\}\] 927 928 - *font* Any character strings that are accepted by Tk as a font are 929 considered as valid font argument\. Please note that the Tk package has to be 930 loaded to use the *font* type\. TEPAM is using the following command to 931 validate the color type: 932 933 expr ![catch {font measure <argument_value> ""}] 934 935 - *file* Any strings that are not containing one of the following characters 936 are considered as valid file names: \* ? " < >\. It is not necessary that the 937 file and its containing directory exist\. Zero\-length strings are not 938 considered as valid file names\. 939 940 The following expression is used to validate the file names: 941 942 expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>] 943 944 - *existingfile* The argument is valid if it matches with an existing file\. 945 The following check is performed to validate the arguments of this type: 946 947 file exists <argument_value> 948 949 - *directory* The directory argument is validated exactly in the same way as 950 the file arguments\. 951 952 - *existingdirectory* The argument is valid if it matches with an existing 953 directory\. The following check is performed to validate the arguments of 954 this type: 955 956 file isdirectory <argument_value> 957 958## <a name='subsection4'></a>Defining Application Specific Argument Types 959 960To add support for a new application specific argument type it is just necessary 961to add into the namespace __tepam__ a validation function 962__Validation\(<type>\)__\. This function requires one argument\. It has to 963returns __1__ if the provided argument matches with the relevant data type\. 964The function has to return otherwise __0__\. 965 966The validation command section of the "tepam\.tcl" package provides sufficient 967examples of validation functions, since it implements the ones for the standard 968TEPAM types\. 969 970The following additional code snippet shows the validation function for a custom 971argument type that requires values that have a character string length of 972exactly 2: 973 974 proc tepam::Validate(two_char) {v} {expr {[string length $v]==2}} 975 976# <a name='section6'></a>PROCEDURE CALLS 977 978## <a name='subsection5'></a>Help 979 980Each procedure can be called with the *\-help* flag\. The procedure will then 981print a generated help text to *stdout* and will then return without 982performing any additional actions\. 983 984Taking the first procedure declared in [PROCEDURE CALLS](#section6), the 985help request and the printed help text would be: 986 987> __display message \-help__ 988> *\->* 989> *NAME* 990> *display message \- Displays a simple message box* 991> *SYNOPSIS* 992> *display message* 993> *\[\-mtype <mtype>\]* 994> *Message type, default: "Warning", choices: \{Info, Warning, Error\}* 995> *<text>* 996> *Multiple text lines to display, type: string* 997> *DESCRIPTION* 998> *This procedure allows displaying a configurable message box\. The default* 999> *message type that is created is a warning, but also errors and info can* 1000> *be generated\.* 1001> *The procedure accepts multiple text lines\.* 1002> *EXAMPLE* 1003> *display message \-mtype Warning "Save first your job"* 1004 1005The argument manager is checking if the last provided argument is *\-help* and 1006generates the requested help message if this is the case\. So, also the following 1007example will print the help message: 1008 1009> __display message \-mtype Info "It is 7:00" \-help__ 1010 1011On the other hand, the following call will result in an error: 1012 1013> __display message \-help \-mtype Info "It is 7:00"__ 1014> *\->* 1015> *display message: Argument '\-help' not known* 1016 1017## <a name='subsection6'></a>Interactive Procedure Call 1018 1019If Tk has been loaded a procedure can be called with the *\-interactive* flag 1020to open a graphical form that allows specifying interactively all procedure 1021arguments\. The following example assures that the Tk library is loaded and shows 1022the command line to call interactively the procedure declared in [PROCEDURE 1023CALLS](#section6): 1024 1025> package require Tk 1026> __display message \-interactive__ 1027 1028Also the *\-interactive* flag has to be placed at the last argument position as 1029this is also required for the *\-help* flag\. Arguments defined before the 1030*\-interactive* flag will be ignored\. The following example is therefore also a 1031valid interactive procedure call: 1032 1033> __display message__ \-mtype Info "It is 7:00" __\-interactive__ 1034 1035## <a name='subsection7'></a>Unnamed Arguments 1036 1037Unnamed arguments are typically provided to the called procedure as simple 1038parameters\. This procedure calling form requires that the provided arguments are 1039strictly following the order of the specified arguments\. Several parameters can 1040be assigned to the last argument if this one has the *\-multiple* attribute\. 1041So, the following declared procedure \.\.\. 1042 1043 tepam::procedure {display_message} { 1044 -args { 1045 {mtype -choices {Info Warning Error}} 1046 {text -type string -multiple} 1047 } 1048 } { 1049 puts "$mtype: [join $text]" 1050 } 1051 1052\.\.\. can for example be called in the following ways: 1053 1054> __display\_message Info "It is PM 7:00\."__ 1055> *\-> Info: It is PM 7:00\.* 1056> 1057> __display\_message Info "It is PM 7:00\." "You should go home\."__ 1058> *\-> Info: It is PM 7:00\. You should go home\.* 1059 1060The nice thing is that unnamed arguments can also be called as named arguments, 1061which can be handy, for example if the exact specified argument order is not 1062known to a user: 1063 1064> __display\_message \-mtype Info \-text "It is PM 7:00\."__ 1065> *\-> Info: It is PM 7:00\.* 1066> 1067> __display\_message \-text "It is PM 7:00\." \-mtype Info__ 1068> *\-> Info: It is PM 7:00\.* 1069> 1070> __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__ 1071> *\-> Info: It is PM 7:00\. You should go home\.* 1072> 1073> __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__ 1074> *\-> Info: It is PM 7:00\. You should go home\.* 1075 1076## <a name='subsection8'></a>Named Arguments 1077 1078Named arguments have to be provided to a procedure in form of a parameter pairs 1079composed by the argument names and the argument values\. The order how they are 1080provided during a procedure call is irrelevant and has not to match with the 1081argument specification order\. 1082 1083The following declared procedure \.\.\. 1084 1085 tepam::procedure {display_message} { 1086 -args { 1087 {-mtype -choices {Info Warning Error}} 1088 {-text -type string -multiple} 1089 } 1090 } { 1091 puts "$mtype: [join $text]" 1092 } 1093 1094\.\.\. can be called in the following ways: 1095 1096> __display\_message \-mtype Info \-text "It is PM 7:00\."__ 1097> *\-> Info: It is PM 7:00\.* 1098> 1099> __display\_message \-text "It is PM 7:00\." \-mtype Info__ 1100> *\-> Info: It is PM 7:00\.* 1101> 1102> __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__ 1103> *\-> Info: It is PM 7:00\. You should go home\.* 1104> 1105> __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__ 1106> *\-> Info: It is PM 7:00\. You should go home\.* 1107 1108Also named arguments that have not the *\-multiple* attribute can be provided 1109multiple times\. Only the last provided argument will be retained in such a case: 1110 1111> __display\_message \-mtype Info \-text "It is PM 7:00\." \-mtype Warning__ 1112> *\-> Warning: It is PM 7:00\.* 1113 1114## <a name='subsection9'></a>Unnamed Arguments First, Named Arguments Later \(Tk Style\) 1115 1116A procedure that has been defined while the variable 1117__tepam::named\_arguments\_first__ was set to 1, or with the procedure 1118attribute *\-named\_arguments\_first* set to 1 has to be called in the Tcl style\. 1119The following procedure declaration will be used in this section to illustrate 1120the meaning of this calling style: 1121 1122> __set tepam::named\_arguments\_first 1__ 1123> tepam::procedure my\_proc \{ 1124> \-args \{ 1125> \{\-n1 \-default ""\} 1126> \{\-n2 \-default ""\} 1127> \{u1 \-default ""\} 1128> \{u2 \-default ""\} 1129> \} 1130> \} \{ 1131> puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" 1132> \} 1133 1134The unnamed arguments are placed at the end of procedure call, after the named 1135arguments: 1136 1137> my\_proc __\-n1 N1 \-n2 N2 U1 U2__ 1138> *\-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'* 1139 1140The argument parser considers the first argument that doesn't start with the '\-' 1141character as well as all following arguments as unnamed argument: 1142 1143> my\_proc __U1 U2__ 1144> *\-> n1:'', n2:'', u1:'U1', u2:'U2'* 1145 1146Named arguments can be defined multiple times\. If the named argument has the 1147*\-multiply* attribute, all argument values will be collected in a list\. 1148Otherwise, only the last provided attribute value will be retained: 1149 1150> my\_proc __\-n1 N1 \-n2 N2 \-n1 M1 U1 U2__ 1151> *\-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'* 1152 1153The name of the first unnamed argument has therefore not to start with the '\-' 1154character\. The unnamed argument is otherwise considered as name of another named 1155argument\. This is especially important if the first unnamed argument is given by 1156a variable that can contain any character strings: 1157 1158> my\_proc __\-n1 N1 \-n2 N2 "\->" "<\-"__ 1159> *\-> my\_proc: Argument '\->' not known* 1160> 1161> set U1 "\->" 1162> my\_proc __\-n1 N1 \-n2 N2 $U1 U2__ 1163> my\_proc: Argument '\->' not known 1164 1165The '\-\-' flag allows separating unambiguously the unnamed arguments from the 1166named arguments\. All data after the '\-\-' flag will be considered as unnamed 1167argument: 1168 1169> my\_proc __\-n1 N1 \-n2 N2 \-\- "\->" "<\-"__ 1170> *\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'* 1171> 1172> set U1 "\->" 1173> my\_proc __\-n1 N1 \-n2 N2 \-\- $U1 U2__ 1174> *\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'* 1175 1176## <a name='subsection10'></a>Named Arguments First, Unnamed Arguments Later \(Tcl Style\) 1177 1178The Tk calling style will be chosen if a procedure is defined while the variable 1179__tepam::named\_arguments\_first__ is set to 0, or if the procedure attribute 1180*\-named\_arguments\_first* has been set to 0\. The following procedure will be 1181used in this section to illustrate this calling style: 1182 1183> __set tepam::named\_arguments\_first 0__ 1184> tepam::procedure my\_proc \{ 1185> \-args \{ 1186> \{\-n1 \-default ""\} 1187> \{\-n2 \-default ""\} 1188> \{u1\} 1189> \{u2 \-default "" \-multiple\} 1190> \} 1191> \} \{ 1192> puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" 1193> \} 1194 1195The unnamed arguments have to be provided first in this case\. The named 1196arguments are provided afterwards: 1197 1198> my\_proc __U1 U2 \-n1 N1 \-n2 N2__ 1199> *\-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'* 1200 1201The argument parser will assign to each defined unnamed argument a value before 1202it switches to read the named arguments\. This default behavior changes a bit if 1203there are unnamed arguments that are optional or that can take multiple values\. 1204 1205An argument value will only be assigned to an unnamed argument that is optional 1206\(that has either the *\-optional* attribute or that has a default value\), if 1207the value is not beginning with the '\-' character or if no named arguments are 1208defined\. The value that starts with '\-' is otherwise considered as the name of a 1209named argument\. 1210 1211Argument values are assigned to an argument that has the *\-multiple* attribute 1212as long as the parameter value doesn't starts with the '\-' character\. 1213 1214Values that start with the '\-' character can therefore not be assigned to 1215optional unnamed arguments, which restricts the usage of the Tcl procedure 1216calling style\. The Tk style may be preferable in some cases, since it allows 1217separating unambiguously the named arguments from the unnamed ones with the '\-\-' 1218flag\. 1219 1220Let's explore in a bit less theoretically the ways how the previously defined 1221procedure can be called: The first example calls the procedure without any 1222parameters, which leads to an error since *u1* is a mandatory argument: 1223 1224> my\_proc 1225> *\-> my\_proc: Required argument is missing: u1* 1226 1227The procedure call is valid if one parameter is provided for *u1*: 1228 1229> my\_proc __U1__ 1230> *\-> n1:'', n2:'', u1:'U1', u2:''* 1231 1232If more parameters are provided that are not starting with the '\-' character, 1233they will be attributed to the unnamed arguments\. *U2* will receive 3 of these 1234parameters, since it accepts multiple values: 1235 1236> my\_proc __U1 U2 U3 U4__ 1237> *\-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'* 1238 1239As soon as one parameter starts with '\-' and all unnamed arguments have been 1240assigned, the argument manager tries to interpret the parameter as name of a 1241named argument\. The procedure call will fail if a value beginning with '\-' is 1242assigned to an unnamed argument: 1243 1244> my\_proc __U1 U2 U3 U4 \-U5__ 1245> *\-> my\_proc: Argument '\-U5' not known* 1246 1247The attribution of a parameter to a named argument will fail if there are 1248undefined unnamed \(non optional\) arguments\. The name specification will in this 1249case simply be considered as a parameter value that is attributed to the 1250*next* unnamed argument\. This was certainly not the intention in the following 1251example: 1252 1253> my\_proc __\-n1 N1__ 1254> *\-> n1:'', n2:'', u1:'\-n1', u2:'N1'* 1255 1256The situation is completely different if values have already been assigned to 1257all mandatory unnamed arguments\. A parameter beginning with the '\-' character 1258will in this case be considered as a name identifier for a named argument: 1259 1260> my\_proc __U1 \-n1 N1__ 1261> *\-> n1:'N1', n2:'', u1:'U1', u2:''* 1262 1263No unnamed arguments are allowed behind the named arguments: 1264 1265> my\_proc __U1 \-n1 N1 U2__ 1266> *\-> my\_proc: Argument 'U2' is not an option* 1267 1268The '\-\-' flag has no special meaning if not all mandatory arguments have got 1269assigned a value\. This flag will simply be attributed to one of the unnamed 1270arguments: 1271 1272> my\_proc __\-\- \-n1 N1__ 1273> *\-> n1:'N1', n2:'', u1:'\-\-', u2:''* 1274 1275But the '\-\-' flag is simply ignored if the argument parser has started to handle 1276the named arguments: 1277 1278> my\_proc __U1 \-\- \-n1 N1__ 1279> *\-> n1:'N1', n2:'', u1:'U1', u2:''* 1280> 1281> my\_proc __U1 \-n1 N1 \-\- \-n2 N2__ 1282> *\-> n1:'N1', n2:'N2', u1:'U1', u2:''* 1283 1284## <a name='subsection11'></a>Raw Argument List 1285 1286It may be necessary sometimes that the procedure body is able to access the 1287entire list of arguments provided during a procedure call\. This can happen via 1288the __args__ variable that contains always the unprocessed argument list: 1289 1290> tepam::procedure \{display\_message\} \{ 1291> \-args \{ 1292> \{\-mtype \-choices \{Warning Error\} \-default Warning\} 1293> \{text \-type string \-multiple\} 1294> 1295> \} 1296> \} \{ 1297> puts "args: __$args__" 1298> \} 1299> display\_message \-mtype Warning "It is 7:00" 1300> *\-> args: \-mtype Warning \{It is 7:00\}* 1301 1302# <a name='seealso'></a>SEE ALSO 1303 1304[tepam\(n\)](tepam\_introduction\.md), 1305[tepam::argument\_dialogbox\(n\)](tepam\_argument\_dialogbox\.md) 1306 1307# <a name='keywords'></a>KEYWORDS 1308 1309[argument integrity](\.\./\.\./\.\./\.\./index\.md\#argument\_integrity), [argument 1310validation](\.\./\.\./\.\./\.\./index\.md\#argument\_validation), 1311[arguments](\.\./\.\./\.\./\.\./index\.md\#arguments), 1312[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure), 1313[subcommand](\.\./\.\./\.\./\.\./index\.md\#subcommand) 1314 1315# <a name='category'></a>CATEGORY 1316 1317Procedures, arguments, parameters, options 1318 1319# <a name='copyright'></a>COPYRIGHT 1320 1321Copyright © 2009\-2013, Andreas Drollinger 1322