Annotation of embedaddon/confuse/doc/tutorial-html/index.html, revision 1.1.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>libConfuse tutorial</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="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" title="libConfuse tutorial"><div class="titlepage"><div><div><h2 class="title"><a id="id433031"></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><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="index.html#id433064">1. Introducing libConfuse in an existing program</a></span></dt><dd><dl><dt><span class="sect2"><a href="index.html#id401812">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#id442390">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#id442506">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#id442560">9.1. Altering the printing of certain options</a></span></dt></dl></dd></dl></div><div class="sect1" title="1. Introducing libConfuse in an existing program"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id433064"></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">
4: 1 #include <stdio.h>
5: 2
6: 3 int main(void)
7: 4 {
8: 5 printf("Hello, World!\n");
9: 6 return 0;
10: 7 }
11: 8
12: </pre><p>
13: Simple enough, but we want to extend the program so we can greet
14: others. Maybe we don't want to greet the whole world, just our
15: neighbour. We use libConfuse to let the user decide whom to greet.
16: </p><a id="listing2"></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 opts[] =
23: 7 {
24: 8 CFG_STR("target", "World", CFGF_NONE),
25: 9 CFG_END()
26: 10 };
27: 11 cfg_t *cfg;
28: 12
29: 13 cfg = cfg_init(opts, CFGF_NONE);
30: 14 if(cfg_parse(cfg, "hello.conf") == CFG_PARSE_ERROR)
31: 15 return 1;
32: 16
33: 17 printf("Hello, %s!\n", cfg_getstr(cfg, "target"));
34: 18
35: 19 cfg_free(cfg);
36: 20 return 0;
37: 21 }
38: 22
39: </pre><p>
40: All programs using libConfuse must first include the
41: <code class="filename">confuse.h</code> header file. This is done on line
42: 2.
43: </p><p>
44: On line 6 - 10, the options that should be recognized are defined in an
45: array of cfg_opt_t structs. This is passed to the
46: <code class="function">cfg_init</code> function on line 13. The resulting
47: <span class="structname">cfg_t</span> context is used by
48: <code class="function">cfg_parse()</code>, which reads the configuration file
49: "hello.conf". When reading the configuration file, only options defined in
50: the array of options passed to <code class="function">cfg_init()</code> are
51: recognized.
52: </p><p>
53: The friendly greeting is now replaced with a parameter read from the
54: configuration file. The value of the <code class="varname">target</code> option is retrieved with
55: <code class="function">cfg_getstr(cfg, "target")</code>.
56: </p><p>
57: Lets take a look at the configuration file hello.conf:
58: </p><pre class="programlisting">
59: # this is the configuration file for the hello program
60:
61: target = "Neighbour"
62: </pre><p>
63: Here, the target option is set to the string value "Neighbour".
64: What if the configuration file was empty or didn't exist? Then the
65: default value for the <code class="varname">target</code> option would be
66: used. When we initialized our options, the second parameter to the
67: <code class="function">CFG_STR()</code> macro specified the default value.
68: Thus, if no <code class="varname">target</code> option was specified in the
69: configuration file, the hello program would have printed the
70: standard greeting "Hello, World".
71: </p><div class="sect2" title="1.1. Environment variables in values"><div class="titlepage"><div><div><h3 class="title"><a id="id401812"></a>1.1. Environment variables in values</h3></div></div></div><p>
72: What else can we do in the configuration file? We can set the value to an
73: environment variable:
74: </p><pre class="programlisting">
75: target = ${USER}
76: </pre><p>
77: This results in the hello program greeting the user who runs it. On some
78: systems, the USER variable might not be available, so we want to specify a
79: default value in those cases:
80: </p><pre class="programlisting">
81: target = ${USER:-User}
82: </pre><p>
83: Now, if the USER environment variable is unset, the string "User" will be
84: used instead.
85: </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