ofxIniSettings

openFrameworks addon for providing a simple and straightforward way to manage settings with INI config files.

Introduction

ofxIniSettings is built on top of the single header mINI c++ library to provide simple reads and writes to INI files. This can be used standalone without any other addon dependency. All variables are stored as string types, and conversions exist for the standard c++ types, and a few openFramework specific types (ofVec2f, 3f, 4f, ofColor).

Installation

Either clone or download the code into the openFrameworks/addons/ folder. Then you can use the OF Project Generator to add this addon to your project.

Usage

1. Create the ofxIniSettings object

   ofxIniSettings settings;

2. Save some parameters to the object

   int myInt = 0;
   string myString = "Test";
   
   // Add parameters to the setting structure
   settings.setInt("Section Name", "IntKey", myInt);
   settings.setString("Section Name", "StringKey", myString);
   
   // Save the file
   settings.save(ofToDataPath("settings.ini"));

3. Load the file and parameters

   // Load the file
   settings.load(ofToDataPath("settings.ini"));
   
   // Load parameters
   int myInt = settings.getInt("Section Name", "IntKey");
   string myString = settings.getString("Section Name", "StringKey");

Examples

• Open the /example-simple directory for a simple example that loads an ini file and writes changes to console.
• Open the /example-ofxGui directory for an example of loading and saving settings with a GUI made with ofxGui using ofParameter style variables.

Class Documentation

Documentation is generated using Natural Docs. Clone or download the repository and open /docs/index.html to find class and function documentation.

Known issues

None (I think??)

Why did I make this?

openFrameworks by default only has an interface to save a settings file in the .xml format. In my opinion, although any plaintext format is as good as the next in terms of programmatically reading and writing to a file, making the file human-readable is another thing altogether. Trying to read XML files really hurts the eyes and possibly the brain.

Here are some quick comparisons of the same set of parameters setup in 3 different formats:

XML

<!-- Information-->
<stats>
	<name>HoLee Schitt</name>
	<height>183</height>
	<ishungry>false</ishungry>
</stats>

JSON

{
"comment":"Information",
"stats":
	{
		"name":"HoLee Schitt",
		"height":"183",
		"ishungry":"false"
	}
}

INI

; Information
[stats]
name = HoLee Schitt
height = 183
ishungry = false

I definitely find that INI is much more human readable. It does come with certain tradeoffs like not being able to make nested sections, but those are easily fixed by adding something like your own dot syntax:

[parentsection]
parameter = 0

[parentsection.childsection1]
parameter = 0

[parentsection.childsection2]
parameter = 0

In the context of creating a good, readable, and painless interface for settings, I find it more than adequate for the job. I won't go so far as to claim that it is the defacto standard for storing any kind of configuration data, but its damn close to it.

License

ofxIniSettings is available under the MIT License.

Contributing

If you want to contribute to this (admittedly tiny) addon, fork the repo and create a pull request with your changes. Make sure you update documentation in your PR before sending.

Credits

• pulzed - mINI