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>libConfuse tutorial</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="next" href="ar01s02.html" title="2. Other types of options" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">libConfuse tutorial</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s02.html">Next</a></td></tr></table><hr /></div><div class="article"><div class="titlepage"><div><div><h2 class="title"><a id="idm1"></a>libConfuse tutorial</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Martin</span> <span class="surname">Hedenfalk</span></h3></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="index.html#idm7">1. Introducing libConfuse in an existing program</a></span></dt><dd><dl><dt><span class="sect2"><a href="index.html#idm29">1.1. Environment variables in values</a></span></dt></dl></dd><dt><span class="sect1"><a href="ar01s02.html">2. Other types of options</a></span></dt><dt><span class="sect1"><a href="ar01s03.html">3. Introducing lists</a></span></dt><dt><span class="sect1"><a href="ar01s04.html">4. Using sections</a></span></dt><dt><span class="sect1"><a href="ar01s05.html">5. Parsing from internal buffers</a></span></dt><dt><span class="sect1"><a href="ar01s06.html">6. Validating callback functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="ar01s06.html#idm126">6.1. Installing the callback</a></span></dt></dl></dd><dt><span class="sect1"><a href="ar01s07.html">7. Value parsing callback</a></span></dt><dt><span class="sect1"><a href="ar01s08.html">8. Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="ar01s08.html#idm145">8.1. Predefined functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="ar01s09.html">9. Saving configuration files</a></span></dt><dd><dl><dt><span class="sect2"><a href="ar01s09.html#idm157">9.1. Altering the printing of certain options</a></span></dt></dl></dd></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm7"></a>1. Introducing libConfuse in an existing program</h2></div></div></div><p>Consider this simple program:</p><a id="listing1"></a><pre class="programlisting">
3: 1 #include <stdio.h>
4: 2
5: 3 int main(void)
6: 4 {
7: 5 printf("Hello, World!\n");
8: 6 return 0;
9: 7 }
10: 8
11: </pre><p>
12: Simple enough, but we want to extend the program so we can greet
13: others. Maybe we don't want to greet the whole world, just our
14: neighbour. We use libConfuse to let the user decide whom to greet.
15: </p><a id="listing2"></a><pre class="programlisting">
16: 1 #include <stdio.h>
17: 2 #include <confuse.h>
18: 3
19: 4 int main(void)
20: 5 {
21: 6 cfg_opt_t opts[] =
22: 7 {
23: 8 CFG_STR("target", "World", CFGF_NONE),
24: 9 CFG_END()
25: 10 };
26: 11 cfg_t *cfg;
27: 12
28: 13 cfg = cfg_init(opts, CFGF_NONE);
29: 14 if(cfg_parse(cfg, "hello.conf") == CFG_PARSE_ERROR)
30: 15 return 1;
31: 16
32: 17 printf("Hello, %s!\n", cfg_getstr(cfg, "target"));
33: 18
34: 19 cfg_free(cfg);
35: 20 return 0;
36: 21 }
37: 22
38: </pre><p>
39: All programs using libConfuse must first include the
40: <code class="filename">confuse.h</code> header file. This is done on line
41: 2.
42: </p><p>
43: On line 6 - 10, the options that should be recognized are defined in an
44: array of cfg_opt_t structs. This is passed to the
45: <code class="function">cfg_init</code> function on line 13. The resulting
46: <span class="structname">cfg_t</span> context is used by
47: <code class="function">cfg_parse()</code>, which reads the configuration file
48: "hello.conf". When reading the configuration file, only options defined in
49: the array of options passed to <code class="function">cfg_init()</code> are
50: recognized.
51: </p><p>
52: The friendly greeting is now replaced with a parameter read from the
53: configuration file. The value of the <code class="varname">target</code> option is retrieved with
54: <code class="function">cfg_getstr(cfg, "target")</code>.
55: </p><p>
56: Lets take a look at the configuration file hello.conf:
57: </p><pre class="programlisting">
58: # this is the configuration file for the hello program
59:
60: target = "Neighbour"
61: </pre><p>
62: Here, the target option is set to the string value "Neighbour".
63: What if the configuration file was empty or didn't exist? Then the
64: default value for the <code class="varname">target</code> option would be
65: used. When we initialized our options, the second parameter to the
66: <code class="function">CFG_STR()</code> macro specified the default value.
67: Thus, if no <code class="varname">target</code> option was specified in the
68: configuration file, the hello program would have printed the
69: standard greeting "Hello, World".
70: </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idm29"></a>1.1. Environment variables in values</h3></div></div></div><p>
71: What else can we do in the configuration file? We can set the value to an
72: environment variable:
73: </p><pre class="programlisting">
74: target = ${USER}
75: </pre><p>
76: This results in the hello program greeting the user who runs it. On some
77: systems, the USER variable might not be available, so we want to specify a
78: default value in those cases:
79: </p><pre class="programlisting">
80: target = ${USER:-User}
81: </pre><p>
82: Now, if the USER environment variable is unset, the string "User" will be
83: used instead.
84: </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> 2. Other types of options</td></tr></table></div></body></html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to index.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / confuse / doc / tutorial-html