Provided by: clig_1.9.11.1-3_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  when‐
        ever  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  imple‐
        mented.)
 
        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 dec‐
        larations 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. Con‐
        sequently, 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 any‐
        thing except entries created with the declarator functions.
 
    parseCmdline
        After declaring the database and sourcing your declarations  from  cmd     
        line.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.
        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)