Annotation of embedaddon/confuse/doc/tutorial-html/index.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>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