Linux Certif

Toute la documentation sur la certification Linux LPI

clig_parseCmdline

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). (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(1), clig_Commandline(7), clig_Description(7), clig_Double(7), clig_Flag(7), clig_Float(7), clig_Int(7), clig_Long(7), clig_Name(7), clig_Rest(7), clig_String(7), clig_Usage(7), clig_Version(7)