Return to index.html CVS log | Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / confuse / doc / tutorial-html |
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>