SourceForge project page
Web Links

Have you noticed that there aren't many open-source libraries for parsing configuration files?

Well, I have noticed it some time ago - and decided to fill this gap with a library of my own production. It had to be, among other things, flexible, easy-to-use, portable and have good documentation. Since the SDL team made similiar design requirements, knowing also that it was very popular, I decided to connect my library somehow with SDL, and as such, created an API similiar to SDL and other closely connected SDL libraries, like SDL_Image, SDL_TTF, SDL_Mixer etc.

After that decision, other things went fast: I called my library SDL_Config, hosted it on Sourceforge, written it in C/C++ and released source code under the GNU LGPL license (with one little change - read here). Since SDL_Config uses from SDL only SDL_Rwops functionality, it is compatible with SDL 1.2 branch and possibly also a lot older versions, but I haven't tested that.

After that little bit of history, let's get down to more interesting things.
If you don't know what those config files really are, take a look at next paragraph for very simple example, or click here for some more advanced examples.


screen_size_x = 640
screen_size_y = 480
color_depth = 32

Such config file could be used in computer game, to store information about resolution and color depth.

What are advantages of using config files over storing your values in code, scripts or binary files? Some are listed here:

  • if you want to temporarily change game resolution (or fullscreen/window status), and you store such values in code, you have to recompile it - and as you probably know, compilation in some languages (C++ especially) is a slow process. If you are using text config files, there's no need to recompile anything - everything can be edited fast, even in Notepad.

  • similiary, binary files often need some kind of editor - which needs to be written, debugged, maintained etc. Pretty much work, considering that config files can be edited by anything what can edit text.

  • config files can be easily tweaked by end user. Their structure is easy to understand... unlike C++ source code ;-) OTOH, if you don't want to give user ability to change values because they are so important, this feature can annoy... but don't worry, there are solutions to this problem (ie. loading config files from encrypted zip archives - you can do such things with SDL_Config using SDL_RWops streams).

  • config files are much lighter than scripts, easier to incorporate and maintain - less coding, less bugs, higher productivity etc. If you just want to keep file with some values, without any logic behind it - config files are for you.

Ok, nuff' of this advertising. Next topic please:

What SDL_Config is and what it isn't, what it can and what it can't do:

  • it can natively read Windows .INI (and compatible) files. Also, it shouldn't have problems with some (*) Linux .conf files.

  • it can parse files, but it won't interpret them for you - only you know what those numbers and chars in config files really mean. Btw, here you can read about some of potential uses for them.

  • dividing config file into logical groups helps to efficiently maintain it. Obviously, groups are supported by SDL_Config :-) There's also global group, which contains entries that were found before first explicit group definition. If you will ask for entry, and it won't be found in selected group, then library will check if it exists in global group, and if so, return its value - all transparently to coder.

  • it supports four basic entry types: boolean (true/false), integer (32 bit signed), float (standard C++ float) and text (internally null terminated C string, can store Unicode characters (not yet) ). Types are automatically determined by looking at entry's value, you don't need to explicitly write them.

  • it allows you to comment your entries and groups. If you save your config file to disk (or anywhere else), original comments will stay next to appropriate entries/groups. Supported types of comments are:

    • C++ style: //

    • Windows .INI style: ;

    • PHP style: #

    • C style multiline comment also can be used (with some small restrictions): /* */

    After finding one of those in line (**), everything after it is treated as comment, that is: ignored, not parsed further. Library also contains API for dealing with comments in code.

  • you are free to format your configuration files in similiar way to C/C++ or other high level programming languages. So, it doesn't matter if you write:

    hello = world


    hello = world

    Parser will interpret all of them with the same results. You can use as many whitespaces (spaces and tabs) in one line as you want, indent them, add blank lines, freely use comments etc. There is only one rule: each entry should begin and end in one line. Simple, ehh? So, this is forbidden:

    hello =

  • Multiple value entries are also supported! You can have entry which holds many values, the syntax is very natural. Also, using such entry from within code is easy. Example:

    maps = "", "", ""
    someNumbers = 23, 34, 256, -43, 217
    bit_pattern = on, off, on, on, on, off, off
    vector_3d = 34.67, -12.3, 0.0

  • Key value substitution, very powerful functionality similar to defines in C++, is also supported.

    instal_dir = "C:/Games/"
    subdir = "MagicPencil/"
    game = "MagicPencil.exe"
    full_exec = $(instal_dir) $(subdir) $(game)

    As expected, after reading in code the value of full_exec you'll get C:/Games/MagicPencil/MagicPencil.exe

  • If you don't like the default syntax, you might very easily change some keywords at runtime(!) so that ie. your cfg files might look like this:

    ! yeaah, this is comment
    < Type O Negative > ! group
    Bloody_Kisses : ^Christian Woman^ | ^Summer Breeze^ |^Bloody Kisses^ | ^Black No.1^ !!!!!! multi value entry

  • If you're using C++, you might find SDL_Config's C++ interface very useful - it nicely automates a few things, ie. you don't need to remember about closing file or selecting it every time you use it.

  • SDL_Config is fast! it parses 1MB .cfg file containing 2000 groups, each with a dozen of entries in a second... don't believe? see test 008

  • If you want to see full list of features that is available in current version, click here. Nice thing for users is that I, the author of the library, am using it in almost all of my projects, constantly testing it in new scenarios, debugging, refining and polishing.


(*) As far as I know, there's no one, standard syntax definition of configuration files on Linux (actually, some of them look more like scripts), so there's no way to write general config file parser. Simple as that. Of course, if you will stick to general rules, your config files will be interpreted correcly on all operating systems. I just want to say, that some config files in Linux aren't supported by SDL_Config. But would you expect from model loader, designed for loading models from custom format, to support all other formats in the world? ;-)

(**) If you are worried that keeping such characters as ; in your config files text entries will make you troubles - there's no need to worry. Assuming that strings with such characters are enclosed by double quotes ", parser will behave correctly.

Posted by Koshmaar on December 30 2005 17:42:018479 Reads - Print


Forgotten your password?
Request a new one here.
Banners Logo

Get Firefox!

Copyright © Hubert "Koshmaar" Rutkowski 2005