Ignore:
Timestamp:
Sep 30, 2007, 3:42:50 AM (18 years ago)
Author:
Paul Smedley
Message:

Update trunk to 3.2.0pre1

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/samba/source/iniparser/html/index.html

    r1 r77  
    1111
    1212
    13 <!-- Generated by Doxygen 1.4.4 -->
    14 <h1>iniparser documentation </h1>
     13<!-- Generated by Doxygen 1.5.1 -->
     14<h1>iniparser documentation</h1>
    1515<p>
    1616<h3 align="center">2.x </h3><hr>
     
    2323An 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>
    2424An ini file is segmented into Sections, declared by the following syntax:<p>
    25 <div class="fragment"><pre class="fragment">    [Section Name]
     25<div class="fragment"><pre class="fragment">
     26    [Section Name]
    2627        </pre></div><p>
    2728i.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>
    2829In any section are zero or more variables, declared with the following syntax:<p>
    29 <div class="fragment"><pre class="fragment">    Key = value ; comment
     30<div class="fragment"><pre class="fragment">
     31    Key = value ; comment
    3032        </pre></div><p>
    3133The 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>
    32 <div class="fragment"><pre class="fragment">    Hello = "this is a long string value" ; comment
     34<div class="fragment"><pre class="fragment">
     35    Hello = "this is a long string value" ; comment
    3336    Hello = this is a long string value ; comment
    3437        </pre></div><p>
     
    4750<div class="fragment"><pre class="fragment"><span class="preprocessor">    #include "<a class="code" href="iniparser_8h.html">iniparser.h</a>"</span>
    4851</pre></div><p>
    49 And link your program with the iniparser library by adding <code>-liniparser</code>.a to the compile line.<p>
     52And link your program with the iniparser library by adding <code>-liniparser.a</code> to the compile line.<p>
    5053See the file test/initest.c for an example.<p>
    5154<hr>
     
    6063Using the parser</a></h2>
    6164Comments 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>
    62 <div class="fragment"><pre class="fragment">    [Section]
     65<div class="fragment"><pre class="fragment">
     66    [Section]
    6367    Keyword = value ; comment
    6468        </pre></div><p>
    6569is converted to the following key pair:<p>
    66 <div class="fragment"><pre class="fragment">    ("section:keyword", "value")
     70<div class="fragment"><pre class="fragment">
     71    ("section:keyword", "value")
    6772        </pre></div><p>
    6873This 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>
    69 Section 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#a11">iniparser_find_entry()</a>.<p>
    70 To launch the parser, simply use the function called <a class="el" href="iniparser_8h.html#a12">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>
     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>
    7176<ul>
    72 <li><a class="el" href="iniparser_8h.html#a4">iniparser_getstr()</a></li><li><a class="el" href="iniparser_8h.html#a6">iniparser_getint()</a></li><li><a class="el" href="iniparser_8h.html#a7">iniparser_getdouble()</a></li><li><a class="el" href="iniparser_8h.html#a8">iniparser_getboolean()</a></li></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>
    7378<p>
    74 Finally, discard this structure using <a class="el" href="iniparser_8h.html#a13">iniparser_freedict()</a>.<p>
     79Finally, discard this structure using <a class="el" href="iniparser_8h.html#90549ee518523921886b74454ff872eb">iniparser_freedict()</a>.<p>
    7580All 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>
    76 Notice that the <a class="el" href="iniparser_8h.html#a8">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>
    77 If 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#a9">iniparser_setstr()</a> to insert a string.<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>
    7883<hr>
    7984<h2><a class="anchor" name="implementation">
     
    8590ini 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>
    8691A 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>
    87 <div class="fragment"><pre class="fragment">    |
     92<div class="fragment"><pre class="fragment">
     93    |
    8894    +-- Pizza
    8995    |     +-- Cheese
     
    94100        </pre></div><p>
    95101In an ini file, that would be converted to:<p>
    96 <div class="fragment"><pre class="fragment">    [Pizza]
     102<div class="fragment"><pre class="fragment">
     103    [Pizza]
    97104
    98105    [Pizza/Cheese]
     
    117124<div class="fragment"><pre class="fragment">    dictionary * d ;
    118125
    119     d = <a class="code" href="iniparser_8h.html#a12">iniparser_load</a>(<span class="stringliteral">"example.ini"</span>);
     126    d = <a class="code" href="iniparser_8h.html#b0be559bfb769224b3f1b75e26242a67">iniparser_load</a>(<span class="stringliteral">"example.ini"</span>);
    120127
    121     printf(<span class="stringliteral">"cheese name is %s\n"</span>, <a class="code" href="iniparser_8h.html#a4">iniparser_getstr</a>(d, <span class="stringliteral">"pizza/cheese:name"</span>));
    122     printf(<span class="stringliteral">"grape name is %s\n"</span>,  <a class="code" href="iniparser_8h.html#a4">iniparser_getstr</a>(d, <span class="stringliteral">"wine/grape:name"</span>));
     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>));
    123130
    124     <a class="code" href="iniparser_8h.html#a13">iniparser_freedict</a>(d);
     131    <a class="code" href="iniparser_8h.html#90549ee518523921886b74454ff872eb">iniparser_freedict</a>(d);
    125132</pre></div><p>
    126133The whole ini file above is represented in the dictionary as the following list of pairs:<p>
    127 <div class="fragment"><pre class="fragment">    key                             value
     134<div class="fragment"><pre class="fragment">
     135    key                             value
    128136
    129137    "pizza"                         NULL
Note: See TracChangeset for help on using the changeset viewer.