Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

tepam(n)                        Tcl's Enhanced Procedure and Argument Manager                       tepam(n)



____________________________________________________________________________________________________________

NAME
       tepam - An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager

DESCRIPTION
       This document is an informal introduction into version 0.1 of TEPAM, the Tcl's Enhanced Procedure and
       Argument Manager. Detailed information to the TEPAM package is provided in the  tepam::procedure  and
       tepam::argument_dialogbox reference manuals.

OVERVIEW
       This  package  provides  a new Tcl procedure declaration syntax that simplifies the implementation of
       procedure subcommands and the handling of the different types of procedure arguments  like  flags  or
       switches,  options,  unnamed arguments, optional and mandatory options and arguments, default values,
       etc. Procedure declarations can be enriched with detailed information about  the  procedure  and  its
       arguments. This information is used later for the following purposes:

       First  of  all, an argument manager that is automatically added to a procedure implemented with TEPAM
       checks the argument types and values before the procedure body is executed. Then, the information  is
       used  to  generate  help  and usage texts if requested, or to generate clear error message in case an
       argument validation fails. The information also allows generating automatically graphical forms  that
       allows  an  interactive definition of all arguments, in case a procedure is called interactively. And
       finally, the additional information helps self-commenting in a clean way the declaration of a  proce-dure procedure
       dure and of all its arguments.

       The graphical form generator that creates the necessary argument specification forms for the interac-tive interactive
       tive procedure calls is also available for other purposes than for procedure argument specifications.
       It  allows creating code efficiently complex parameter entry forms that are usable independently from
       TEPAM's new procedure definition feature.

       Here is a short overview about all major TEPAM features:

       •      New self-documenting procedure declaration syntax: The additional information to declare prop-erly properly
              erly a procedure has not to be provided with additional statements, but can be added in a nat-ural natural
              ural syntax directly into the procedure header.

       •      Easy way to specify subcommands: A subcommand is declared like a procedure, simply with a pro-cedure procedure
              cedure name composed by a base name followed by a subcommand name. Sub-subcommands are created
              identically using simply procedure names composed by 3 words.

       •      Flexible usage of flags (switches), options (named arguments) and  unnamed  arguments.  Option
              names are optionally automatically completed.

       •      Support  for  default  values,  mandatory/optional  options and arguments, choice lists, valid
              value ranges, multiple usable options/arguments.

       •      Choice of a named arguments first, unnamed arguments later procedure  calling  style  (typical
              for  Tcl  commands)  or of an unnamed arguments first, named arguments later procedure calling
              style (typical for Tk commands).

       •      In case the named arguments first, unnamed arguments later style  (Tcl)  is  selected:   Clear
              separation  between options and arguments via the "--" flag. The unnamed arguments can option-ally optionally
              ally be accessed as options (named arguments).

       •      Automatic type and value check before the procedure body is executed, taking into account val-idation validation
              idation ranges, choice lists and custom validation commands. Generation of clear error message
              if necessary.

       •      Many predefined types exist (integer, boolean, double, color, file, font, ...). Other applica-tion application
              tion specific types can easily be added.

       •      Automatic help and usage text generation when a procedure is called with the -help flag.

       •      Automatic generation of an interactive argument definition form, in case a procedure is called
              with the -interactive flag.

       •      Powerful and code efficient generation of complex parameter definition forms.


PROCEDURE DECLARATION
       TEPAM's procedure declaration syntax is simple and self-explaining. Instead of declaring a  procedure
       with  the  Tcl key word proc, a procedure is declared with the TEPAM command procedure which takes as
       proc also 3 arguments: The procedure name, the procedure header and the procedure body.

       The following example declares the subcommand message of the procedure display. This command has sev-eral several
       eral named and unnamed arguments:
       tepam::procedure {display message} {
          -return            --short_description -return-short_description
          -short_description "Displays a simple message box"
          -description       "This procedure allows displaying a configurable message box.
          -args {
             {-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
             {-font -type font -default {Arial 10 italic} -description "Message text font"}
             {-level -type integer -optional -range {1 10} -description "Message level"}
             {-fg -type color -default black -description "Message color"}
             {-bg -type color -optional -description "Background color"}
             {-no_border -type none -description "Use a splash window style (no border)"}
             {-log_file -type file -optional -description "Optional message log file"}
             {text -type string -multiple -description "Multiple text lines to display"}
          }
       } {
          puts "display message:"
          foreach var {mtype font level fg bg no_border log_file text} {
             if {[info exists $var]} {
                puts  "  $var=[set $var]"
             }
          }
       }
       When a procedure that has been declared in this way is called, the TEPAM argument manager is automat-ically automatically
       ically invoked before the procedure body is executed. The argument manager parses the provided  argu-ments, arguments,
       ments,  validates  them,  completes  them eventually with some default values, and makes them finally
       available to the procedure body as local variables. In case an argument is missing  or  has  a  wrong
       type, the argument manager generates an error message that explains the reason for the error.

       As  the  example above shows, the TEPAM command procedure accepts subcommand definitions as procedure
       name and allows defining much more information than just  the  argument  list  inside  the  procedure
       header.  The  procedure  body  on the other hand is identical between a command declared with proc or
       with procedure.

       The procedure header allows defining in addition to the arguments some procedure attributes,  like  a
       description, information concerning the return value, etc. This information is basically used for the
       automatic generation of comprehensive help and usage texts.

       A list of argument definition statements assigned to the -args argument  is  defining  the  procedure
       arguments.  Each  argument definition statement starts with the argument name, optionally followed by
       some argument attributes.

       Three types of arguments can be defined: Unnamed arguments, named arguments and flags.  The  distinc-tion distinction
       tion  between  the  named and unnamed arguments is made by the first argument name character which is
       simply "-" for named arguments. Flags are defined as named argument that has a type set to none.

       Named and unnamed arguments are mandatory, unless they are  declared  with  the  -optional  flag  and
       unless  they  have  a  default value specified with the -default option. Named arguments and the last
       unnamed argument can have the attribute -multiple, which means that  they  can  be  defined  multiple
       times.  The expected argument data type is specified with the -type option. TEPAM defines a large set
       of standard data types which can easily be completed with application specific data types.

       The argument declaration order has only an importance for  unnamed  arguments  that  are  by  default
       parsed  after the named arguments (Tcl style). A variable allows changing this behavior in a way that
       unnamed arguments are parsed first, before the named arguments (Tk style).

PROCEDURE HELP
       The declared procedure can simply be called with the -help option to get the  information  about  the
       usage of the procedure and its arguments:
       display message -help
         ->
       NAME
             display message - Displays a simple message box
       SYNOPSYS
             display message
                   [-mtype <mtype>] :
                      Message type, default: "Warning", choices: {Info Warning Error}
                   [-font <font>] :
                      Message text font, type: font, default: Arial 1_ italic
                   [-level <level>] :
                      Message level, type: integer, range: 1..1_
                   [-fg <fg>] :
                      Message color, type: color, default: black
                   [-bg <bg>] :
                      Background color, type: color
                   [-no_border ] :
                      Use a splash window style (no border)
                   [-log_file <log_file>] :
                      Optional message log file, type: file
                   <text> :
                      Multiple text lines to display, type: string
       DESCRIPTION
             This procedure allows displaying a configurable message box.

PROCEDURE CALL
       The  specified procedure can be called in many ways. The following listing shows some valid procedure
       calls:
       display message "The document hasn't yet been saved!"
       -> display message:
            mtype=Warning
            font=Arial 1_ italic
            fg=black
            no_border=_
            text={The document hasn't yet been saved!}

       display message -fg red -bg black "Please save first the document"
       -> display message:
            mtype=Warning
            font=Arial 1_ italic
            fg=red
            bg=black
            no_border=_
            text={Please save first the document}

       display message -mtype Error -no_border "Why is here no border?"
       -> display message:
            mtype=Error
            font=Arial 1_ italic
            fg=black
            no_border=1
            text={Why is here no border?}

       display message -font {Courier 12} -level 10 \
          "Is there enough space?" "Reduce otherwise the font size!"
       -> display message:
            mtype=Warning
            font=Courier 12
            level=1_
            fg=black
            no_border=_
            text={Is there enough space?} {Reduce otherwise the font size!}
       The next lines show how wrong arguments are recognized. The text argument that is mandatory is  miss-ing missing
       ing in the first procedure call:
       display message -font {Courier 12}
         -> display message: Required argument is missing: text
       Only valid arguments are accepted:
       display message -category warning Hello
         -> display message: Argument '-category' not known
       Argument  types are automatically checked and an error message is generated in case the argument type
       is not satisfied.
       display message -fg MyColor "Hello"
         -> display message: Argument 'fg' requires type 'color'. \
                   Provided value: 'MyColor'
       Selection choices have to be respected...
       display message -mtype Fatal Hello
         -> display message: Argument (mtype) has to be one of the \
                   following elements: Info, Warning, Error
       display message -level 12 Hello
         -> display message: Argument (level) has to be between 1 and 1_

INTERACTIVE ARGUMENT DEFINITION
       The most intuitive way to call the procedure is using an interactive form that allows specifying  all
       arguments.  This  form will automatically be generated when the declared procedure is called with the
       -interactive flag.
       display message -interactive
       The generated form contains for each argument a data entry widget that is  adapted  to  the  argument
       type. Check buttons are used to specify flags, radio boxes for tiny choice lists, disjoint list boxes
       for larger choice lists and files, directories, fonts and  colors  can  be  selected  with  dedicated
       browsers.

       After  acknowledging  the  specified argument data via an OK button, the entered data are first vali-dated, validated,
       dated, before the provided arguments are transformed into local variables and the procedure  body  is
       executed. In case the entered data are invalid, a message appears and the user can correct them until
       they are valid.

FLEXIBLE ARGUMENT DIALOG BOX
       The form generator that creates in the previous example the argument dialog box for  the  interactive
       procedure  call  is also available for other purposes than for the definition of procedure arguments.
       Even if Tk is well known for its code efficient way to build GUIs, the presented argument dialog  box
       allows crating complex parameter definition forms in a still much more efficient way.

       The  following example tries to illustrate the simplicity to create complex data entry forms. It cre-ates creates
       ates an input mask that allows specifying a file to copy, a destination folder as well as a  checkbox
       that  allows  specifying if an eventual existing file can be overwritten. Comfortable browsers can be
       used to select files and directories. And finally, the form offers also the possibility to accept and
       decline the selection. Here is the code snippet that is doing all this:
       tepam::argument_dialogbox \
          -existingfile {-label "Source file" -variable SourceFile} \
          -existingdirectory {-label "Destination folder" -variable DestDir} \
          -checkbutton {-label "Overwrite existing file" -variable Overwrite}
       The  argument_dialogbox returns ok when the entered data are validated and cancel when the data entry
       has been canceled. After the validation of the entered data, the argument_dialogbox defines  all  the
       specified variables with the entered data inside the calling context.

       A  pair of arguments has to be provided to argument_dialogbox for each variable that has to be speci-fied specified
       fied by this last one. The first argument defines the entry widget type to use to  select  the  vari-able's variable's
       able's data and the second one is a lists of attributes related to the variable and the entry widget.

       Many entry widget types are available: Beside the simple generic entries, there are  different  kinds
       of  list  and  combo  boxes available, browsers for existing and new files and directories, check and
       radio boxes and buttons, as well as color and font pickers. If  necessary,  additional  entry  widget
       types can be defined.

       The  attribute  list  contains  pairs of attribute names and attribute data. The primary attribute is
       -variable used to specify the variable in the calling context into which the entered data has  to  be
       stored.  Another  often used attribute is -label that allows adding a label to the data entry widget.
       Other attributes are available that allows specifying default values, the expected data types,  valid
       data ranges, etc.

       The  next  example of a more complex argument dialog box provides a good overview about the different
       available entry widget types and parameter attributes. The  example  contains  also  some  formatting
       instructions  like  -frame and -sep which allows organizing the different entry widgets in frames and
       sections:
       set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"}

       set Result [tepam::argument_dialogbox \
          -title "System configuration" \
          -context test_1 \
          -frame {-label "Entries"} \
             -entry {-label Entry1 -variable Entry1} \
             -entry {-label Entry2 -variable Entry2 -default "my default"} \
          -frame {-label "Listbox & combobox"} \
             -listbox {-label "Listbox, single selection" -variable Listbox1 \
                       -choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \
             -listbox {-label "Listbox, multiple selection" -variable Listbox2
                       -choicevariable ChoiceList -default {"Choice 2" "Choice 3"}
                       -multiple_selection 1 -height 3} \
             -disjointlistbox {-label "Disjoined listbox" -variable DisJntListbox
                               -choicevariable ChoiceList \
                               -default {"Choice 3" "Choice 5"} -height 3} \
             -combobox {-label "Combobox" -variable Combobox \
                        -choices {1 2 3 4 5 6 7 8} -default 3} \
          -frame {-label "Checkbox, radiobox and checkbutton"} \
             -checkbox {-label Checkbox -variable Checkbox
                        -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
                        -default italic} \
             -radiobox {-label Radiobox -variable Radiobox
                        -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
                        -default underline} \
             -checkbutton {-label CheckButton -variable Checkbutton -default 1} \
          -frame {-label "Files & directories"} \
             -existingfile {-label "Input file" -variable InputFile} \
             -file {-label "Output file" -variable OutputFile} \
             -sep {} \
             -existingdirectory {-label "Input directory" -variable InputDirectory} \
             -directory {-label "Output irectory" -variable OutputDirectory} \
          -frame {-label "Colors and fonts"} \
             -color {-label "Background color" -variable Color -default red} \
             -sep {} \
             -font {-label "Font" -variable Font -default {Courier 12 italic}}]
       The validation status is in this case stored inside the Result variable. If the entered data are val-idated, validated,
       idated,  Result  will  contain  0 and the calling program can read the entered data via the variables
       that have been specified:
       if {$Result=="cancel"} {
          puts "Canceled"
       } else {
          puts "Arguments: "
          foreach Var {
             Entry1 Entry2
             Listbox1 Listbox2 DisJntListbox
             Combobox Checkbox Radiobox Checkbutton
             InputFile OutputFile InputDirectory OutputDirectory
             Color Font
          } {
             puts "  $Var: '[set $Var]'"
          }
       }
       -> Arguments:
          Entry1: 'Hello, this is a trial'
          Entry2: 'my default'
          Listbox1: '1'
          Listbox2: '{Choice 2} {Choice 3}'
          DisJntListbox: '{Choice 3} {Choice 5}'
          Combobox: '3'
          Checkbox: 'italic'
          Radiobox: 'underline'
          Checkbutton: '1'
          InputFile: 'c:\tepam\in.txt'
          OutputFile: 'c:\tepam\out.txt'
          InputDirectory: 'c:\tepam\input'
          OutputDirectory: 'c:\tepam\output'
          Color: 'red'
          Font: 'Courier 12 italic'

SEE ALSO
       tepam_argument_dialogbox(n), tepam_procedure(n)

KEYWORDS
       argument integrity, argument validation, arguments, entry mask, parameter entry form, procedure, sub-command subcommand
       command

CATEGORY
       Procedures, arguments, parameters, options

COPYRIGHT
       Copyright (c) 2009/2010, Andreas Drollinger




tepam                                                0.1                                            tepam(n)