third_party/inipp/repo/inipp/README.md

   1 # IniPP
   2
   3 Simple header-only C++ ini parser and generator.
   4
   5 [![Build Status](https://travis-ci.org/mcmtroffaes/inipp.svg?branch=develop)](https://travis-ci.org/mcmtroffaes/inipp) [![Build status](https://ci.appveyor.com/api/projects/status/74hf86c4yhtmb1j5/branch/develop?svg=true)](https://ci.appveyor.com/project/mcmtroffaes/inipp/branch/develop)
   6
   7 ## Features
   8
   9 * Header-only.
  10 * Both parsing and generating.
  11 * Wide character support for native unicode on Windows.
  12 * Default section support (similar to Python's ConfigParser).
  13 * Interpolation support (i.e. variable substitution, similar to Python's ConfigParser).
  14 * Simple design and implementation.
  15 * Permissive MIT license.
  16
  17 ## Example
  18
  19 ```cpp
  20 #include <fstream>
  21 #include "inipp.h"
  22
  23 int main() {
  24         inipp::Ini<char> ini;
  25         std::ifstream is("example.ini");
  26         ini.parse(is);
  27         std::cout << "raw ini file:" << std::endl;
  28         ini.generate(std::cout);
  29         ini.default_section(ini.sections["DEFAULT"]);
  30         ini.interpolate();
  31         std::cout << "ini file after default section and interpolation:" << std::endl;
  32         ini.generate(std::cout);
  33         int compression_level = -1;
  34         inipp::extract(ini.sections["bitbucket.org"]["CompressionLevel"], compression_level);
  35         std::cout << "bitbucket.org compression level: " << compression_level << std::endl;
  36         return 0;
  37 }
  38 ```
  39
  40 ## Parsing algorithm
  41
  42 * The *section* is set to the empty string.
  43
  44 * Every *line* is read from the file and trimmed from whitespace.
  45
  46     * If *line* is empty or starts with ``;`` then nothing happens.
  47
  48     * Otherwise, if *line* starts with ``[`` then *section* is changed
  49       to the string between ``[`` and ``]``. If *line* does not end
  50       with ``]`` then an error is reported.
  51
  52     * Otherwise, if *line* contains an ``=`` sign, then all characters
  53       before ``=`` are treated as *variable* and all characters
  54       following ``=`` are treated as *value*. Both are trimmed. If the
  55       variable was already assigned earlier, an error is
  56       reported. Otherwise, the corresponding assigment is added to the
  57       *section*.
  58
  59     * Otherwise, the *line* is reported as an error.
  60
  61 ## Default section algorithm
  62
  63 Insert every variable from the default section into every other section, without overwriting existing variables.
  64
  65 ## Interpolation algorithm
  66
  67 1. Locally within each section, every occurrence "${variable}" is replaced by "${section:variable}".
  68 2. Every occurrence of "${section:variable}" is replaced by its value.
  69 3. The previous step is repeated until no more replacements are possible, or until the recursion depth (by default, 10) is reached.
  70