From e5e33247ff9abe01a87bd7b8ebd050c549e2814f Mon Sep 17 00:00:00 2001 From: Lars Müller Date: Sun, 27 May 2007 15:58:19 +0000 Subject: r23166: Bring samba.org's iniparser copy in sync with the upstream version 2.17. (This used to be commit 3fa98245d98436a0f042ffca9bf102e9f920bace) --- source3/iniparser/html/index.html | 50 +++++++++++++++++++++++---------------- 1 file changed, 29 insertions(+), 21 deletions(-) (limited to 'source3/iniparser/html/index.html') diff --git a/source3/iniparser/html/index.html b/source3/iniparser/html/index.html index e0ca48b872..a09575587d 100644 --- a/source3/iniparser/html/index.html +++ b/source3/iniparser/html/index.html @@ -10,8 +10,8 @@ - -

iniparser documentation

+ +

iniparser documentation

2.x

@@ -22,14 +22,17 @@ iniParser is a simple C library offering ini file parsing services. The library What is an ini file?

An 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.

An ini file is segmented into Sections, declared by the following syntax:

-

    [Section Name]
+
+    [Section Name]
 	

 i.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).

 In any section are zero or more variables, declared with the following syntax:

-
    Key = value ; comment
+
+    Key = value ; comment
 	

 The 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:

-
    Hello = "this is a long string value" ; comment
+
+    Hello = "this is a long string value" ; comment
     Hello = this is a long string value ; comment
 	

 The 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.

@@ -46,7 +49,7 @@ Type 'make', that should do it.

 To use the library in your programs, add the following line on top of your module:

 
    #include "iniparser.h"
 

-And link your program with the iniparser library by adding -liniparser.a to the compile line.

+And link your program with the iniparser library by adding -liniparser.a to the compile line.

 See the file test/initest.c for an example.

 

 

@@ -59,22 +62,24 @@ The library is completely documented in its header file. On-line documentation h
 

 Using the parser

 Comments 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:

-
    [Section]
+
+    [Section]
     Keyword = value ; comment
 	

 is converted to the following key pair:

-
    ("section:keyword", "value")
+
+    ("section:keyword", "value")
 	

 This means that if you want to retrieve the value that was stored in the section called Pizza, in the keyword Cheese, you would make a request to the dictionary for "pizza:cheese". 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.

-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 iniparser_find_entry().

-To launch the parser, simply use the function called iniparser_load(), which takes an input file name and returns a newly allocated dictionary structure. This latter object should remain opaque to the user and only accessed through the following accessor functions:

+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 iniparser_find_entry().

+To launch the parser, simply use the function called iniparser_load(), which takes an input file name and returns a newly allocated dictionary structure. This latter object should remain opaque to the user and only accessed through the following accessor functions:

 

+
  • iniparser_getstr()
  • iniparser_getint()
  • iniparser_getdouble()
  • iniparser_getboolean()
    • 
 
    
-Finally, discard this structure using iniparser_freedict().
    
+Finally, discard this structure using iniparser_freedict().
    
 All 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.
    
-Notice that the iniparser_getboolean() 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.
    
-If you want to add extra information into the structure that was not present in the ini file, you can use iniparser_setstr() to insert a string.
    
+Notice that the iniparser_getboolean() 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.
    
+If you want to add extra information into the structure that was not present in the ini file, you can use iniparser_setstr() to insert a string.
    
 
    
 
    
 A word about the implementation
    
@@ -84,7 +89,8 @@ The dictionary structure is a pretty simple dictionary implementation which migh
 Hierarchical ini files
    
 ini 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:
    
 A 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 Pizza and has two child subsections called Cheese and Ham. The second main section in the ini file is called Wine and has two child subsections called Year and Grape. As a tree, this could appear as:
    
-
        |
+
    +    |
     +-- Pizza
     |     +-- Cheese
     |     +-- Ham
@@ -93,7 +99,8 @@ A section depends on another section if it contains its name as a prefix, separa
          +--- Grape
 	
    
 In an ini file, that would be converted to:
    
-
        [Pizza]
+
    +    [Pizza]
 
     [Pizza/Cheese]
     Name   = Gorgonzola ;
@@ -116,15 +123,16 @@ This proposal is actually more related to the way people write ini files, more t
 Accessing the above tree would give something like (error checking removed for clarity sake):
    
 
        dictionary * d ;
 
-    d = iniparser_load("example.ini");
+    d = iniparser_load("example.ini");
 
-    printf("cheese name is %s\n", iniparser_getstr(d, "pizza/cheese:name"));
-    printf("grape name is %s\n",  iniparser_getstr(d, "wine/grape:name"));
+    printf("cheese name is %s\n", iniparser_getstr(d, "pizza/cheese:name"));
+    printf("grape name is %s\n",  iniparser_getstr(d, "wine/grape:name"));
 
-    iniparser_freedict(d);
+    iniparser_freedict(d);
 
    
 The whole ini file above is represented in the dictionary as the following list of pairs:
    
-
        key                             value
+
    +    key                             value
 
     "pizza"                         NULL
     "pizza/cheese"                  NULL
-- 
cgit