

------------------ argp::registerArgs -------------------------

argp::registerArgs procname argdefinelist

Initializes the optional argument parsing for procedure procname.

argp::registerArgs is aware of the namespace from which it was
called. This means: when called from the global namespace, procname
must be fully qualified, when called from within a namespace, the
procname must not be fully qualified.

The definition-list argdefinelist has this format:

    { ?optarg? ... }

where optarg stands for the definition of a single optional argument.
optarg is a list with this format:

    { argname argtype argdefault ?allowedvalues? }

 - argname is the name of the optional argument. Special case: use an
   empty string ("") for registering arguments that will be parsed in
   the main program.
 - argtype defines the type of the optional argument. Types recognized
   at the moment are: string, boolean, integer and double. The type
   can be abreviated.
 - argdefault defines the standard value assigned to this argument if
   it is not given.
 - allowedvalues defines the allowed values of the argument. This can
   be a single value or a list of values. In case of type integer and
   double, ranges can be given also. A range is a sublist containing
   two values: low and high. The special case '-' for low defines no
   lower bound, the special case '+' for high defines no upper bound.

If allowedvalues is given, the argdefault must be contained in the
allowed values.

Usage:

argp::registerArgs must be called just once for every function.
The usual place for calling this proc is within the namespace
declaration of the procs. Registering arguments for procs of a foreign
namespace is not possible in this case.

argp::registerArgs can also be called from the global namespace, but
then the procname must be fully qualified.


Examples:

Calling registerArgs from within the namespace eval:

    namespace eval somens {
    	argp::registerArgs someproc {
    	    { -name1 string "alpha" }
    	    { -name2 str "" {"" beta gamma} }
    	}
    }


Calling registerArgs from the global namespace:

    argp::registerArgs ns::someproc {
    	{ -val     int     0                                            }
    	{ -prime20 integer 2   {2 3 5 7 11 13 17 19}                    }
    	{ -val2    doub    -57 {{- -200} 0 2 4 6 8 {10 20} 30 { 20 + }} }
    }


This will cause an error, argdefault is not covered by allowedvalues:

    namespace eval somens {
    	argp::registerArgs someproc {
    	    { -prime20 integer 0 {2 3 5 7 11 13 17 19} }
    	}
    }


See also:

   argp::parseArgs, argp::setStandardArgs, argp::setArgsNeeded




----------------------- argp::parseArgs -------------------------

argp::parseArgs ?optionarrayname?

Parses optional arguments given to a proc (or to the program on the
commandline) and store them in the array named optionarrayname (or
'opts' if not given).


Usage:

argp::parseArgs will usually called at the beginning of a proc. It
will then extract all optional arguments given based on the
definitionlist given earlier by argp::registerArgs. 

parseArgs will reject unknown optional arguments or those whose value
does not fulfill the restrictions.


Example:

This example shows how to use argp::parseArgs in namespace procs:

  package require argp 0.1
  namespace eval demo {
      argp::registerArgs newCity {
  	  {-numcitizen integer 0 }
  	  {-nationality string american }
      }
  }
  proc demo::newCity { name args } {
      argp::parseArgs cityargs
  
      puts -nonewline "Creating $name, which has $cityargs(-numcitizen) "
      puts "citizen and is $cityargs(-nationality)."
  }
  demo::newCity "New York"
  demo::newCity "Paris" -numcitizen 5000000 -nationality french

This example shows how to use argp::parseArgs in procs in the global
namespace:

  package require argp 0.1
  argp::registerArgs newCity {
      {-numcitizen integer 0 }
      {-nationality string american }
  }
  proc newCity { name args } {
      argp::parseArgs cityargs
  
      puts -nonewline "Summoning $name, which has $cityargs(-numcitizen) "
      puts "citizen and is $cityargs(-nationality)."
  }
  newCity "New York"
  newCity "Paris" -numcitizen 5000000 -nationality french

The last example shows how to use argp::parseArgs to parse optional
arguments given on the commandline:

  package require argp 0.1
  argp::registerArgs "" {
      {-name   string  tclsh {tclsh tcl wish wishx}                }
      {-number integer 10    { { - -20 } { 5 100 } { 200 +} }      }
      {-%cpu   double  90    { 50.0 50.1 50.3  { 90 100 } }        }         
      {-alive  boolean 1     { 1 }                                 }
  }
  set args $argv         ;# this is important: copy argv to args :)
  argp::parseArgs opts
  foreach {k v} [array get opts] {
      puts "option $k has value $v"
  }


See also:

   argp::registerArgs, argp::setStandardArgs, argp::setArgsNeeded




---------------------- argp::setArgsNeeded -------------------------

argp::setArgsNeeded procname arglist

Sets the list of optional arguments that must be given when calling a
proc, making them, in fact non-optional anymore. Like
argp::registerArgs, this command is aware of the namespace from which
it was called, so procname must not be fully qualified, except when
called from the global namespace.

arglist is the list of optional arguments that are to be made
non-optional. 


Usage:
This command will usually be called once, after argp::registerArgs, to
set the non-optional arguments, but it may be called afterwards during
runtime to change the behaviour, too.


Example:
  package require argp 0.1
  namespace eval demo {
      argp::registerArgs newCity {
  	  {-numcitizen integer 0 }
  	  {-nationality string american }
  	  {-surface double 1.0 }
      }
      argp::setArgsNeeded newCity {-surface -numcitizen}
  }
  proc demo::newCity { name args } {
      argp::parseArgs cityargs
  
      puts -nonewline "Creating $name, which has $cityargs(-numcitizen) "
      puts "citizen and is $cityargs(-nationality)."
      puts "The city covers a surface of $cityargs(-surface) km^2."
  }
  catch {demo::newCity "New York"} res
  puts $res
  catch {demo::newCity "Paris" -numcitizen 5000000 -nationality french} res
  puts $res
  demo::newCity "Berlin" -numcitizen 3500000 -surface 147 -nationality german


See also:

   argp::registerArgs, argp::parseArgs argp::setStandardArgs




---------------------- argp::setArgDefaults -------------------------

argp::setArgDefaults procname argdefaults

Set new defaults for optional arguments, overriding the defaults given
at argp::registerArgs. argdefaults is a list and has the format:

   argname argdefaultval ?argname argdefaultval? ...


Examples:

package require argp 0.1
namespace eval demo {
    argp::registerArgs newCity {
	{-numcitizen integer 0 }
	{-nationality string american }
    }
}
proc demo::newCity { name args } {
    argp::parseArgs cityargs
    
    puts -nonewline "Creating $name, which has $cityargs(-numcitizen) "
    puts "citizen and is $cityargs(-nationality)."
}
demo::newCity "New York"
demo::newCity "Washington"
demo::newCity "Los Angeles"

argp::setArgDefaults demo::newCity {-nationality french}

demo::newCity "Paris" 
demo::newCity "Marseilles" 
demo::newCity "Strasbourg"

