1cmdline(n) Command line and option processing cmdline(n)
2______________________________________________________________________________
6
8 cmdline - Procedures to process command lines and options.
9
11 package require Tcl 8.2
12 package require cmdline ?1.5.2?
14 ::cmdline::getopt argvVar optstring optVar valVar
16 ::cmdline::getKnownOpt argvVar optstring optVar valVar
18 ::cmdline::getoptions argvVar optlist ?usage?
20 ::cmdline::getKnownOptions argvVar optlist ?usage?
22 ::cmdline::usage optlist ?usage?
24 ::cmdline::getfiles patterns quiet
26 ::cmdline::getArgv0
28______________________________________________________________________________
30
32 This package provides commands to parse command lines and options.
33
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 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
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 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 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 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 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 ::cmdline::getKnownOpt argvVar optstring optVar valVar
74 Like ::cmdline::getopt, except it ignores any unknown options in
75 the input.
76 ::cmdline::getoptions argvVar optlist ?usage?
78 Processes the entire set of command line options found in the
79 list variable named by argvVar and fills in defaults for those
80 not specified. This also generates an error message that lists
81 the allowed flags if an incorrect flag is specified. The op‐
82 tional usage-argument contains a string to include in front of
83 the generated message. If not present it defaults to "options:".
84 argvVar contains the name of the list of arguments to process.
86 If options are found the list is modified and the processed ar‐
87 guments are removed from the start of the list.
88 optlist contains a list of lists where each element specifies an
90 option in the form: flag default comment.
91 If flag ends in ".arg" then the value is taken from the command
93 line. Otherwise it is a boolean and appears in the result if
94 present on the command line. If flag ends in ".secret", it will
95 not be displayed in the usage.
96 The options -?, -help, and -- are implicitly understood. The
98 first two abort option processing by throwing an error and force
99 the generation of the usage message, whereas the the last aborts
100 option processing without an error, leaving all arguments coming
101 after for regular processing, even if starting with a dash.
102 The result of the command is a dictionary mapping all options to
104 their values, be they user-specified or defaults.
105 ::cmdline::getKnownOptions argvVar optlist ?usage?
107 Like ::cmdline::getoptions, but ignores any unknown options in
108 the input.
109 ::cmdline::usage optlist ?usage?
111 Generates and returns an error message that lists the allowed
112 flags. optlist is defined as for ::cmdline::getoptions. The op‐
113 tional usage-argument contains a string to include in front of
114 the generated message. If not present it defaults to "options:".
115 ::cmdline::getfiles patterns quiet
117 Given a list of file patterns this command computes the set of
118 valid files. On windows, file globbing is performed on each ar‐
119 gument. On Unix, only file existence is tested. If a file ar‐
120 gument produces no valid files, a warning is optionally gener‐
121 ated (set quiet to true).
122 This code also uses the full path for each file. If not given
124 it prepends the current working directory to the filename. This
125 ensures that these files will never conflict with files in a
126 wrapped zip file. The last sentence refers to the pro-tools.
127 ::cmdline::getArgv0
129 This command returns the "sanitized" version of argv0. It will
130 strip off the leading path and removes the extension ".bin". The
131 latter is used by the TclPro applications because they must be
132 wrapped by a shell script.
133 ERROR CODES
135 Starting with version 1.5 all errors thrown by the package have a
136 proper ::errorCode for use with Tcl's try command. This code always has
137 the word CMDLINE as its first element.
138
140 CMDLINE::GETOPTIONS
141 This example, taken from the package fileutil and slightly modified,
142 demonstrates how to use cmdline::getoptions. First, a list of options
143 is created, then the 'args' list is passed to cmdline for processing.
144 Subsequently, different options are checked to see if they have been
145 passed to the script, and what their value is.
146 package require Tcl 8.5
148 package require try ;# Tcllib.
149 package require cmdline 1.5 ;# First version with proper error-codes.
150 # Notes:
152 # - Tcl 8.6+ has 'try' as a builtin command and therefore does not
153 # need the 'try' package.
154 # - Before Tcl 8.5 we cannot support 'try' and have to use 'catch'.
155 # This then requires a dedicated test (if) on the contents of
156 # ::errorCode to separate the CMDLINE USAGE signal from actual errors.
157 set options {
159 {a "set the atime only"}
160 {m "set the mtime only"}
161 {c "do not create non-existent files"}
162 {r.arg "" "use time from ref_file"}
163 {t.arg -1 "use specified time"}
164 }
165 set usage ": MyCommandName \[options] filename ...\noptions:"
166 try {
168 array set params [::cmdline::getoptions argv $options $usage]
169 # Note: argv is modified now. The recognized options are
171 # removed from it, leaving the non-option arguments behind.
172 } trap {CMDLINE USAGE} {msg o} {
173 # Trap the usage signal, print the message, and exit the application.
174 # Note: Other errors are not caught and passed through to higher levels!
175 puts $msg
176 exit 1
177 }
178 if { $params(a) } { set set_atime "true" }
180 set has_t [expr {$params(t) != -1}]
181 set has_r [expr {[string length $params(r)] > 0}]
182 if {$has_t && $has_r} {
183 return -code error "Cannot specify both -r and -t"
184 } elseif {$has_t} {
185 ...
186 }
187 CMDLINE::GETOPT
190 This example shows the core loop of cmdline::getoptions from the previ‐
191 ous example. It demonstrates how it uses cmdline::get to process the
192 options one at a time.
193 while {[set err [getopt argv $opts opt arg]]} {
196 if {$err < 0} {
197 set result(?) ""
198 break
199 }
200 set result($opt) $arg
201 }
202
205 This document, and the package it describes, will undoubtedly contain
206 bugs and other problems. Please report such in the category cmdline of
207 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
208 also report any ideas for enhancements you may have for either package
209 and/or documentation.
210 When proposing code changes, please provide unified diffs, i.e the out‐
212 put of diff -u.
213 Note further that attachments are strongly preferred over inlined
215 patches. Attachments can be made by going to the Edit form of the
216 ticket immediately after its creation, and then using the left-most
217 button in the secondary navigation bar.
218
220 argument processing, argv, argv0, cmdline processing, command line pro‐
221 cessing
222
224 Programming tools
225tcllib 1.5.2 cmdline(n)