1<html> 2<head> 3 <meta name="author" content="ndevilla@free.fr"> 4 <meta name="keywords" content="ini file, config file, parser, C library"> 5 <link href="doxygen.css" rel="stylesheet" type="text/css"> 6<title>iniparser 2.x</title> 7</head> 8 9<body text="#000000" bgcolor="#ffffff"> 10 11 12 13<!-- Generated by Doxygen 1.5.1 --> 14<h1>iniparser documentation</h1> 15<p> 16<h3 align="center">2.x </h3><hr> 17<h2><a class="anchor" name="welcome"> 18Introduction</a></h2> 19iniParser is a simple C library offering ini file parsing services. The library is pretty small (less than 1500 lines of C) and robust, and does not depend on any other external library to compile. It is written in ANSI C and should compile anywhere without difficulty.<p> 20<hr> 21<h2><a class="anchor" name="inidef"> 22What is an ini file?</a></h2> 23An ini file is an ASCII file describing simple parameters (character strings, integers, floating-point values or booleans) in an explicit format, easy to use and modify for users.<p> 24An ini file is segmented into Sections, declared by the following syntax:<p> 25<div class="fragment"><pre class="fragment"> 26 [Section Name] 27 </pre></div><p> 28i.e. the section name enclosed in square brackets, alone on a line. Sections names are allowed to contain any character but square brackets or linefeeds. Slashes (/) are also reserved for hierarchical sections (see below).<p> 29In any section are zero or more variables, declared with the following syntax:<p> 30<div class="fragment"><pre class="fragment"> 31 Key = value ; comment 32 </pre></div><p> 33The key is any string (possibly containing blanks). The value is any character on the right side of the equal sign. Values can be given enclosed with quotes. If no quotes are present, the value is understood as containing all characters between the first and the last non-blank characters. The following declarations are identical:<p> 34<div class="fragment"><pre class="fragment"> 35 Hello = "this is a long string value" ; comment 36 Hello = this is a long string value ; comment 37 </pre></div><p> 38The semicolon and comment at the end of the line are optional. If there is a comment, it starts from the first character after the semicolon up to the end of the line.<p> 39Comments in an ini file are:<p> 40<ul> 41<li>Lines starting with a hash sign</li><li>Blank lines (only blanks or tabs)</li><li>Comments given on value lines after the semicolon (if present)</li></ul> 42<p> 43<hr> 44<h2><a class="anchor" name="install"> 45Compiling/installing the library</a></h2> 46Edit the Makefile to indicate the C compiler you want to use, the options to provide to compile ANSI C, and possibly the options to pass to the <code>ar</code> program on your machine to build a library (.a) from a set of object (.o) files.<p> 47Defaults are set for the gcc compiler and the standard ar library builder.<p> 48Type 'make', that should do it.<p> 49To use the library in your programs, add the following line on top of your module:<p> 50<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include "<a class="code" href="iniparser_8h.html">iniparser.h</a>"</span> 51</pre></div><p> 52And link your program with the iniparser library by adding <code>-liniparser.a</code> to the compile line.<p> 53See the file test/initest.c for an example.<p> 54<hr> 55<h2><a class="anchor" name="reference"> 56Library reference</a></h2> 57The library is completely documented in its header file. On-line documentation has been generated and can be consulted here:<p> 58<ul> 59<li><a class="el" href="iniparser_8h.html">iniparser.h</a></li></ul> 60<p> 61<hr> 62<h2><a class="anchor" name="usage"> 63Using the parser</a></h2> 64Comments are discarded by the parser. Then sections are identified, and in each section a new entry is created for every keyword found. The keywords are stored with the following syntax:<p> 65<div class="fragment"><pre class="fragment"> 66 [Section] 67 Keyword = value ; comment 68 </pre></div><p> 69is converted to the following key pair:<p> 70<div class="fragment"><pre class="fragment"> 71 ("section:keyword", "value") 72 </pre></div><p> 73This means that if you want to retrieve the value that was stored in the section called <code>Pizza</code>, in the keyword <code>Cheese</code>, you would make a request to the dictionary for <code>"pizza:cheese"</code>. All section and keyword names are converted to lowercase before storage in the structure. The value side is conserved as it has been parsed, though.<p> 74Section names are also stored in the structure. They are stored using as key the section name, and a NULL associated value. They can be queried through <a class="el" href="iniparser_8h.html#3d67c98bbc0cb5239f024ad54bdc63f1">iniparser_find_entry()</a>.<p> 75To launch the parser, simply use the function called <a class="el" href="iniparser_8h.html#b0be559bfb769224b3f1b75e26242a67">iniparser_load()</a>, which takes an input file name and returns a newly allocated <em>dictionary</em> structure. This latter object should remain opaque to the user and only accessed through the following accessor functions:<p> 76<ul> 77<li><a class="el" href="iniparser_8h.html#587eafb48937fdee8ae414ad7a666db8">iniparser_getstr()</a></li><li><a class="el" href="iniparser_8h.html#694eb1110f4200db8648820a0bb405fa">iniparser_getint()</a></li><li><a class="el" href="iniparser_8h.html#480d35322f1252344cf2246ac21ee559">iniparser_getdouble()</a></li><li><a class="el" href="iniparser_8h.html#eb93c13fcbb75efaa396f53bfd73ff4d">iniparser_getboolean()</a></li></ul> 78<p> 79Finally, discard this structure using <a class="el" href="iniparser_8h.html#90549ee518523921886b74454ff872eb">iniparser_freedict()</a>.<p> 80All values parsed from the ini file are stored as strings. The getint, getdouble and getboolean accessors are just converting these strings to the requested type on the fly, but you could basically perform this conversion by yourself after having called the getstr accessor.<p> 81Notice that the <a class="el" href="iniparser_8h.html#eb93c13fcbb75efaa396f53bfd73ff4d">iniparser_getboolean()</a> function will return an integer (0 or 1), trying to make sense of what was found in the file. Strings starting with "y", "Y", "t", "T" or "1" are considered true values (return 1), strings starting with "n", "N", "f", "F", "0" are considered false (return 0). This allows flexible handling of boolean answers.<p> 82If you want to add extra information into the structure that was not present in the ini file, you can use <a class="el" href="iniparser_8h.html#605a88057bac4c3249513fc588421c32">iniparser_setstr()</a> to insert a string.<p> 83<hr> 84<h2><a class="anchor" name="implementation"> 85A word about the implementation</a></h2> 86The dictionary structure is a pretty simple dictionary implementation which might find some uses in other applications. If you are curious, look into the source.<p> 87<hr> 88<h2><a class="anchor" name="hierarchical"> 89Hierarchical ini files</a></h2> 90ini files are nice to present informations to the user in a readable format, but lack a very useful feature: the possibility of organizing data in a hierarchical (tree-like) fashion. The following convention can be used to make ini files obtain this second dimension:<p> 91A section depends on another section if it contains its name as a prefix, separated by slashes (/). For example: we have 2 main sections in the ini file. The first one is called <code>Pizza</code> and has two child subsections called <code>Cheese</code> and <code>Ham</code>. The second main section in the ini file is called <code>Wine</code> and has two child subsections called <code>Year</code> and <code>Grape</code>. As a tree, this could appear as:<p> 92<div class="fragment"><pre class="fragment"> 93 | 94 +-- Pizza 95 | +-- Cheese 96 | +-- Ham 97 +-- Wine 98 +--- Year 99 +--- Grape 100 </pre></div><p> 101In an ini file, that would be converted to:<p> 102<div class="fragment"><pre class="fragment"> 103 [Pizza] 104 105 [Pizza/Cheese] 106 Name = Gorgonzola ; 107 Origin = Italy ; 108 109 [Pizza/Ham] 110 Name = Parma ; 111 Origin = Italy ; 112 113 [Wine] 114 115 [Wine/Year] 116 Value = 1998 ; 117 118 [Wine/Grape] 119 Name = Cabernet Sauvignon ; 120 Origin = Chile ; 121 </pre></div><p> 122This proposal is actually more related to the way people write ini files, more than the parser presented here. But it is certainly a useful way of making tree-like data declarations without going through painful formats like XML.<p> 123Accessing the above tree would give something like (error checking removed for clarity sake):<p> 124<div class="fragment"><pre class="fragment"> dictionary * d ; 125 126 d = <a class="code" href="iniparser_8h.html#b0be559bfb769224b3f1b75e26242a67">iniparser_load</a>(<span class="stringliteral">"example.ini"</span>); 127 128 printf(<span class="stringliteral">"cheese name is %s\n"</span>, <a class="code" href="iniparser_8h.html#587eafb48937fdee8ae414ad7a666db8">iniparser_getstr</a>(d, <span class="stringliteral">"pizza/cheese:name"</span>)); 129 printf(<span class="stringliteral">"grape name is %s\n"</span>, <a class="code" href="iniparser_8h.html#587eafb48937fdee8ae414ad7a666db8">iniparser_getstr</a>(d, <span class="stringliteral">"wine/grape:name"</span>)); 130 131 <a class="code" href="iniparser_8h.html#90549ee518523921886b74454ff872eb">iniparser_freedict</a>(d); 132</pre></div><p> 133The whole ini file above is represented in the dictionary as the following list of pairs:<p> 134<div class="fragment"><pre class="fragment"> 135 key value 136 137 "pizza" NULL 138 "pizza/cheese" NULL 139 "pizza/cheese:name" "Gorgonzola" 140 "pizza/cheese:origin" "Italy" 141 "pizza/ham" NULL 142 "pizza/ham:name" "Parma" 143 "pizza/ham:origin" "Italy" 144 "wine" NULL 145 "wine/year" NULL 146 "wine/year:value" "1998" 147 "wine/grape" NULL 148 "wine/grape:name" "Cabernet Sauvignon" 149 "wine/grape:origin" "Chile" 150 </pre></div><p> 151<hr> 152<h2><a class="anchor" name="authors"> 153Authors</a></h2> 154Nicolas Devillard (ndevilla AT free DOT fr). 155</body> 156</html> 157