---
name: "clig_parseCmdline"
section: "7"
platform: "linux"
package: "clig"
version: "1.9.11.1-3"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/clig_parseCmdline"
---

# clig\_parseCmdline(7)

command line interpreter for Tcl

## NAME

::clig::parseCmdline - command line interpreter for Tcl

## SYNOPSIS

```
package require clig
namespace import ::clig::*
setSpec var
parseCmdline _spec argv0 argc argv
```

## DESCRIPTION

This manual page describes how to instrument your Tcl-scripts with a command line parser. It requires that package clig is installed whenever your script is run. To find out how to create a parser which is independent of clig, read [clig(1)](/clig/1.md). (Well, don't, it is not yet implemented.)

The options to be understood by your script must be declared with calls to ::clig::Flag, ::clig:String etc., which is best done in a separate file, e.g. cmdline.cli, to be sourced by your script. Having these declarations in a separate file allows you to run  **clig**, the program, on that file to create a basic manual page.

### setSpec

The option-declaring functions want to store the declarations in an array with a globally accessible name. For compatibility with older software, the name of this array can not be passed as a parameter. Consequently, your script must declare it before sourcing  **cmdline.cli**.

A call like

```
   setSpec ::main
```

declares  **::main** as the database (array) to be filled by subsequent calls to ::clig::Flag and the like. The array should not contain anything except entries created with the declarator functions.

### parseCmdline

After declaring the database and sourcing your declarations from **cmdline.cli** your script is ready to call parseCmdline. This is typically done with:

```
  set Program [file tail $argv0]
  if {[catch {parseCmdline ::main $Program $argc $argv} err]} {
    puts stderr $err
    exit 1
  }
```

If **parseCmdline** finds an unknown option in  **$argv**, it prints a usage-message to stderr and exits the script with exit-code 1. If it finds any other errors, like numerical arguments being out of range, it prints an appropriate error-message to stderr and also exits your script with code 1. Setting  **Program** and passing it to **parseCmdline** instead of **$argv0** results in nicer error-messages.

If no errors occur,  **parseCmdline** enters the values found into variables of its callers context. The names of these variables are those declared with the declarator functions. For example with a declaration like

```
  Float -ival ival {interval to take into account} -c 2 2
```

the caller will find the variable  **ival** set to a list with 2 elements, if option **-ival** was found with two numeric arguments in  **$argv**.

If option **-ival** is not existent on the given command line,  **ival** will not be set. Consequently, it is best to not set the declared variables to any value before calling **parseCmdline**.

### Summary

The typical skeleton of your script should look like

```
  package require clig
  namespace import ::clig::*
  setSpec ::main
  source [file join path to your installed base cmdline.cli]
  set Program [file tail $argv0]
  if {[catch {parseCmdline ::main $Program $argc $argv} err]} {
    puts stderr $err
    exit 1
  }
```

## REMARK

Of course **parseCmdline** can be called from a within any  **proc** with a specification database previously filled with the declarator functions. I am not using  **OptProc** because it is not documented and the declaration syntax used here was used for C-programs probably long before it existed.

## SEE ALSO

[clig\_Name(7)](/clig_Name/7.md), [clig\_Double(7)](/clig_Double/7.md), [clig(1)](/clig/1.md), [clig\_Usage(7)](/clig_Usage/7.md), [clig\_Long(7)](/clig_Long/7.md), [clig\_Version(7)](/clig_Version/7.md), [clig\_Float(7)](/clig_Float/7.md), [clig\_Rest(7)](/clig_Rest/7.md), [clig\_Description(7)](/clig_Description/7.md), [clig\_String(7)](/clig_String/7.md), [clig\_Flag(7)](/clig_Flag/7.md), [clig\_Commandline(7)](/clig_Commandline/7.md), [clig\_Int(7)](/clig_Int/7.md)