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

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

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

cmdline(n)                           Command line and option processing                           cmdline(n)



____________________________________________________________________________________________________________

NAME
       cmdline - Procedures to process command lines and options.

SYNOPSIS
       package require Tcl  8.2

       package require cmdline  ?1.3.1?

       ::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.

::ARGV HANDLING
       One  of  the  most common variables this package will be used with is ::argv, which holds the command
       line of the current application. This variable has a companion ::argc which  is  initialized  to  the
       number of elements in ::argv at the beginning of the application.

       The  commands  in  this package will not modify the ::argc companion when called with ::argv. Keeping
       the value consistent, if such is desired or required, is the responsibility of the caller.

API
       ::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 of 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 list of arguments to process. If options are found the list
              is modified and the processed arguments are removed from the start of the list.

              optstring contains a list of command options that the application 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  lead-ing leading
              ing '-' and without the .arg extension).

              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 generated 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 generated (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 argv_.  It will strip off the leading path and
              removes  the extension ".bin". The latter is used by the pro-apps 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-existent 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 package fileutil,  shows  how  to  use  cmdline.
       First,  a list of options is created, then the 'args' list is passed to cmdline for processing.  Sub-sequently, Subsequently,
       sequently, different options are checked to see if they have been passed  to  the  script,  and  what
       their value is.

BUGS, IDEAS, FEEDBACK
       This  document,  and  the  package  it  describes,  will undoubtedly contain bugs and other problems.
       Please  report  such  in  the  category  cmdline  of   the   Tcllib   SF   Trackers   [http://source -
       forge.net/tracker/? group_id=12883].   Please  also report any ideas for enhancements you may have for
       either package and/or documentation.

KEYWORDS
       argument processing, argv, argv0, cmdline processing, command line processing

CATEGORY
       Programming tools



cmdline                                             1.3.1                                         cmdline(n)