Let's say, your game is using following, rather standard looking config file, and you want to parse it using SDL_Config:
screen_size_x = 640
screen_size_y = 480
fullscreen = false
Code which you would use to parse this file with SDL_Config could look like this:
if ( CFG_OK != CFG_OpenFile("config_file.cfg", &config ) )
// error ...
if ( CFG_OK == CFG_SelectGroup("Video", 0) )
Sint32 screen_size_x = CFG_ReadInt("screen_size_x", 640);
Sint32 screen_size_y = CFG_ReadInt("screen_size_y", 480);
bool fullscreen = CFG_ReadBool("fullscreen", true);
// use them
First, there goes the definition of object of class CFG_File, which will be responsible for storing informations about our config file's data. What's important, is that you don't need to initialize / deinitialize library in any way.
In next line we open and parse config file with name "config_file.cfg" (what extension you use is up to you) using function CFG_OpenFile(). It returns number, which indicates whether everything went ok, or were there any errors. Obviously, if returned number equals CFG_ERROR or CFG_CRITICAL_ERROR, then error occured and you have to deal with it in a way specific to your project :-) You may use function CFG_GetError to obtain textual description in english of what has happened.
Next we select group "Video", so that all following operations will be performed only on it. As you see, this function also returns number which indicates whether any errors occured etc.
After selecting group, we read the values that we are interested in. CFG_ReadInt takes as its first parameter name of entry and the second one, is default value, which will be returned when such entry wasn't found. It returns value from found entry (or default one). Pretty simple, right? :-) The same logic applies to CFG_ReadBool, CFG_ReadFloat and CFG_ReadText, the only thing which changes is type of second parameter and returned value's type (to bool, float and const char *).
As you probably suspect, CFG_CloseFile(0) closes currently selected file. If you would like to close other file than currently selected, you would pass to this function pointer to it instead of 0.
That's all, file has been parsed. Is this easy or what? ;-)
Let's say that your config file can have an arbitrary number of groups, so you can't made any assumptions when parsing it, ie.
File which holds the information about levels used by game.
Group names ("Level_1" etc.) have no meaning
name = "Blood bath"
model = "bloodbath.md3"
name = "Bloob bath"
model = "bloobbath.md3"
name = "Boob bath"
model = "boobbath.md3"
Iteration over sections in SDL_Config is very easy:
int result = CFG_OpenFile("config_file.cfg", &config );
// typical error detection code etc.
for ( CFG_StartGroupIteration(); !CFG_IsLastGroup(); CFG_SelectNextGroup() )
std :: string name = CFG_ReadText("name", "");
std :: string model = CFG_ReadText("model", "");
And that's it, for() will loop over all groups in file (except for global group) selecting them one after another (in original or alphabethical order). You can call all Read/Write functions and as usual, they'll operate on that currently selected group. If you don't like the need to postfix group names with numbers in order to make them unique, and want to have all groups with the same name yet be able to operate on them, defining CFG_USE_MULTIMAP allows for it.
Multi value entries are one of the extensions of ini format introduced by SDL_Config. They're really useful in real world. For example, let's say that you want to store list of quotes that AI opponent might scream in battle. Here's how you can do it:
name = "Kane"
health = 540
texture = "Textures/kane.png"
weapon = "machine_gun"
battle_quotes = "Burn baby!", "We've found a witch!", "I'm gonna boil you alive", "Get over here"
How to handle above cfg file? Let's say that this time we'lll be using SDL_Config's C++ interface:
return "error"; // deal with error
for ( config.StartMultiValueEntryIteration("battle_quotes"); !config.IsLastMultiValueEntry(); config.SelectNextMultiValueEntry() )
std::string quote = config.ReadText(CFG_MULTI_VALUE_ENTRY_ITERATION, 0);
// that's it!