6. Validating callback functions

Remember the problem about a negative or too large "repeat" value in Section 2, “Other types of options”? The code that prints the greeting has those lines:

...
repeat = cfg_getint(cfg_greet, "repeat");
while(repeat--)
...
        

The repeat variable is defined as an int, a signed integer. If the user specified a negative repeat value in the configuration file, this code would continue to decrease the repeat variable until it eventually underflowed.

We'll fix this by not allowing a negative value in the configuration file. Of course we could first just check if the value is negative and then abort, using cfg_getint() and a test. But we will use a validating callback function instead. This way cfg_parse() will return an error directly when parsing the file, additionally indicating on which line the error is.

A validating callback function is defined as:

typedef int (*cfg_validate_callback_t)(cfg_t *cfg, cfg_opt_t *opt);
        

This function takes two arguments: the section and the option. It should return 0 on success (ie, the value validated ok). All other values indicates an error, and the parsing is aborted. The callback function should notify the error itself, for example by calling cfg_error().

Here is the code for the callback function:

01   int validate_unsigned_int(cfg_t *cfg, cfg_opt_t *opt)
02   {
03       int value = cfg_opt_getnint(opt, cfg_opt_size(opt) - 1);
04       if(value < 0)
05       {
06           cfg_error(cfg, "integer option '%s' must be positive in section '%s'",
07                   opt->name, cfg->name);
08           return -1;
09       }
10       return 0;
11   }
12   

Only the last value is validated, because libConfuse will call this function once for every value corresponding to the option. Since the "repeat" option is not a list, we could instead have used cfg_opt_getint(opt) to retrieve the only value. However, if we later want to use this callback to validate an integer list, it is already lists-aware.

6.1. Installing the callback

The validating callback is installed with cfg_set_validate_func(). It is called with a string specifying which option is affected, and a pointer to the callback function. To specify an option in a subsection, the section and the option must be separated with a vertical bar ("|").

We're now also looking at the return code from cfg_parse() to verify that the parsing was successful. The complete program is now:

01   #include <stdio.h>
02   #include <confuse.h>
03   
04   int validate_unsigned_int(cfg_t *cfg, cfg_opt_t *opt)
05   {
06       int value = cfg_opt_getnint(opt, cfg_opt_size(opt) - 1);
07       if(value < 0)
08       {
09           cfg_error(cfg, "integer option '%s' must be positive in section '%s'",
10                   opt->name, cfg->name);
11           return -1;
12       }
13       return 0;
14   }
15   
16   int main(void)
17   {
18       cfg_opt_t greet_opts[] =
19       {
20           CFG_STR_LIST("targets", "{World}", CFGF_NONE),
21           CFG_INT("repeat", 1, CFGF_NONE),
22           CFG_END()
23       };
24       cfg_opt_t opts[] =
25       {
26           CFG_SEC("greeting", greet_opts, CFGF_TITLE | CFGF_MULTI),
27           CFG_END()
28       };
29       cfg_t *cfg, *cfg_greet;
30       int repeat;
31       int i, j;
32   
33       cfg = cfg_init(opts, CFGF_NONE);
34       cfg_set_validate_func(cfg, "greeting|repeat", validate_unsigned_int);
35       if(cfg_parse(cfg, "hello.conf") == CFG_PARSE_ERROR)
36           return 1;
37   
38       for(j = 0; j < cfg_size(cfg, "greeting"); j++)
39       {
40           cfg_greet = cfg_getnsec(cfg, "greeting", j);
41   
42           repeat = cfg_getint(cfg_greet, "repeat");
43           while(repeat--)
44           {
45               printf("%s", cfg_title(cfg_greet));
46               for(i = 0; i < cfg_size(cfg_greet, "targets"); i++)
47                   printf(", %s", cfg_getnstr(cfg_greet, "targets", i));
48               printf("!\n");
49           }
50       }
51   
52       cfg_free(cfg);
53       return 0;
54   }
55