1cmdline(n)            Command line and option processing            cmdline(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       cmdline - Procedures to process command lines and options.
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require cmdline  ?1.3.1?
14
15       ::cmdline::getopt argvVar optstring optVar valVar
16
17       ::cmdline::getKnownOpt argvVar optstring optVar valVar
18
19       ::cmdline::getoptions arglistVar optlist ?usage?
20
21       ::cmdline::getKnownOptions arglistVar optlist ?usage?
22
23       ::cmdline::usage optlist ?usage?
24
25       ::cmdline::getfiles patterns quiet
26
27       ::cmdline::getArgv0
28
29_________________________________________________________________
30

DESCRIPTION

32       This package provides commands to parse command lines and options.
33
34       ::cmdline::getopt argvVar optstring optVar valVar
35              This command works in a fashion like the standard C based getopt
36              function.  Given an option string and a pointer to an  array  or
37              args  this  command  will  process the first argument and return
38              info on how to proceed. The command returns 1 if an  option  was
39              found,  0  if  no  more  options  were found, and -1 if an error
40              occurred.
41
42              argvVar contains the name of the list of arguments  to  process.
43              If  options  are  found  the  list is modified and the processed
44              arguments are removed from the start of the list.
45
46              optstring contains a list of command options that  the  applica‐
47              tion will accept.  If the option ends in ".arg" the command will
48              use the next argument as an argument to the  option.   Otherwise
49              the option is a boolean that is set to 1 if present.
50
51              optVar  refers  to the variable the command will store the found
52              option into (without the leading '-' and without the .arg exten‐
53              sion).
54
55              valVar  refers to the variable to store either the value for the
56              specified option into upon success or an error  message  in  the
57              case  of  failure.  The stored value comes from the command line
58              for .arg options, otherwise the value is 1.
59
60       ::cmdline::getKnownOpt argvVar optstring optVar valVar
61              Like ::cmdline::getopt, but ignores any unknown options  in  the
62              input.
63
64       ::cmdline::getoptions arglistVar optlist ?usage?
65              Processes  the  set  of  command  line options found in the list
66              variable named by arglistVar and fills in defaults for those not
67              specified.   This also generates an error message that lists the
68              allowed flags if an incorrect flag is  specified.  The  optional
69              usage-argument contains a string to include in front of the gen‐
70              erated message. If not present it defaults to "options:".
71
72              optlist contains a list of lists where each element specifies an
73              option in the form: flag default comment.
74
75              If  flag ends in ".arg" then the value is taken from the command
76              line. Otherwise it is a boolean and appears  in  the  result  if
77              present  on the command line. If flag ends in ".secret", it will
78              not be displayed in the usage.
79
80       ::cmdline::getKnownOptions arglistVar optlist ?usage?
81              Like ::cmdline::getoptions, but ignores any unknown  options  in
82              the input.
83
84       ::cmdline::usage optlist ?usage?
85              Generates  and  returns  an error message that lists the allowed
86              flags. optlist is  defined  as  for  ::cmdline::getoptions.  The
87              optional usage-argument contains a string to include in front of
88              the generated message. If not present it defaults to "options:".
89
90       ::cmdline::getfiles patterns quiet
91              Given a list of file patterns this command computes the  set  of
92              valid  files.   On  windows,  file globbing is performed on each
93              argument.  On Unix, only file existence is tested.   If  a  file
94              argument produces no valid files, a warning is optionally gener‐
95              ated (set quiet to true).
96
97              This code also uses the full path for each file.  If  not  given
98              it  prepends the current working directory to the filename. This
99              ensures that these files will never conflict  with  files  in  a
100              wrapped zip file. The last sentence refers to the pro-tools.
101
102       ::cmdline::getArgv0
103              This  command returns the "sanitized" version of argv0.  It will
104              strip off the leading path and removes the extension ".bin". The
105              latter is used by the pro-apps because they must be wrapped by a
106              shell script.
107

EXAMPLES

109               set options {
110                   {a          "set the atime only"}
111                   {m          "set the mtime only"}
112                   {c          "do not create non-existent files"}
113                   {r.arg  ""  "use time from ref_file"}
114                   {t.arg  -1  "use specified time"}
115               }
116               set usage ": MyCommandName \[options] filename ...\noptions:"
117               array set params [::cmdline::getoptions argv $options $usage]
118
119               if {  $params(a) } { set set_atime "true" }
120               set has_t [expr {$params(t) != -1}]
121               set has_r [expr {[string length $params(r)] > 0}]
122               if {$has_t && $has_r} {
123                   return -code error "Cannot specify both -r and -t"
124               } elseif {$has_t} {
125                ...
126               }
127
128
129       This example, taken (and slightly modified) from the package  fileutil,
130       shows  how  to  use cmdline.  First, a list of options is created, then
131       the 'args' list is passed to  cmdline  for  processing.   Subsequently,
132       different  options  are  checked to see if they have been passed to the
133       script, and what their value is.
134

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

143       argument processing, argv, argv0, cmdline processing, command line pro‐
144       cessing
145
146
147
148cmdline                              1.3.1                          cmdline(n)
Impressum