Tcl Library Source Code

Documentation
Login
Bounty program for improvements to Tcl and certain Tcl packages.


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

cmdline - Procedures to process command lines and options.

Table Of Contents

SYNOPSIS

package require Tcl 8.2
package require cmdline ?1.5.1?

::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

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

cmdline::getoptions

This example, taken from the package fileutil and slightly modified, demonstrates how to use cmdline::getoptions. 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.

        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]

	    # Note: argv is modified now. The recognized options are
	    # removed from it, leaving the non-option arguments behind.
        } 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} {
	    ...
        }

cmdline::getopt

This example shows the core loop of cmdline::getoptions from the previous example. It demonstrates how it uses cmdline::get to process the options one at a time.

    while {[set err [getopt argv $opts opt arg]]} {
	if {$err < 0} {
            set result(?) ""
            break
	}
	set result($opt) $arg
    }

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. 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 output 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 processing

CATEGORY

Programming tools