Currently it is only shown how to set up MiniINI using GCC on Unix. It should be reasonably simple to set it up in any other environment, though. All you need is to add a library path to where you have the compiled library and/or its debug build (bin/ by default), link with it, and add a header path to top MiniINI directory.
First, install MiniINI (see instructions in readme). Create a file named makefile in your project directory, with following contents:
debug: example.cpp g++ -g -Wall -o example-debug example.cpp -lminiini-dbg optimized: example.cpp g++ -O3 -o example-optimized example.cpp -lminiini clean: rm -f example.o example-debug example
When you type make to the terminal, this makefile will compile debug build by default, linked with debug build of MiniINI. To build optimized build, linked with optimized MiniINI, type make optimized. To remove built files, type make clean.
In the debug target, -g is used to add debugging symbols to the exe and -Wall to provide basic warnings. Note -lminiini-dbg, which links the program with the debug build of MiniINI.
In the optimized target, we use -O3 for maximum optimization. (Note: -Os can sometimes give better results with MiniINI, especially if your program is small.) -lminiini links to the default (optimized) build of MiniINI.
The clean target removes any files created by compilation.
Most MiniINI methods have two versions: one for STL users, using C++ strings and vectors, and one for plain C strings and arrays. The latter are usually a bit more difficult to use, but also faster. Here we explain to use MiniINI both the STL way and the plain C data way. In order to show STL versions of methods in the tutorial, we will explicitly convert C strings to C++ strings even where we'd be passing literal strings directly in normal use.
There is only one header you need to include to use MiniINI. That is miniini.h. We also include iostream so we can show what we read from the inifile.
#include<miniini.h> #include<iostream>
For this example, create a file named example.ini, with these contents:
[general] AppName=HugeRTS2 AppBuild=4242 Brightness=0.5 FullScreen=true
This is the kind of ini file that could be used in a game. We have some basic settings here.
Now create a file called example.cpp . In this example, most of the code is in the *main* function.
int main() {
The most important class you're going to use in MiniINI is INIFile. This class handles loading of ini files and accessing ini sections. Here we declare an INIFile, then open our example file using the OpenFile method. This method will load given ini file to memory and process it. If you are not using STL methods, name of the section must be a valid zero terminated string. If the file was succesfully opened and processed, OpenFile returns true. If the file does not exist, could not be opened, is corrupted or otherwise invalid, OpenFile returns false and we print out an error. Note that you can only call OpenFile on an unitialised INIFile, i.e. you can't load to an INIFile that is already loaded.
Non-STL version:
INIFile ini; if(!ini.OpenFile("example.ini")) std::cout << "ERROR: Could not open example.ini" << std::endl;
STL version:
INIFile ini; std::string fname = "example.ini"; if(!ini.OpenFile(fname)) std::cout << "ERROR: Could not open example.ini" << std::endl;
We get access to the [general] section using the GetSection method. This method returns a pointer to the INISection with given name, which is a class we use to read values from a section. If the section does not exist, it returns NULL and we print out an error. If you're not using STL methods, name of the section must be a valid zero terminated string.
Note that MiniINI is case sensitive, so, for instance, [general] and [General] are not the same thing. Also, MiniINI ignores all spaces, so name=val is the same as name = va l.
Non-STL version:
INISection * general = ini.GetSection("general"); if(!general) std::cout << "ERROR: Missing section [general] in example.ini" << std::endl;
STL version:
std::string sname = "general"; INISection * general = ini.GetSection(sname); if(!general) std::cout << "ERROR: Missing section [general] in example.ini" << std::endl;
Now we can load some data from [general]. First we declare variables to which we read data using the ReadString, ReadInt, ReadFloat and ReadBool methods of INISection.
All these methods take two arguments: name of the tag and reference to variable to read data to. Again, if you're not using STL methods, name of the tag must be a valid zero terminated string. In case of non-STL ReadString, only a pointer (C string) to string inside INISection is returned, so the data is not copied. This requires the char pointer to be const, so that it can't change internal INISection data.
NOTE: This means that, if you're using the non-STL ReadString method, you have to copy the string data somewhere before INIFile is destroyed if you still want to use it (i.e. before it goes out of scope or is deleted).
These methods return true on success and false if the tag does not exist or is invalid (for instance when we ReadInt from a tag that does not contain data parsable as an int - this also issues a warning with the debug build when logging callback is provided.)
When we have the data, we print it out so we can see what we've read.
Non-STL version:
const char * appname; int appbuild; float brightness; bool fullscreen; if(!general->ReadString("AppName", appname)) std::cout << "ERROR: Missing tag AppName= in section [general] in example.ini" << std::endl; if(!general->ReadInt("AppBuild", appbuild)) std::cout << "ERROR: Missing or invalid tag AppBuild= in section [general] in example.ini" << std::endl; if(!general->ReadFloat("Brightness", brightness)) std::cout << "ERROR: Missing or invalid tag Brightness= in section [general] in example.ini" << std::endl; if(!general->ReadBool("FullScreen", fullscreen)) std::cout << "ERROR: Missing or invalid tag FullScreen= in section [general] in example.ini" << std::endl; std::cout << appname << " build " << appbuild << " fullscreen is " << fullscreen << " brightness is " << brightness << std::endl;
STL version:
std::string appname; int appbuild; float brightness; bool fullscreen; std::string appname_tag = "AppName"; std::string appbuild_tag = "AppBuild"; std::string brightness_tag = "Brightness"; std::string fullscreen_tag = "FullScreen"; if(!general->ReadString(appname_tag, appname)) std::cout << "ERROR: Missing tag AppName= in section [" << sname << "] in example.ini" << std::endl; if(!general->ReadInt(appbuild_tag, appbuild)) std::cout << "ERROR: Missing or invalid tag AppBuild= in section [" << sname << "] in example.ini" << std::endl; if(!general->ReadFloat(brightness_tag, brightness)) std::cout << "ERROR: Missing or invalid tag Brightness= in section [" << sname << "] in example.ini" << std::endl; if(!general->ReadBool(fullscreen_tag, fullscreen)) std::cout << "ERROR: Missing or invalid tag FullScreen= in section [" << sname << "] in example.ini" << std::endl; std::cout << appname << " build " << appbuild << " fullscreen is " << fullscreen << " brightness is " << brightness << std::endl;
Now you should have the basic idea about how to use MiniINI. All that is left is to finish the main function. This is where our ini file goes out of scope, and all its data is deleted.
return 0; }
You can find example code for this tutorial in the example/Getting_started directory in the MiniINI package. To learn about other features of MiniINI, read other tutorials or the API documentation.