Home · Pages · Index · Overviews

System Utilities & Command Line Interface Module Reference

A flexible command line processing suite and guarded system utilities. More...

 #include <utilities.h>

Macro Constants

  ASCII = 128
Ascii characters have values from 0 to ASCII-1

Routines

Command Line Processor

void Process_Arguments (int argc, char **argv, char **spec, int no_escapes)

char * Program_Name ()

int Get_Repeat_Count (char *name)
int Is_Arg_Matched (char *name, ... int no X)

int Get_Int_Arg (char *name, ... int no X, int an X)
double Get_Double_Arg (char *name, ... int no X, int an X)
char * Get_String_Arg (char *name, ... int no X, int an X)

void Print_Argument_Usage (FILE *file, int no_escapes)

Guarded System Calls

void * Guarded_Malloc (int size, char *routine)
void * Guarded_Realloc (void *array, int size, char *routine)
char * Guarded_Strdup (char *string, char *routine)
FILE * Guarded_Fopen (char *name, char *options, char *routine)

Detailed Description

Command Line Processor

All UNIX programs take arguments from the command line as an array argv of argc strings. It becomes quite tedious to copy and retailor code for processing the command line each time you write a new program. To alleviate this mylib provides the routine Process_Arguments that interprets the command line arguments from a specification, where the specification can be a complex pattern that also serves as the usage statement shown to a user of the program in the event a user invokes the program improperly. Process_Arguments stores the results of its command-line interpretation in a permanent table so that you can then get the value of any command-line argument at any time during the subsequent computation of your program with a number of simple access routines, e.g. Get_Int_Arg, Get_String_Arg, etc.

Our design goal for this utility was to encompass as many of the features and styles of command line interfaces and conventions as possible. To do this required a quite flexible and powerful specification language whose semantics are compicated enough that (a) it takes a bit of effort to understand, and (b) you can create some pretty surprising patterns if you wish. As such we refer you to the document Command.Line for a 7 page description of the specification language along with lots of examples.

To give one example, the specification:

 static char *Spec[] =
     { "[-{m|matrix} <file(PAM120)>] [-{t|thresh} <int(40)>] <query:file> <db:file> ...",
       NULL
     };

for a program called, say "sw", would result in a usage statement of the form:

 Usage: sw [-{m|matrix} <file(PAM120)>] [-{t|thresh} <int(40)>] <query:file> <db:file> ...

which specifies that there are options -m and -t, with long forms -matrix and -thresh, respectively, for specifying a scoring matrix (where the default is PAM120) and threshold level for a match (where the default is 40). The first required argument is a file containing a query sequence followed by one or more files to be searched against. Calling Process_Arguments with Spec at the start of your program effectively interprets the command line for the syntax above, printing the usage statement if not correct. Then anywhere within your program, the call Get_Int_Arg("-t") will return the value for the threshold argument, Get_Repeat_Count("db") will return the number of files to be searched, Get_String_Arg("db",2) will return the file name of the 3rd file to be searched (if present), and so on.

Guarded System Calls

Standard library routines such as malloc and fopen can fail for a number of reasons and one should detect the failure. We provide simple guarded versions of these routines that check for a failure, and if they encounter one, then the print an error message and exit with status 1. For most batch applications this is just fine and saves one having to write a few extra lines of code where ever these functions are needed.

The generated object management routines call these guarded system routines. In a module where stopping the program doesn't make sense, e.g. the image I/O module, we simply declared a static version of the routines and redefined their behavior, so that when the object management code is compiled it refers to the redefined, private version of the routines.


Macro Constants Documentation

ASCII= 128


Routine Documentation

void Process_Arguments (int argc, char **argv, char **spec, int no_escapes)

This should be one of the very first if not the first call in the main routine of a program. The argc arguments in argv from the command line are parsed and interpreted according to spec. Rather than giving the specification as a single string, one gives it as an array of strings whose last element is NULL and where the concatenation of the strings in the array is the specification. The reason for this is to allow you to control exactly what the usage statement will look like, as each string will be output as a line of the specification, offset by the program name. For example, consider the specification:

   static char *Spec[] = { "[-m <int>] [!xyz] [-c'(<int>')]",
                           "  <arg1:int>  <arg2:int>",
                           NULL;
                         };

and suppose that the compiled program is called, say my_program. Then the usage statement that will be printed by Print_Argument_Usage (see below) is:

   Usage: my_program [-m <int>] [-xyz] [-c'(<int>')]
                       <arg1:int>  <arg2:int>

if the argument no_escapes is false, and:

   Usage: my_program [-m <int>] [-xyz] [-c(<int>)]
                       <arg1:int>  <arg2:int>

if no_escapes is true.

The possible syntax for a command line is documented in detail in the document Command.Line as it is too complex for a description here. Suffice it to say that it was designed to be very flexible and to encompass as many of the command line argument prototypes found amongst the common UNIX utilities.

Note carefully that the routine catches two classes of errors -- those made by the programmer and those made by the user. The author of the program should be certain to thoroughly debug the specification and the access calls so that the only errors a user sees are those due to their giving the program invalid input on the command line. Messages to the user always begin with the program name and messages to the implementor always begin with "Error in <routine name>:". Messages to the user always end with a usage statement for the program, thus the necessity of having no_escapes as a parameter to Process_Arguments.

This routine parses the command line and saves all the values obtained there from in a set of global state variables, so that all the following routines, that provide access to what was parsed, can be called anywhere within the code base of ones program. This is obviously not re-entrant.

char * Program_Name ()

Returns a pointer the name of the program.

int Get_Repeat_Count (char *name)

Returns 0 if the named unit is not in a repetition or if the repetition it is in was not used in making the match to the command line. Otherwise returns the number of times the repetition containing the named unit was iterated to match the command line. Note carefully that the name should not contain any escaping quotes that might have been necessary in the specification.

int Is_Arg_Matched (char *name, ... int no X)

For a given unit name, returns true if and only if the unit instance has been matched.

int Get_Int_Arg (char *name, ... int no X, int an X)

Returns the integer value of the argument whose name is name. If the argument is in a repetition then you must supply the parameter no, and the routine returns the noth instance. If the argument is one of several in a multi-value option, then you must also supply the parameter an, and the routine returns the anth value in the option.

double Get_Double_Arg (char *name, ... int no X, int an X)

Exactly like Get_Int_Arg save that the returned value is double.

char * Get_String_Arg (char *name, ... int no X, int an X)

Exactly like Get_Int_Arg save that the returned value is a string.

void Print_Argument_Usage (FILE *file, int no_escapes)

Prints a usage message for the program to stream file. The message is taken directly from the specification as discussed under the description of Process_Arguments. If the argument no_escapes is true then any escape characters are removed from the display of the specification.

void * Guarded_Malloc (int size, char *routine)

Calls the system routine malloc with size and returns the pointer it recieves from said, unless the result is NULL in which case an out-of-memory message is printed with routine indicated as the source of the request, and the program is exited with status 1.

void * Guarded_Realloc (void *array, int size, char *routine)

Calls the system routine realloc with array and size and returns the pointer it recieves from said, unless the result is NULL in which case an out-of-memory message is printed with routine indicated as the source of the request, and the program is exited with status 1.

char * Guarded_Strdup (char *string, char *routine)

Calls the system routine strdup with string and returns the pointer it recieves from said, unless the result is NULL in which case an out-of-memory message is printed with routine indicated as the source of the request, and the program is exited with status 1.

FILE * Guarded_Fopen (char *name, char *options, char *routine)

Calls the system routine fopen with file_name and options and returns the FILE pointer it recieves from said, unless the result is NULL in which case cannot-open-file message is printed with routine indicated as the source of the request, and the program is exited with status 1.