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"> 41 #include <stdio.h> 52 63 int main(void) 74 { 85 printf("Hello, World!\n"); 96 return 0; 107 } 118 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"> 171 #include <stdio.h> 182 #include <confuse.h> 193 204 int main(void) 215 { 226 cfg_opt_t opts[] = 237 { 248 CFG_STR("target", "World", CFGF_NONE), 259 CFG_END() 2610 }; 2711 cfg_t *cfg; 2812 2913 cfg = cfg_init(opts, CFGF_NONE); 3014 if(cfg_parse(cfg, "hello.conf") == CFG_PARSE_ERROR) 3115 return 1; 3216 3317 printf("Hello, %s!\n", cfg_getstr(cfg, "target")); 3418 3519 cfg_free(cfg); 3620 return 0; 3721 } 3822 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 61target = "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"> 75target = ${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"> 81target = ${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> 86