Provided by: clig_1.9.10-4_all bug

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)