cmdline(3tcl) Command line and option processing cmdline(3tcl)
______________________________________________________________________________
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 oc-
curred.
argvVar contains the name of the list of arguments to process.
If options are found the list is modified and the processed ar-
guments are removed from the start of the list.
optstring contains a list of command options that the applica-
tion will accept. If the option ends in ".arg" the command will
use the next argument as an argument to the option, or extract
it from the current argument, if it is of the form "op-
tion=value". 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 exten-
sion).
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 gen-
erated 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 by throwing an error 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 op-
tional 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 ar-
gument. On Unix, only file existence is tested. If a file ar-
gument produces no valid files, a warning is optionally gener-
ated (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.
ERROR CODES
Starting with version 1.5 all errors thrown by the package have a
proper ::errorCode for use with Tcl's try command. This code always has
the word CMDLINE as its first element.
EXAMPLES
package require Tcl 8.5
package require try ;# Tcllib.
package require cmdline 1.5 ;# First version with proper error-codes.
# Notes:
# - Tcl 8.6+ has 'try' as a builtin command and therefore does not
# need the 'try' package.
# - Before Tcl 8.5 we cannot support 'try' and have to use 'catch'.
# This then requires a dedicated test (if) on the contents of
# ::errorCode to separate the CMDLINE USAGE signal from actual errors.
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:"
try {
array set params [::cmdline::getoptions argv $options $usage]
} trap {CMDLINE USAGE} {msg o} {
# Trap the usage signal, print the message, and exit the application.
# Note: Other errors are not caught and passed through to higher levels!
puts $msg
exit 1
}
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 Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
also report any ideas for enhancements you may have for either package
and/or documentation.
When proposing code changes, please provide unified diffs, i.e the out-
put of diff -u.
Note further that attachments are strongly preferred over inlined
patches. Attachments can be made by going to the Edit form of the
ticket immediately after its creation, and then using the left-most
button in the secondary navigation bar.
KEYWORDS
argument processing, argv, argv0, cmdline processing, command line pro-
cessing
CATEGORY
Programming tools
tcllib 1.5 cmdline(3tcl)