cmdline--3tcl

cmdline(n)             command line / option processing             cmdline(n)



______________________________________________________________________________

NAME
       cmdline - Procedures to process command lines and options.

SYNOPSIS
       package require Tcl  8.2

       package require cmdline  ?1.2.2?

       ::cmdline::getopt argvVar optstring optVar valVar

       ::cmdline::getKnownOpt argvVar optstring optVar valVar

       ::cmdline::getoptions arglistVar optlist ?usage?

       ::cmdline::getKnownOptions arglistVar optlist ?usage?

       ::cmdline::usage optlist ?usage?

       ::cmdline::getfiles patterns quiet

       ::cmdline::getArgv0

_________________________________________________________________

DESCRIPTION
       This package provides commands to parse command lines and options.

       ::cmdline::getopt argvVar optstring optVar valVar
              This command works in a fashion like the standard C based getopt
              function.  Given an option string and a pointer to an  array  or
              args  this  command  will  process the first argument and return
              info on how to proceed. The command returns 1 if an  option  was
              found,  0  if  no  more  options  were found, and -1 if an error
              occurred.

              argvVar contains the name  of  the  argv  list  to  process.  If
              options  are  found  the  arg list is modified and the processed
              arguments are removed from the start of the list.

              optstring contains a list of command options that  the  applica-
              tion will accept.  If the option ends in ".arg" the command will
              use the next argument as an argument to the  option.   Otherwise
              the option is a boolean that is set to 1 if present.

              optVar  refers  to the variable the command will store the found
              option into (without the leading '-' and without the .arg exten-
              sion).

              valVar  refers to the variable to store either the value for the
              specified option into upon success or an error  message  in  the
              case  of  failure.  The stored value comes from the command line
              for .arg options, otherwise the value is 1.

       ::cmdline::getKnownOpt argvVar optstring optVar valVar
              Like ::cmdline::getopt, but ignores any unknown options  in  the
              input.

       ::cmdline::getoptions arglistVar optlist ?usage?
              Processes  the  set  of  command  line options found in the list
              variable named by arglistVar and fills in defaults for those not
              specified.   This also generates an error message that lists the
              allowed flags if an incorrect flag is  specified.  The  optional
              usage-argument contains a string to include in front of the gen-
              erated message. If not present it defaults to "options:".

              optlist contains a list of lists where each element specifies an
              option in the form: flag default comment.

              If  flag ends in ".arg" then the value is taken from the command
              line. Otherwise it is a boolean and appears  in  the  result  if
              present  on the command line. If flag ends in ".secret", it will
              not be displayed in the usage.

       ::cmdline::getKnownOptions arglistVar optlist ?usage?
              Like ::cmdline::getoptions, but ignores any unknown  options  in
              the input.

       ::cmdline::usage optlist ?usage?
              Generates  and  returns  an error message that lists the allowed
              flags. optlist is  defined  as  for  ::cmdline::getoptions.  The
              optional usage-argument contains a string to include in front of
              the generated message. If not present it defaults to "options:".

       ::cmdline::getfiles patterns quiet
              Given  a  list of file patterns this command computes the set of
              valid files.  On windows, file globbing  is  performed  on  each
              argument.   On  Unix,  only file existence is tested.  If a file
              argument produces no valid files, a warning is optionally gener-
              ated (set quiet to true).

              This  code  also uses the full path for each file.  If not given
              it prepends the current working directory to the filename.  This
              ensures  that  these  files  will never conflict with files in a
              wrapped zip file. The last sentence refers to the pro-tools.

       ::cmdline::getArgv0
              This command returns the "sanitized" version of argv0.  It  will
              strip  off  the  leading  path and removes the ".bin" extensions
              that the pro-apps use because they must be wrapped  by  a  shell
              script.

EXAMPLES
               set options {
                   {a          "set the atime only"}
                   {m          "set the mtime only"}
                   {c          "do not create non-existant files"}
                   {r.arg  ""  "use time from ref_file"}
                   {t.arg  -1  "use specified time"}
               }
               set usage ": MyCommandName \[options] filename ...\noptions:"
               array set params [::cmdline::getoptions argv $options $usage]

               if {  $params(a) } { set set_atime "true" }
               set has_t [expr {$params(t) != -1}]
               set has_r [expr {[string length $params(r)] > 0}]
               if {$has_t && $has_r} {
                   return -code error "Cannot specify both -r and -t"
               } elseif {$has_t} {
                ...
               }

       This  example, taken (and slightly modified) from the fileutil package,
       shows how to use cmdline.  First, a list of options  is  created,  then
       the  'args'  list  is  passed to cmdline for processing.  Subsequently,
       different options are checked to see if they have been  passed  to  the
       script, and what their value is.

KEYWORDS
       cmdline processing



cmdline                              1.2.1                          cmdline(n)