DragonFly On-Line Manual Pages

CLIG(1)                       Programmer's Manual                      CLIG(1)

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

Kir                                1.9.11.1                            CLIG(1)