Annotation of embedaddon/confuse/doc/tutorial-html/ar01s04.html, revision 1.1
1.1 ! misho 1: <?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?>
! 2: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! 3: <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>4. Using sections</title><link rel="stylesheet" href="tutorial.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="libConfuse tutorial" /><link rel="up" href="index.html" title="libConfuse tutorial" /><link rel="prev" href="ar01s03.html" title="3. Introducing lists" /><link rel="next" href="ar01s05.html" title="5. Parsing from internal buffers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4. Using sections</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s03.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s05.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="4. Using sections"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id400837"></a>4. Using sections</h2></div></div></div><p>
! 4: So far, we have only use a flat configuration file. libConfuse can also handle
! 5: sections to build a hierarchy of options. Sections can be used to group options
! 6: in logical blocks, and those blocks can (optionally) be specified multiple
! 7: times.
! 8: </p><p>
! 9: Sections are initialized with the <code class="function">CFG_SEC()</code> macro. It also takes three
! 10: parameters: the name of the option, an array of options allowed in the section
! 11: and flags.
! 12: </p><p>
! 13: We'll extend the, now rather complex, hello program so we can do other kinds of
! 14: greetings, not just "Hello". Each greeting will have its own settings for
! 15: targets and repeat.
! 16: </p><a id="listing5"></a><pre class="programlisting">
! 17: 1 #include <stdio.h>
! 18: 2 #include <confuse.h>
! 19: 3
! 20: 4 int main(void)
! 21: 5 {
! 22: 6 cfg_opt_t greet_opts[] =
! 23: 7 {
! 24: 8 CFG_STR_LIST("targets", "{World}", CFGF_NONE),
! 25: 9 CFG_INT("repeat", 1, CFGF_NONE),
! 26: 10 CFG_END()
! 27: 11 };
! 28: 12 cfg_opt_t opts[] =
! 29: 13 {
! 30: 14 CFG_SEC("greeting", greet_opts, CFGF_TITLE | CFGF_MULTI),
! 31: 15 CFG_END()
! 32: 16 };
! 33: 17 cfg_t *cfg, *cfg_greet;
! 34: 18 int repeat;
! 35: 19 int i, j;
! 36: 20
! 37: 21 cfg = cfg_init(opts, CFGF_NONE);
! 38: 22 if(cfg_parse(cfg, "hello.conf") == CFG_PARSE_ERROR)
! 39: 23 return 1;
! 40: 24
! 41: 25 for(j = 0; j < cfg_size(cfg, "greeting"); j++)
! 42: 26 {
! 43: 27 cfg_greet = cfg_getnsec(cfg, "greeting", j);
! 44: 28
! 45: 29 repeat = cfg_getint(cfg_greet, "repeat");
! 46: 30 while(repeat--)
! 47: 31 {
! 48: 32 printf("%s", cfg_title(cfg_greet));
! 49: 33 for(i = 0; i < cfg_size(cfg_greet, "targets"); i++)
! 50: 34 printf(", %s", cfg_getnstr(cfg_greet, "targets", i));
! 51: 35 printf("!\n");
! 52: 36 }
! 53: 37 }
! 54: 38
! 55: 39 cfg_free(cfg);
! 56: 40 return 0;
! 57: 41 }
! 58: 42
! 59: </pre><p>
! 60: We have renamed the option array from "opts" to "greet_opts", and introduced a
! 61: new "opts" array that only has one option: a "greeting" section.
! 62: The second parameter of the <code class="function">CFG_SEC()</code> macro
! 63: points to the old greeting options "targets" and "repeat".
! 64: </p><p>
! 65: We have also used a couple of flags to alter the behaviour of the
! 66: section: CFGF_TITLE means that a greeting section should have a
! 67: title and the CFGF_MULTI flag tells libConfuse that this section
! 68: may be specified multiple times in the configuration file. The
! 69: title of a section is retrieved with the
! 70: <code class="function">cfg_title()</code> function.
! 71: </p><p>
! 72: The outmost loop (with index j) now loops through all given
! 73: sections in the configuration file. We retrieve a section with a
! 74: <code class="function">cfg_getnsec()</code> call. The value returned is a
! 75: pointer to a cfg_t struct, the same type as returned by
! 76: <code class="function">cfg_init()</code>. Thus we can use the ordinary value
! 77: retrieval functions <code class="function">cfg_getstr()</code>,
! 78: <code class="function">cfg_getint()</code> and so on to retrieve values of
! 79: options inside the section.
! 80: </p><p>
! 81: Ok, so how does the configuration file look like for this setup?
! 82: </p><pre class="programlisting">
! 83: # this is the configuration file for the hello program
! 84:
! 85: greeting Hello
! 86: {
! 87: targets = {"Life", "Universe", "Everything"}
! 88: repeat = 1
! 89: }
! 90:
! 91: greeting Bye
! 92: {
! 93: targets = {Adams}
! 94: repeat = 1
! 95: }
! 96: </pre><p>
! 97: The program will loop through the sections in the order specified
! 98: in the configuration file. First it will find the "Hello" section.
! 99: It prints the title of the section, "Hello", retrieved with
! 100: <code class="function">cfg_title()</code>. Then the targets are printed just
! 101: as in the previous exemples, but this time the values are retrieved
! 102: from the cfg_greet section. Next, the section titled "Bye" is
! 103: found, and the values are retrieved from that section.
! 104: </p><p>
! 105: When run, the program produces the following:
! 106: </p><pre class="programlisting">
! 107: $ ./listing5
! 108: Hello, Life, Universe, Everything!
! 109: Bye, Adams!
! 110: $
! 111: </pre></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s03.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. Introducing lists </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 5. Parsing from internal buffers</td></tr></table></div></body></html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>