NAME¶
cmdline - Procedures to process command lines and options.
SYNOPSIS¶
package require
Tcl 8.2
package require
cmdline ?1.3.3?
::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 leading '-' 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.
The options -?, -help, and -- are implicitly
understood. The first two abort option processing and force the generation
of the usage message, whereas the the last aborts option processing
without an error, leaving all arguments coming after for regular
processing, even if starting with a dash.
The result of the command is a dictionary mapping all options to their
values, be they user-specified or defaults.
- ::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
argv0. 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. Subsequently, 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://sourceforge.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