::unibase::getflags: How to add command line flags

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.

Parsing the command line will create a number of variables in the $::UB_FLAGS namespace. Your program can then use these variables.

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	We set 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. For Select, you choose one of the valid options. For Booleans, if the flag is present, we set the variable’s value 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 you don’t provide the required variable, we print the USAGE message, and your program will exit. By default, the variable isn’t required, and supplying it 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

You must start flags with at least one “–“. Otherwise, we interpret them as words.

You can define multiple flags for the same variable. For strings, the last argument is the value.

We collect arguments not part of a flag into a global list called $::UB_FLAGS::_GLOBAL.

Select

We provide lists of available options with 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.