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.3?
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

::ARGV HANDLING

35       One  of  the  most  common  variables this package will be used with is
36       ::argv, which holds the command line of the current  application.  This
37       variable  has  a companion ::argc which is initialized to the number of
38       elements in ::argv at the beginning of the application.
39
40       The commands in this package will not modify the ::argc companion  when
41       called with ::argv. Keeping the value consistent, if such is desired or
42       required, is the responsibility of the caller.
43

API

45       ::cmdline::getopt argvVar optstring optVar valVar
46              This command works in a fashion like the standard C based getopt
47              function.   Given  an option string and a pointer to an array of
48              args this command will process the  first  argument  and  return
49              info  on  how to proceed. The command returns 1 if an option was
50              found, 0 if no more options were found, and -1 if an  error  oc‐
51              curred.
52
53              argvVar  contains  the name of the list of arguments to process.
54              If options are found the list is modified and the processed  ar‐
55              guments are removed from the start of the list.
56
57              optstring  contains  a list of command options that the applica‐
58              tion will accept.  If the option ends in ".arg" the command will
59              use  the  next argument as an argument to the option, or extract
60              it from the  current  argument,  if  it  is  of  the  form  "op‐
61              tion=value".  Otherwise the option is a boolean that is set to 1
62              if present.
63
64              optVar refers to the variable the command will store  the  found
65              option into (without the leading '-' and without the .arg exten‐
66              sion).
67
68              valVar refers to the variable to store either the value for  the
69              specified  option  into  upon success or an error message in the
70              case of failure. The stored value comes from  the  command  line
71              for .arg options, otherwise the value is 1.
72
73       ::cmdline::getKnownOpt argvVar optstring optVar valVar
74              Like  ::cmdline::getopt,  but ignores any unknown options in the
75              input.
76
77       ::cmdline::getoptions arglistVar optlist ?usage?
78              Processes the set of command line  options  found  in  the  list
79              variable named by arglistVar and fills in defaults for those not
80              specified.  This also generates an error message that lists  the
81              allowed  flags  if  an incorrect flag is specified. The optional
82              usage-argument contains a string to include in front of the gen‐
83              erated message. If not present it defaults to "options:".
84
85              optlist contains a list of lists where each element specifies an
86              option in the form: flag default comment.
87
88              If flag ends in ".arg" then the value is taken from the  command
89              line.  Otherwise  it  is  a boolean and appears in the result if
90              present on the command line. If flag ends in ".secret", it  will
91              not be displayed in the usage.
92
93              The  options  -?,  -help,  and -- are implicitly understood. The
94              first two abort option processing by throwing an error and force
95              the generation of the usage message, whereas the the last aborts
96              option processing without an error, leaving all arguments coming
97              after for regular processing, even if starting with a dash.
98
99              The result of the command is a dictionary mapping all options to
100              their values, be they user-specified or defaults.
101
102       ::cmdline::getKnownOptions arglistVar optlist ?usage?
103              Like ::cmdline::getoptions, but ignores any unknown  options  in
104              the input.
105
106       ::cmdline::usage optlist ?usage?
107              Generates  and  returns  an error message that lists the allowed
108              flags. optlist is defined as for ::cmdline::getoptions. The  op‐
109              tional  usage-argument  contains a string to include in front of
110              the generated message. If not present it defaults to "options:".
111
112       ::cmdline::getfiles patterns quiet
113              Given a list of file patterns this command computes the  set  of
114              valid files.  On windows, file globbing is performed on each ar‐
115              gument.  On Unix, only file existence is tested.  If a file  ar‐
116              gument  produces  no valid files, a warning is optionally gener‐
117              ated (set quiet to true).
118
119              This code also uses the full path for each file.  If  not  given
120              it  prepends the current working directory to the filename. This
121              ensures that these files will never conflict  with  files  in  a
122              wrapped zip file. The last sentence refers to the pro-tools.
123
124       ::cmdline::getArgv0
125              This  command returns the "sanitized" version of argv0.  It will
126              strip off the leading path and removes the extension ".bin". The
127              latter is used by the pro-apps because they must be wrapped by a
128              shell script.
129
130   ERROR CODES
131       Starting with version 1.5 all errors  thrown  by  the  package  have  a
132       proper ::errorCode for use with Tcl's try command. This code always has
133       the word CMDLINE as its first element.
134

EXAMPLES

136                      package require Tcl 8.5
137                      package require try         ;# Tcllib.
138                      package require cmdline 1.5 ;# First version with proper error-codes.
139
140                      # Notes:
141                      # - Tcl 8.6+ has 'try' as a builtin command and therefore does not
142                      #   need the 'try' package.
143                      # - Before Tcl 8.5 we cannot support 'try' and have to use 'catch'.
144                      #   This then requires a dedicated test (if) on the contents of
145                      #   ::errorCode to separate the CMDLINE USAGE signal from actual errors.
146
147                      set options {
148                          {a          "set the atime only"}
149                          {m          "set the mtime only"}
150                          {c          "do not create non-existent files"}
151                          {r.arg  ""  "use time from ref_file"}
152                          {t.arg  -1  "use specified time"}
153                      }
154                      set usage ": MyCommandName \[options] filename ...\noptions:"
155
156                      try {
157                          array set params [::cmdline::getoptions argv $options $usage]
158                      } trap {CMDLINE USAGE} {msg o} {
159                          # Trap the usage signal, print the message, and exit the application.
160                          # Note: Other errors are not caught and passed through to higher levels!
161                    puts $msg
162                    exit 1
163                      }
164
165                      if {  $params(a) } { set set_atime "true" }
166                      set has_t [expr {$params(t) != -1}]
167                      set has_r [expr {[string length $params(r)] > 0}]
168                      if {$has_t && $has_r} {
169                          return -code error "Cannot specify both -r and -t"
170                      } elseif {$has_t} {
171                    ...
172                      }
173
174
175       This example, taken (and slightly modified) from the package  fileutil,
176       shows  how  to  use cmdline.  First, a list of options is created, then
177       the 'args' list is passed to  cmdline  for  processing.   Subsequently,
178       different  options  are  checked to see if they have been passed to the
179       script, and what their value is.
180

BUGS, IDEAS, FEEDBACK

182       This document, and the package it describes, will  undoubtedly  contain
183       bugs and other problems.  Please report such in the category cmdline of
184       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
185       also  report any ideas for enhancements you may have for either package
186       and/or documentation.
187
188       When proposing code changes, please provide unified diffs, i.e the out‐
189       put of diff -u.
190
191       Note  further  that  attachments  are  strongly  preferred over inlined
192       patches. Attachments can be made by going  to  the  Edit  form  of  the
193       ticket  immediately  after  its  creation, and then using the left-most
194       button in the secondary navigation bar.
195

KEYWORDS

197       argument processing, argv, argv0, cmdline processing, command line pro‐
198       cessing
199

CATEGORY

201       Programming tools
202
203
204
205tcllib                                1.5                           cmdline(n)
Impressum