::unibase::getflags

SYNOPSIS

::unibase::getflags {PROGRAM ARGUMENTS}

DESCRIPTION

process command line arguments in a similar format to standard Linux commands.

This command adds command line flags to your program. Not however that every argument must have a flag. However not every flag has an argument.

The result of parsing the command line will be a number of variables in the ::UB_FLAGS namespace. These can then be used by your program.

ARGUMENTS

PROGRAM	Name of your program. eg ubCreateCustomer
ARGUMENTS	A Tcl list of Tcl dict defined flags and control values

FLAG OPTIONS

variable	Name of a variable that will be created in the namespace ::UB_FLAGS.
flag	The flag that will set the variable. eg –customer
type	The type of the value. either string, list, select, or boolean. Strings include numbers and require a value. Lists support multiple instances of the flag on the command line and the variable is a Tcl list of all the values. Select. Choose one of the valid options. Booleans. If present the value of the variable is set to 1, otherwise it will be 0.
usage	A string to add to the USAGE message that is printed if there is an error.
required	This argument is required. 1 – required 0 – not required If the variable is required but not present the USAGE message is printed and your program will exit. Default is not required and supplying this variable is optional.
default	Default value if argument is a string or list.

CREATE THE DICTIONARY

Your program must start by requiring the unibase package:

package require unibase

Next the dictionary is created. This stub shows how to add 4 variables to the command line flags

set FLAGLIST [list]
lappend FLAGLIST [dict create variable APPLICATION flag --application type string usage {<application name>} required 1]
lappend FLAGLIST [dict create variable CUSTOMER flag --customer type string usage {<customer name>} required 1]
lappend FLAGLIST [dict create variable EMAIL flag --email type string usage {<email>} required 1]
lappend FLAGLIST [dict create variable FINANCIAL flag --financial type boolean usage "" required 1]
lappend FLAGLIST [dict create variable TABLES flag --table type list usage {<table name>} required 0]
lappend FLAGLIST [dict create variable INTERPRETER flag --int type select options {bash,tcl} default tcl usage {<output format>}

Then you can call getflags:

::unibase::getflags ubCreateCompany $FLAGLIST

When it returns $::UB_FLAGS will be populated with your variables and their values.

You can refer to the variables as, eg, $::UB_FLAGS::CUSTOMER

Flags must start with at least one “-“. Otherwise they are interpreted as words.

Multiple flags can be defined for the same variable. For strings the last argument is the value.

Arguments not part of a flag are collected into a global list called ::UB_FLAGS::_GLOBAL

Select

Lists of available options are given by the keyword “options”. A list is a comma separated list of valid values.

eg lappend FLAGLIST [dict create variable FORMAT flag –format type select options {tcl,bash} usage {} required 0 default tcl]

This adds the option –format with valid values “tcl” and “bash”. Any other value triggers an error message.

If required is 1 a valid value must be provided.

In this case a default value “tcl” is specified.

A note on Tcl dict

A Tcl dict is simply a collection of key/value pairs. A dict can be recursive – ie a value can also be a dict.

dict create is followed by the key/value pairs and returns the created dictionary.

Essentially a dict is an associative array, but easier to set up and maintain and a bit more flexible.

dict is well documented in the Tcl documentation and various tutorials.