C/Tcl Interface - Command Line Parsing

This page describes the Tcl procedure itfParseArgv and the C-function itfParseArgv(). You are strongly encouraged to use them to make the Tcl and C sources both, mor readable and more uniformly usable. Don't annoy the user by not reacting on -help options to methods, or running into problems after incorrect arguments have not been checked.

Both, the Tcl procedure and the C function work very similar. Both expect an object (for which the method was called) and an argument list (argc, argv in C, and a simple list in Tcl). In C the argument list consists (besides administrativia) of multiple blocks of six single arguments, and in Tcl the argument list consists of muliple sublists of six elements each. For both, the C and the Tcl version, the six items have the following meanings:

1. item

The name of the arguement.

2. item

The type of the argument in C is one of the follwing constants

ARGV_SHORT for short type values
ARGV_INT for int type values
ARGV_FLOAT for float type values
ARGV_DOUBLE for double type values
ARGV_STRING for char* type values
ARGV_IARRAY for a list of int type values
ARGV_LIARRAY for a list of names of items from the list that is given in the 5th item which will automatically be transformed to indices
ARGV_OBJECT for void* type values to object from the type that is given in the 5th item
ARGV_LINDEX for a single name of an element from the list that is given in the 5th item which will automatically be transformed to an index
ARGV_CUSTOM make the custom function given in the 3rd item to parste the next arguments
ARGV_REST ignore the rest of the arguments (might be parsed by the calling function itself)

The type of the argument in Tcl is one of the follwing constants

int for integer type values
float for floating point type values
string for string (i.e. any) type values
iarray for a list of integer type values
liarray for a list of names of items from the list that is given in the 5th item which will automatically be transformed to indices
object for the name of an object from the type that is given in the 5th item
lindex for a single single name of an element from the list that is given in the 5th item which will automatically be transformed to an index

3. item

Not yet used in Tcl, in C it is a pointer to a custom function that can parse some portion of the argument list. See the details about the C version below.

4. item

In C, this is the pointer to a variable in which the parsed result will be stored. In Tcl it is the name of such a variable. Note that, although the name of the argument is "iarray" or "liarray" the returned value is not a Tcl-Array, but a list.

5. item

If the type of the argument that is to be parsed is an object, then you have to provide the name of the object type here. If the type of the argument is a list index or an array of list indices then you have to provide the list (pointer in C, name in Tcl) here.

6. item

A help text, that will be printed, if the user type the option -help.

So much about theory. To learn the usage of itfParseArgv you better look at some examples, or even at the source codes.

Details About The Tcl Version

The following is a both, an example usage of the itfParseArgv procedure, and a test script for its implementation. It defines a Tcl method m for the Phones object type, and calls itfParseArgv with several possible argument kinds.

[Phones p] add a b c d e f
FeatureSet fs

proc myproc { obj args } { 

  global p

  set fixPar1 123
  set fixPar2 alpha
  set fixPar3 {1 2}
  set optPar1 fs2
  set optPar2 y
  set optPar3 -1
  set optPar4 {7 8 9}

  itfParseArgv myproc $args [list [
    list <par1> int     {} fixPar1 {}         {first parameter}   ] [
    list <par2> string  {} fixPar2 {}         {second parameter}  ] [
    list <par3> liarray {} fixPar3 $obj.list  {third parameter}   ] [
    list -par4  object  {} optPar1 FeatureSet {fourth parameter}  ] [
    list -par5  char    {} optPar2 {}         {fifth parameter}   ] [
    list -par6  lindex  {} optPar3 $obj.list  {sixth parameter}   ] [
    list -par7  iarray  {} optPar4 {}         {seventh parameter} ] ] 

  puts "fixPar1 $fixPar1"
  puts "fixPar2 $fixPar2"
  puts "fixPar3 $fixPar3"
  puts "optPar1 $optPar1"
  puts "optPar2 $optPar2"
  puts "optPar3 $optPar3"
  puts "optPar4 $optPar4"
}

Phones method m myproc -text "helptext for method m"

# 
puts "----------------"
puts "get help message"
# 
puts [  p m -help ]

#
puts "---------------------------------------------------"
puts "regular call of method with all optional parameters"
#
puts [  p m 7 bla { d e a } -par6 c -par5 n -par4 fs -par7 { 3 4 5 } ]

#
puts "---------------------------"
puts "not enough fixed parameters"
#
puts [  p m 7 bla -par6 c ]

#
puts "------------------------------------------"
puts "too many fixed parameters (== sick option)"
#
puts [  p m 7 bla { d e a } sick -par5 n -par4 fs ]

#
puts "------------------------"
puts "illegal integer argument"
#
puts [  p m seven bla { d e a } -par5 n ]

#
puts "-----------------------"
puts "illegal object argument"
#
puts [  p m 7 bla { d e a } -par4 feat ]

#
puts "--------------------------"
puts "illegal character argument"
#
puts [  p m 7 bla { d e a } -par5 foo ]

#
puts "------------------------------"
puts "illegal integer array argument"
#
puts [  p m 7 bla { d e a } -par7 { 1 2 foo 3 } ]

And here comes the output of the test:

% source testParseArgv.tcl
----------------
get help message
Parameters of 'myproc' are:
 <par1>       first parameter (int:123)
 <par2>       second parameter (string:alpha)
 <par3>       third parameter (index array in p.list:1 2)
 -par4        fourth parameter (FeatureSet:fs2)
 -par5        fifth parameter (char:y)
 -par6        sixth parameter (index in p.list:-1)
 -par7        seventh parameter (iarray:7 8 9)
fixPar1 123
fixPar2 alpha
fixPar3 1 2
optPar1 fs2
optPar2 y
optPar3 -1
optPar4 7 8 9

---------------------------------------------------
regular call of method with all optional parameters
fixPar1 7
fixPar2 bla
fixPar3 3 4 0
optPar1 fs
optPar2 n
optPar3 2
optPar4 3 4 5

---------------------------
not enough fixed parameters
undefined option: c
Parameters of 'myproc' are:
 <par1>       first parameter (int:7)
 <par2>       second parameter (string:bla)
 <par3>       third parameter (index array in p.list:-1)
 -par4        fourth parameter (FeatureSet:fs2)
 -par5        fifth parameter (char:y)
 -par6        sixth parameter (index in p.list:-1)
 -par7        seventh parameter (iarray:7 8 9)
fixPar1 7
fixPar2 bla
fixPar3 -1
optPar1 fs2
optPar2 y
optPar3 -1
optPar4 7 8 9

------------------------------------------
too many fixed parameters (== sick option)
undefined option: sick
Parameters of 'myproc' are:
 <par1>       first parameter (int:7)
 <par2>       second parameter (string:bla)
 <par3>       third parameter (index array in p.list:3 4 0)
 -par4        fourth parameter (FeatureSet:fs2)
 -par5        fifth parameter (char:y)
 -par6        sixth parameter (index in p.list:-1)
 -par7        seventh parameter (iarray:7 8 9)
fixPar1 7
fixPar2 bla
fixPar3 3 4 0
optPar1 fs2
optPar2 y
optPar3 -1
optPar4 7 8 9

------------------------
illegal integer argument
expected int argument for <par1>, but got "seven"
fixPar1 123
fixPar2 alpha
fixPar3 1 2
optPar1 fs2
optPar2 y
optPar3 -1
optPar4 7 8 9

-----------------------
illegal object argument
expected FeatureSet argument for -par4, but got "feat"
fixPar1 7
fixPar2 bla
fixPar3 3 4 0
optPar1 fs2
optPar2 y
optPar3 -1
optPar4 7 8 9

--------------------------
illegal character argument
expected char argument for -par4, but got "foo"
fixPar1 7
fixPar2 bla
fixPar3 3 4 0
optPar1 fs2
optPar2 y
optPar3 -1
optPar4 7 8 9

------------------------------
illegal integer array argument
expected iarray argument for -par4, but got " 1 2 foo 3 "
fixPar1 7
fixPar2 bla
fixPar3 3 4 0
optPar1 fs2
optPar2 y
optPar3 -1
optPar4 7 8 9

C/Tcl Interface - Command Line Parsing

Details About The Tcl Version

And here comes the output of the test:

Details About The C Version