2.4 Include Files and Callbacks

So far, our examples have only considered the basic features of Genparse. In fact, these features are probably more than enough for 90% of all command line parsing needs. However, some programs require additional flexibility. In this section, we explore some of the advanced features of Genparse.

Include files may be specified at the beginning of a Genparse file. They are listed in C style, e.g., #include <file.h> or #include "file.h". One of the possible uses of include files are for when a macro needs to be used in a Genparse file. Consider the following modification to mycopy3.gp.

/* mycopy3.gp */
#include <mycopy3.h>
i / iterations	int	1	[0...MAX]	"Number of times to output <file>."
o / outfile	string	{""}			"Output file."

#usage_begin
usage: __PROGRAM_NAME__ __OPTIONS_SHORT__ file
Print a file for a number of times to stdout.
__GLOSSARY__
#usage_end

This example assumes that the macro MAX is defined in mycopy3.h.

In order to demonstrate the utility of callback functions, let’s further modify mycopy3.gp. In fact, let’s just call it mycopy4.gp.

/* mycopy4.gp */
#include <mycopy4.h>
my_callback ()
i / iterations	int	1	[1..MAX]	"Number of times to output <file>."
o / outfile	string	{""}	outfile_cb ()	"Output file."

#usage_begin
usage: __PROGRAM_NAME__ __OPTIONS_SHORT__ file
Print a file for a number of times to stdout.
__GLOSSARY__
#usage_end

This file instructs Genparse to create a global callback function my_callback () and the option callback function outfile_cb ().

For these callbacks, Genparse adds prototypes to the header file, a call to the parser file, and callback skeletons in a callback file. Rather than display the whole header and parse files, we’ll just show the lines that are added.

Callback functions are useful if extra processing needs to occur before one or more parameters are used by the main program. For example, if one parameter is dependent on the values of two others, a user-defined global callback function can contain the logic to check for the proper conditions.

/* mycopy4_clp.h */
/* global and local callbacks */
int my_callback (struct arg_t *);
int outfile_cb (char *);

In the mycopy4_clp.h file, prototypes for the global and the option callback functions are added.

/* mycopy4_clp.c */

  case 'o': 
    my_args->o = optarg;
    if (!outfile_cb (my_args->o))
      usage (EXIT_FAILURE, argv[0]);
    break;

...

if (!my_callback (my_args)) 
  usage (argv[0]);

In the mycopy4_clp.c file, a call to the callback functions is made. If a 0 is returned, an error is assumed and the usage function is called.

The main difference in Genparse behavior that including callbacks produces is the creation of a callback file. This file contains skeletons of all of the callback functions. It is up to the user to fill them in. Note that callbacks should return 0 on error and non-zero otherwise.

/* mycopy4_clp_cb.c */

#include <stdio.h>
#include "mycopy4_clp.h"

/*----------------------------------------------------------------------------
**
** my_callback ()
**
** User defined global callback.
**
**--------------------------------------------------------------------------*/

int my_callback (struct arg_t *a)
{
  return 1;
}

/*----------------------------------------------------------------------------
**
** outfile_cb ()
**
** User defined parameter callback.
**
**--------------------------------------------------------------------------*/

int outfile_cb (char * var)
{
  return 1;
}

Note that the struct arg_t structure must be passed to the global callback, while the option value is expected to be passed in character array format to option callbacks.