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.3.1?
14 ::cmdline::getopt argvVar optstring optVar valVar
16 ::cmdline::getKnownOpt argvVar optstring optVar valVar
18 ::cmdline::getoptions arglistVar optlist ?usage?
20 ::cmdline::getKnownOptions arglistVar 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 ::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 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 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 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 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 ::cmdline::getKnownOpt argvVar optstring optVar valVar
61 Like ::cmdline::getopt, but ignores any unknown options in the
62 input.
63 ::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 optlist contains a list of lists where each element specifies an
73 option in the form: flag default comment.
74 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 ::cmdline::getKnownOptions arglistVar optlist ?usage?
81 Like ::cmdline::getoptions, but ignores any unknown options in
82 the input.
83 ::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 ::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 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 ::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
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 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 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
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
143 argument processing, argv, argv0, cmdline processing, command line pro‐
144 cessing
145cmdline 1.3.1 cmdline(n)