README.md
1simpleini
2=========
3
4[](https://travis-ci.org/brofield/simpleini)
5
6A cross-platform library that provides a simple API to read and write INI-style configuration files. It supports data files in ASCII, MBCS and Unicode. It is designed explicitly to be portable to any platform and has been tested on Windows, WinCE and Linux. Released as open-source and free using the MIT licence.
7
8# Feature Summary
9
10- MIT Licence allows free use in all software (including GPL and commercial)
11- multi-platform (Windows 95/98/ME/NT/2K/XP/2003, Windows CE, Linux, Unix)
12- loading and saving of INI-style configuration files
13- configuration files can have any newline format on all platforms
14- liberal acceptance of file format
15 * key/values with no section
16 * removal of whitespace around sections, keys and values
17- support for multi-line values (values with embedded newline characters)
18- optional support for multiple keys with the same name
19- optional case-insensitive sections and keys (for ASCII characters only)
20- saves files with sections and keys in the same order as they were loaded
21- preserves comments on the file, section and keys where possible.
22- supports both char or wchar_t programming interfaces
23- supports both MBCS (system locale) and UTF-8 file encodings
24- system locale does not need to be UTF-8 on Linux/Unix to load UTF-8 file
25- support for non-ASCII characters in section, keys, values and comments
26- support for non-standard character types or file encodings via user-written converter classes
27- support for adding/modifying values programmatically
28- compiles cleanly in the following compilers:
29 * Windows/VC6 (warning level 3)
30 * Windows/VC.NET 2003 (warning level 4)
31 * Windows/VC 2005 (warning level 4)
32 * Linux/gcc (-Wall)
33 * Windows/MinGW GCC
34
35# Documentation
36
37Full documentation of the interface is available in doxygen format.
38
39# Examples
40
41These snippets are included with the distribution in the file snippets.cpp.
42
43### SIMPLE USAGE
44
45```c++
46CSimpleIniA ini;
47ini.SetUnicode();
48ini.LoadFile("myfile.ini");
49const char * pVal = ini.GetValue("section", "key", "default");
50ini.SetValue("section", "key", "newvalue");
51```
52
53### LOADING DATA
54
55```c++
56// load from a data file
57CSimpleIniA ini(a_bIsUtf8, a_bUseMultiKey, a_bUseMultiLine);
58SI_Error rc = ini.LoadFile(a_pszFile);
59if (rc < 0) return false;
60
61// load from a string
62std::string strData;
63rc = ini.LoadData(strData.c_str(), strData.size());
64if (rc < 0) return false;
65```
66
67### GETTING SECTIONS AND KEYS
68
69```c++
70// get all sections
71CSimpleIniA::TNamesDepend sections;
72ini.GetAllSections(sections);
73
74// get all keys in a section
75CSimpleIniA::TNamesDepend keys;
76ini.GetAllKeys("section-name", keys);
77```
78
79### GETTING VALUES
80
81```c++
82// get the value of a key
83const char * pszValue = ini.GetValue("section-name",
84 "key-name", NULL /*default*/);
85
86// get the value of a key which may have multiple
87// values. If bHasMultipleValues is true, then just
88// one value has been returned
89bool bHasMultipleValues;
90pszValue = ini.GetValue("section-name", "key-name",
91 NULL /*default*/, &bHasMultipleValues);
92
93// get all values of a key with multiple values
94CSimpleIniA::TNamesDepend values;
95ini.GetAllValues("section-name", "key-name", values);
96
97// sort the values into the original load order
98values.sort(CSimpleIniA::Entry::LoadOrder());
99
100// output all of the items
101CSimpleIniA::TNamesDepend::const_iterator i;
102for (i = values.begin(); i != values.end(); ++i) {
103 printf("key-name = '%s'\n", i->pItem);
104}
105```
106
107### MODIFYING DATA
108
109```c++
110// adding a new section
111rc = ini.SetValue("new-section", NULL, NULL);
112if (rc < 0) return false;
113printf("section: %s\n", rc == SI_INSERTED ?
114 "inserted" : "updated");
115
116// adding a new key ("new-section" will be added
117// automatically if it doesn't already exist)
118rc = ini.SetValue("new-section", "new-key", "value");
119if (rc < 0) return false;
120printf("key: %s\n", rc == SI_INSERTED ?
121 "inserted" : "updated");
122
123// changing the value of a key
124rc = ini.SetValue("section", "key", "updated-value");
125if (rc < 0) return false;
126printf("key: %s\n", rc == SI_INSERTED ?
127 "inserted" : "updated");
128```
129
130### DELETING DATA
131
132```c++
133// deleting a key from a section. Optionally the entire
134// section may be deleted if it is now empty.
135ini.Delete("section-name", "key-name",
136 true /*delete the section if empty*/);
137
138// deleting an entire section and all keys in it
139ini.Delete("section-name", NULL);
140```
141
142### SAVING DATA
143
144```c++
145// save the data to a string
146rc = ini.Save(strData);
147if (rc < 0) return false;
148
149// save the data back to the file
150rc = ini.SaveFile(a_pszFile);
151if (rc < 0) return false;
152```
153
){kind=link}