Cracking an INI file with a jackhammer
All I was after was a simple .INI file reader in C or C++. You know, to parse [section] and name=value lines for config files. We needed it for an embedded Linux project, so it had to be small, portable and only dependent on the C and C++ standard libraries.
Maybe it’s my embedded background that makes me defensive about my mild case of Not-Invented-Here syndrome. Then again, perhaps I’m in good company.
But surely there are tons of INI parsing libraries around, right? Well, kind of.
I found no fewer than 15 in under an hour. But why is it that things like this are either way off the mark (bloated or non-portable) or they’re very close, but just not quite what you want?
Below is the list of INI file readers that I found, from bad to better. Some of the ones that weren’t for me might well suit your application, so treat this as something of a non-exhaustive list of INI file readers:
Not for me
- SDL_Config: Rather bloated … somehow 246KB of source code just to read an INI file doesn’t do it for me. I also admit to being a bit icked out by five levels of pointer indirection, for example:
file->internal_file-> global_group.multi_value_iterator = ... - ini.c by Carey Bloodworth: Small and in C, but has a funny API and is ripe with buffer overrun goodness.
- GetPrivateProfileString API: Fine API, but of course Win32 only.
- CIniReader by Xiangxiong Jian: C++ class, nice and simple, but Win32 only (uses
GetPrivateProfileString). - CIniFile by Ludvik Jerabek: C++ class, but uses loads of non-portable MFC helper classes. Update: Ludvik’s now added a portable version to this page.
Half way there
- SimpleIni by Brodie Thiesfield: C++, cross platform, and not really bad, but it just shows that “simple” is in the eye of the beholder. Does one really want 110KB of heavy duty, template-driven C++ code just to read an INI file?
- Config by freejack: Tantalising … a C++ class with a nice API, only 5KB of code (as it should be), and optional environment variable expansion. The problem? What it parses are not quite INI files, but his own special “structured config files”. Which is all very nice, but not exactly INI-compatible. (Admittedly this could easily be hacked into an INI reader.)
- Boost.Program_options: C++, and not bad code, but it’s more of a fully-fledged “program configuration library” than just an INI file reader. Plus, we weren’t yet sure we wanted a dependency on Boost.
- CIniFile by Silviu Simen: C++ class, a little better, but relies on the Boost.Spirit parsing library.
- M’s INI parser: C++, not bad, small, portable and uses the STL, but relies on the re2c scanner generator, giving it another dependency and making the code harder to read (and modify).
So very close
- minIni by CompuPhase: So very close, does just what you want (also writes INI files), and in only 17KB of portable C source, great for embedded systems … but re-reading the INI file for every
name=valuepair you need somehow just doesn’t sit right. - CDataFile by Gary McNickle: This one looks decent — small, C++, uses the STL instead of MFC or its own fancy dictionary type … I probably would have used this had I seen it sooner.
- libinifile by Anders Lövgren: This one’s quite good too. Minimal, portable, low memory footprint, but a slightly unusual API (partly to give it the low memory footprint). I might well have used this one too, had I found it sooner.
- libini by Simon White: Plain C, SWIGgable, fairly small, though has a bit of an odd API (and I’m struggling to see why a simple INI file reader needs a 665KB configuration script :-).
- iniParser by Nicolas Devillard: This is the one we ended up using. Small (about 32KB of source) and fast. The only minor drawback is that it implements its own dictionary type in C, and we’re using the STL which already has one. (Still, in C, what else can you do?) Also, it looks like it’s been around forever and is well tested.
INI Not Invented Here (INIH)
Of course, in the time it took to investigate all these, I could have easily written my own. And, being unable to help myself, I did. :-) So I present you with my own offering: INI Not Invented Here, a.k.a. INIH or simply ini.h.
It contains a small C function, ini_parse(), that parses an INI file and executes the given callback function for each name=value pair parsed (think SAX).
The reason I used the callback style is so you don’t have to load the whole file into memory if you don’t need to — good for embedded systems. Plus, I wanted to be able to use the parser easily in C, but not implement a dictionary-like structure in C.
For a more user-friendly, lookup style API if you’re using C++, I’ve wrapped ini_parse() in a class called INIReader, which has Get() and GetInteger() methods (all I needed). And it’s easy to sub-class INIReader if you need fancier GetXYZ() functions.
Show us the code
UPDATE: I’ve moved the code from here to its own Google Code project at http://code.google.com/p/inih/ — enjoy!
26 February 2009 by Ben 44 comments
44 comments and pings (oldest first)
However useless the above comment is, he does have a point. You see, you were complaining on how difficult it is to find the right library for your program out of so many available on the internet and then you go ahead and make another one yourself. It is very likely that someone else who stumbles upon your code will have the same sentiment as you did with the others…
Seems quite simple, straighforward and portable. Bravo!
I my own little utils library I have support for this. Using it looks like this:
IniFile config("config.ini");
config.section("user");
String email = config["email"];
or with section/variable :
IniFile config("config.ini");
String username = config["user/name"];
or all in one line, without creating a config object:
int protocol = IniFile("config.ini")["protocol/version"];
I used crack INI files with jackhammer back when I was a homeless rodeo clown but not any more. Now I am a world class magician !
Hi Alvaro, that’s quite neat — great use of operator overloading. Out of interest, I don’t suppose you could post the code somewhere?
Danijel, you’re right about someone else not finding my code good for their purposes. I guess that’s part of the attraction of NIH — you get exactly what you want, no more, no less.
[…] I’m on the lookout for small libraries anyway, I thought I’d also post a list of a few regular expression libraries I’ve found […]
[…] The Brush Blog :: Cracking an INI file with a jackhammer (tags: cpp) […]
For reference, here’s a simple C-based example for using ini_parse() to parse your program’s config file:
/* Simple INIH example */
#include "ini.h"
#include <string.h>
typedef struct {
char* name;
int age;
} config;
int config_handler(void* user, const char* section,
const char* name, const char* value)
{
config* cfg = (config*)user;
if (stricmp(section, "user") == 0) {
if (stricmp(name, "name") == 0)
cfg->name = strdup(value);
else if (stricmp(name, "age") == 0)
cfg->age = atoi(value);
}
}
void run_program(config* cfg)
{
printf("%s is %d years old\n", cfg->name, cfg->age);
}
void main()
{
config cfg = {"Anon Y Mous", 42}; /* Default config */
ini_parse("config.ini", config_handler, &cfg);
run_program(&cfg);
}
C++ class, but uses loads of non-portable MFC helper classes. It’s funny you mention it’s non portable which is 100% correct. I wrote one which was in standard C++ and STL if there is still interest in this let me know.
I was looking for exactly this. If not you I would have written it. Extremely lightweight yet economic. Will use thx!
Here is the text for that Ansi C++ code [snipped]. I will also update the code project page to have this available.
Updated project is located at:
To be honest, I’d rather re-invent the wheel as well (only way to know where your code’s been and who touched it :P ) but since I don’t have enough experience yet – thank you for writing code that even I can follow and use :)
Thank you. Thank you. Thank you.
I too had the experience of wading through the swamp of INI-parsers out there. Then I found yours, and it was good (:
One thing that is handy and absolutely trivial to add is a callback for when the section changes.
Dear Sir, I found your ini file parser very useful. When i work with known section names it’s perfect. How can i get all section names in array, and corresponding values in another array? Best Regards. Evgeny.
Hi Jenya, there’s no way of doing this with what’s built into inih. However, what you’d do is make a data structure, something like an array of arrays, and have your handler() function store the section name and section values into this array.
Something like the below (without fleshing out the data structure functions):
static int handler(void* user, const char* section, const char* name,
const char* value)
{
if (!has_section(section)) {
add_section(section);
}
add_value(section, name, value);
}
I had a senior developer come down on me because I was calling minini from a heavily used function. I should’ve checked the minini code but who would have thought. Learned that lesson really quick.
prob with the callback function approach is it requires a global variable if you want to ‘remember’ if you’re in the same section (or possibly a static variable) – both of which are a bit of a pain
A global is one way of doing it, but you could also use a “state struct” local to the function you’re calling ini_parse() from, and pass the address of that struct in as the “user” parameter. Actually, come to think of it, that’s what the main C example does on the inih project page.
But instead of just configuration the struct could contain any extra parsing state you need, like what section/name you processed last. Note that you’d have to copy or strdup() the section and name rather than just store pointers to them, because their lifetime is only as long as the handler function.
yes – adding an extra member to the struct to handle state is probably the cleanest route. this issue makes me think of closures – not an option in C though, e.g. taken from wikipedia ‘A closure can be used to associate a function with a set of “private” variables, which persist over several invocations of the function. The scope of the variable encompasses only the closed-over function, so it cannot be accessed from other program code.’
[…] La meilleure ressource que j’ai pu trouver sur le sujet me semble être la page suivante : http://blog.brush.co.nz/2009/02/inih/ On y trouvera plusieurs projets dont le code est adapté à l’embarqué notamment à […]
Thank you very much for this excellent, light-weight ini reader with C++ wrapper. I see the project is still somewhat active, do you plan to add INIReader::GetDouble() method? (I have already added that in my source code)
Hi Baris — I added GetReal() in r28. Good idea — thank you!
Read ini file funcina perfectly. However like to know how to create it.
Good!, senk’s. where is parse multilne and append to array? [test] testing = aaa testing = bbb testing = ccc …. etc
@Alan, inih is just for reading .ini files. No plans at this stage to make it write them.
@Petr, can you be a bit more specific? If you want to append to an array, you’ll have to do it yourself (C doesn’t have very high-level array support anyway). Or are you referring to the C++ API?
Thanks for answer. i’m not this moment of current project use C++ API :(
Hi, where is work for example?
typedef struct { int version; const char* name; const char* email; } configuration;
configuration * cnf = malloc(sizeof(configuration));
… other code… INI not update this config pointer from handle function
Hi Petr, there are some basic examples right on the project homepage: https://code.google.com/p/inih/
Yes, i’m ready. Where is correct use construction: configuration * cnf = malloc(sizeof(configuration));
?
if function handle not sccesing real link to config structure. Creates is new config instance..
Well, answer: pconfig = ((configuration *)(user));
int iniparse(const char* filename, int (handler)(void* confstruct, const char* section, const char* name, const char* value), void* confstruct); int iniparse_file(FILE* file, int (handler)(void* confstruct, const char* section, const char* name, const char* value), void** confstruct);
Sorry, wrong charscters, again:
configuration pconfig = ((configuration *)(user));
Web engine not correct ‘asteriks’ *user))
So can I use this lib in a commercial project? I am not an expert in all this open source lic´s
thanks for your help
@mahtias, yes, it’s BSD-licensed, so commercial use is fine. See: https://inih.googlecode.com/svn/trunk/LICENSE.txtx
ok, thanks
Is there any way to use this inside a for loop, for when you want to read many .ini files?
Hi,
I was wondering if this allows for multiple sections with the same name (so, something like multiple [user] sections).
I’m a little new to C, and it isn’t quite clear to me whether something like this might be possible from the examples.
Thanks!
@Bob, yes, the C API allows for multiple sections with the same name, as it just reads the file sequentially and hands the values to you. You should be able to test this with the examples/ini_dump.c program.
Hmm, I managed to compile ini_dump.c (inih_r29) and tried this, and what I’m seeing is that everything is returned under one giant [user] section.
I’m thinking that this might just be how the “if” statement in the dumper function is handling another section with the same name.
So, if I’m understanding this correctly, inih will do what I want, assuming I use it properly (by passing it a proper handler / dumper), that does I’m looking for.
I think where I’m getting confused is how I would tell that a new “[user] section” has started, so as to not get the values for one [user] section confused with another.
Thanks!
@Bob, that’s a good question. Yes, I didn’t think about that — if the two same-named [user] sections are right next to each other you won’t be able to tell when one ends and the next starts, because the handler just gets passed the names.
You could use a “start_of_section=yes” type of marker as the first field in each section.
However, I wouldn’t recommend this use of inih, as not all INI parsers support sections with the same name etc. I’d probably go with the (dumber but more portable) approach where you use section [user1], then section [user2], etc. And the handler would do “if section name starts with ‘user’…”
I think this guy wrote not just an INI parser, but standardized even the idea of what an INI file is:
@Ben Thank you! Minimal but smooth!
@Louis I played a bit with libconfini and it does look like the ultimate INI parser. The only problem is that hacking the source code seems quite challanging (the text formatting functions are written in some obscure C full of bitwise operators). But if you accept the library as it is it just works like a charm.
Thanks for inventing the bicycle.
Btw wxWidgets does it rather than perfect
http://docs.wxwidgets.org/stable/wx_wxconfigbase.html#wxconfigbase