c_cpp/lib/inih/README.md

   1 **inih (INI Not Invented Here)** is a simple [.INI file](http://en.wikipedia.org/wiki/INI_file) parser written in C. It's only a couple of pages of code, and it was designed to be _small and simple_, so it's good for embedded systems. It's also more or less compatible with Python's [ConfigParser](http://docs.python.org/library/configparser.html) style of .INI files, including RFC 822-style multi-line syntax and `name: value` entries.
   2
   3 To use it, just give `ini_parse()` an INI file, and it will call a callback for every `name=value` pair parsed, giving you strings for the section, name, and value. It's done this way ("SAX style") because it works well on low-memory embedded systems, but also because it makes for a KISS implementation.
   4
   5 You can also call `ini_parse_file()` to parse directly from a `FILE*` object, or `ini_parse_stream()` to parse using a custom reader to implement string-based or other custom I/O ([see example code](https://github.com/benhoyt/inih/blob/master/examples/ini_buffer.c)).
   6
   7 Download a release, browse the source, or read about [how to use inih in a DRY style](http://blog.brush.co.nz/2009/08/xmacros/) with X-Macros.
   8
   9
  10 ## Compile-time options ##
  11
  12   * **Multi-line entries:** By default, inih supports multi-line entries in the style of Python's ConfigParser. To disable, add `-DINI_ALLOW_MULTILINE=0`.
  13   * **UTF-8 BOM:** By default, inih allows a UTF-8 BOM sequence (0xEF 0xBB 0xBF) at the start of INI files. To disable, add `-DINI_ALLOW_BOM=0`.
  14   * **Inline comments:** By default, inih allows inline comments with the `;` character. To disable, add `-DINI_ALLOW_INLINE_COMMENTS=0`. You can also specify which character(s) start an inline comment using `INI_INLINE_COMMENT_PREFIXES`.
  15   * **Stack vs heap:** By default, inih allocates its line buffer on the stack. To allocate on the heap using `malloc` instead, specify `-DINI_USE_STACK=0`.
  16   * **Stop on first error:** By default, inih keeps parsing the rest of the file after an error. To stop parsing on the first error, add `-DINI_STOP_ON_FIRST_ERROR=1`.
  17   * **Maximum line length:** The default maximum line length is 200 bytes. To override this, add something like `-DINI_MAX_LINE=1000`.
  18   * **Report line numbers:** By default, the `ini_handler` callback doesn't receive the line number as a parameter. If you need that, add `-DINI_HANDLER_LINENO=1`.
  19
  20
  21 ## Simple example in C ##
  22
  23 ```c
  24 #include <stdio.h>
  25 #include <stdlib.h>
  26 #include <string.h>
  27 #include "../ini.h"
  28
  29 typedef struct
  30 {
  31     int version;
  32     const char* name;
  33     const char* email;
  34 } configuration;
  35
  36 static int handler(void* user, const char* section, const char* name,
  37                    const char* value)
  38 {
  39     configuration* pconfig = (configuration*)user;
  40
  41     #define MATCH(s, n) strcmp(section, s) == 0 && strcmp(name, n) == 0
  42     if (MATCH("protocol", "version")) {
  43         pconfig->version = atoi(value);
  44     } else if (MATCH("user", "name")) {
  45         pconfig->name = strdup(value);
  46     } else if (MATCH("user", "email")) {
  47         pconfig->email = strdup(value);
  48     } else {
  49         return 0;  /* unknown section/name, error */
  50     }
  51     return 1;
  52 }
  53
  54 int main(int argc, char* argv[])
  55 {
  56     configuration config;
  57
  58     if (ini_parse("test.ini", handler, &config) < 0) {
  59         printf("Can't load 'test.ini'\n");
  60         return 1;
  61     }
  62     printf("Config loaded from 'test.ini': version=%d, name=%s, email=%s\n",
  63         config.version, config.name, config.email);
  64     return 0;
  65 }
  66 ```
  67
  68
  69 ## C++ example ##
  70
  71 If you're into C++ and the STL, there is also an easy-to-use [INIReader class](https://github.com/benhoyt/inih/blob/master/cpp/INIReader.h) that stores values in a `map` and lets you `Get()` them:
  72
  73 ```cpp
  74 #include <iostream>
  75 #include "INIReader.h"
  76
  77 int main()
  78 {
  79     INIReader reader("../examples/test.ini");
  80
  81     if (reader.ParseError() < 0) {
  82         std::cout << "Can't load 'test.ini'\n";
  83         return 1;
  84     }
  85     std::cout << "Config loaded from 'test.ini': version="
  86               << reader.GetInteger("protocol", "version", -1) << ", name="
  87               << reader.Get("user", "name", "UNKNOWN") << ", email="
  88               << reader.Get("user", "email", "UNKNOWN") << ", pi="
  89               << reader.GetReal("user", "pi", -1) << ", active="
  90               << reader.GetBoolean("user", "active", true) << "\n";
  91     return 0;
  92 }
  93 ```
  94
  95 This simple C++ API works fine, but it's not very fully-fledged. I'm not planning to work more on the C++ API at the moment, so if you want a bit more power (for example `GetSections()` and `GetFields()` functions), see these forks:
  96
  97   * https://github.com/Blandinium/inih
  98   * https://github.com/OSSystems/inih
  99
 100
 101 ## Differences from ConfigParser ##
 102
 103 Some differences between inih and Python's [ConfigParser](http://docs.python.org/library/configparser.html) standard library module:
 104
 105 * INI name=value pairs given above any section headers are treated as valid items with no section (section name is an empty string). In ConfigParser having no section is an error.
 106 * Line continuations are handled with leading whitespace on continued lines (like ConfigParser). However, instead of concatenating continued lines together, they are treated as separate values for the same key (unlike ConfigParser).