Annotation of embedaddon/confuse/doc/tutorial-html/ar01s06.html, revision 1.1.1.2
1.1.1.2 ! misho 1: <?xml version="1.0" encoding="UTF-8" standalone="no"?>
! 2: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>6. Validating callback functions</title><link rel="stylesheet" type="text/css" href="tutorial.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="home" href="index.html" title="libConfuse tutorial" /><link rel="up" href="index.html" title="libConfuse tutorial" /><link rel="prev" href="ar01s05.html" title="5. Parsing from internal buffers" /><link rel="next" href="ar01s07.html" title="7. Value parsing callback" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">6. Validating callback functions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s05.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s07.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm109"></a>6. Validating callback functions</h2></div></div></div><p>
1.1 misho 3: Remember the problem about a negative or too large "repeat" value
1.1.1.2 ! misho 4: in <a class="xref" href="ar01s02.html#negative-repeat-problem">Section 2, “Other types of options”</a>? The code that prints
1.1 misho 5: the greeting has those lines:
6: </p><pre class="programlisting">
7: ...
8: repeat = cfg_getint(cfg_greet, "repeat");
9: while(repeat--)
10: ...
11: </pre><p>
12: The repeat variable is defined as an int, a signed integer. If the user
13: specified a negative repeat value in the configuration file, this code
14: would continue to decrease the repeat variable until it eventually
15: underflowed.
16: </p><p>
17: We'll fix this by not allowing a negative value in the configuration
18: file. Of course we could first just check if the value is negative
19: and then abort, using <code class="function">cfg_getint()</code> and a test.
20: But we will use a validating callback function instead. This way
21: <code class="function">cfg_parse()</code> will return an error directly when
22: parsing the file, additionally indicating on which line the error
23: is.
24: </p><p>
25: A validating callback function is defined as:
26: </p><pre class="programlisting">
27: typedef int (*cfg_validate_callback_t)(cfg_t *cfg, cfg_opt_t *opt);
28: </pre><p>
29: This function takes two arguments: the section and the option. It
30: should return 0 on success (ie, the value validated ok). All other
31: values indicates an error, and the parsing is aborted. The callback
32: function should notify the error itself, for example by calling
33: <code class="function">cfg_error()</code>.
34: </p><p>
35: Here is the code for the callback function:
36: </p><a id="listing7"></a><pre class="programlisting">
37: 1 int validate_unsigned_int(cfg_t *cfg, cfg_opt_t *opt)
38: 2 {
39: 3 int value = cfg_opt_getnint(opt, cfg_opt_size(opt) - 1);
40: 4 if(value < 0)
41: 5 {
42: 6 cfg_error(cfg, "integer option '%s' must be positive in section '%s'",
43: 7 opt->name, cfg->name);
44: 8 return -1;
45: 9 }
46: 10 return 0;
47: 11 }
48: 12
49: </pre><p>
50: Only the last value is validated, because libConfuse will call this
51: function once for every value corresponding to the option. Since
52: the "repeat" option is not a list, we could instead have used
53: <code class="function">cfg_opt_getint(opt)</code> to retrieve the only
54: value. However, if we later want to use this callback to validate
55: an integer list, it is already lists-aware.
1.1.1.2 ! misho 56: </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idm126"></a>6.1. Installing the callback</h3></div></div></div><p>
1.1 misho 57: The validating callback is installed with
58: <code class="function">cfg_set_validate_func()</code>. It is called with
59: a string specifying which option is affected, and a pointer to
60: the callback function. To specify an option in a subsection,
61: the section and the option must be separated with a vertical
62: bar ("|").
63: </p><p>
64: We're now also looking at the return code from
65: <code class="function">cfg_parse()</code> to verify that the parsing was
66: successful. The complete program is now:
67: </p><a id="listing8"></a><pre class="programlisting">
68: 1 #include <stdio.h>
69: 2 #include <confuse.h>
70: 3
71: 4 int validate_unsigned_int(cfg_t *cfg, cfg_opt_t *opt)
72: 5 {
73: 6 int value = cfg_opt_getnint(opt, cfg_opt_size(opt) - 1);
74: 7 if(value < 0)
75: 8 {
76: 9 cfg_error(cfg, "integer option '%s' must be positive in section '%s'",
77: 10 opt->name, cfg->name);
78: 11 return -1;
79: 12 }
80: 13 return 0;
81: 14 }
82: 15
83: 16 int main(void)
84: 17 {
85: 18 cfg_opt_t greet_opts[] =
86: 19 {
87: 20 CFG_STR_LIST("targets", "{World}", CFGF_NONE),
88: 21 CFG_INT("repeat", 1, CFGF_NONE),
89: 22 CFG_END()
90: 23 };
91: 24 cfg_opt_t opts[] =
92: 25 {
93: 26 CFG_SEC("greeting", greet_opts, CFGF_TITLE | CFGF_MULTI),
94: 27 CFG_END()
95: 28 };
96: 29 cfg_t *cfg, *cfg_greet;
97: 30 int repeat;
98: 31 int i, j;
99: 32
100: 33 cfg = cfg_init(opts, CFGF_NONE);
101: 34 cfg_set_validate_func(cfg, "greeting|repeat", validate_unsigned_int);
102: 35 if(cfg_parse(cfg, "hello.conf") == CFG_PARSE_ERROR)
103: 36 return 1;
104: 37
105: 38 for(j = 0; j < cfg_size(cfg, "greeting"); j++)
106: 39 {
107: 40 cfg_greet = cfg_getnsec(cfg, "greeting", j);
108: 41
109: 42 repeat = cfg_getint(cfg_greet, "repeat");
110: 43 while(repeat--)
111: 44 {
112: 45 printf("%s", cfg_title(cfg_greet));
113: 46 for(i = 0; i < cfg_size(cfg_greet, "targets"); i++)
114: 47 printf(", %s", cfg_getnstr(cfg_greet, "targets", i));
115: 48 printf("!\n");
116: 49 }
117: 50 }
118: 51
119: 52 cfg_free(cfg);
120: 53 return 0;
121: 54 }
122: 55
1.1.1.2 ! misho 123: </pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s05.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5. Parsing from internal buffers </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 7. Value parsing callback</td></tr></table></div></body></html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>