MiniINI version 0.2

1. Introduction

MiniINI is a a free/open source, minimalistic, simple to use C++ library for reading ini (or cfg) files. It has no dependencies (that might change in the future, but it is unlikely) and should compile on any platform with a standards compliant compiler. (only a makefile for GCC is included at the moment, though)

Main priority of MiniINI is, as its name suggests, minimalism and speed. The goal is to create fastest ini library possible supporting the most common ini features without sacrificing ease of use. MiniINI should be useful especially for game development, for instance game settings, properties of units in strategy games, etc.

Debug build of MiniINI can also check ini files it reads, and issue warnings for the most common mistakes in ini code. This should be useful mainly for users of programs using MiniINI, for instance game modders.

At the moment, the feature set of MiniINI is quite limited; for instance, there is no support for multiple values in one tag. This should improve in future versions.

You can get newest versions of MiniINI at https://launchpad.net/miniini .

1.1. INI file format

INI files are text files containing simple values formatted as tag=value pairs, for example:

answer=42

These are grouped in ini sections which start by headers containing names in square brackets, for example:

[section]

Optionally, ini files can contain comments, which are ignored. Comments usually start by a semicolon (default in MiniINI) or hash and continue to the end of line. Example:

tag=value ;comment

A simple complete ini file example:

[General]
OS=Linux
Version=0.4
Renderer=OpenGLRenderer

[OpenGLRenderer]
ScreenWidth=1024
ScreenHeight=768
UseShaders=true

2. Features

• Reads most ini or cfg files.

• Is case-sensitive. That means that [CASE], [case] and [Case] are not the same and there is a difference between Tag= and TAG=

• Provides methods to read C strings, ints, floats and bools from inifile and checks the ini data for errors, allowing the programmer to use their own default values.

• In debug build, issues warnings to the user, for instance when a tag from which the program tries to load an int contains something else.

• Programmer can supply a callback to process the warnings (by default, they are printed to standard output)

• Cannot write to ini files at this time. This should be implemented in future, but is not a priority at the moment.

• Ignores all spaces, i.e. no spaces/tabs in tags or values. For example:
  
  tag=125685
  and
  t a g = 125 685
  
  both have the same meaning. Spaces might be supported in the future for values, if there will be a need, but are not planned at the moment.

• Supports single line comments with a configurable comment character. So if you want to use # instead of ; , you can. There is no support for multiple comment characters mainly for performance reasons.

• Does not support multiline comments, like C /* */ comments. This is planned to be implemented in future.

• Can read arrays of data from numbered sequences of tags, for example:
  
  a1=1
  a2=2
  a3=3
  
  However, sequences have to be ordered from lowest to highest index. If they are not ordered, a warning is issued (with debug build), and only tags before the first tag in wrong order are read.

• There is no support for multi-value tags yet, although they are planned for the future.

3. Compiling/Installing/Using

3.1. Directory structure

MiniINI files are split into multiple directories:

• ./ (top-level directory)
  MiniINI include file and this readme.

• ./miniini
  MiniINI source code

• ./bin
  Compiled binary files, e.g. the library itself.

• ./doc
  Documentation for MiniINI.

• ./example
  Example MiniINI program.

• ./test
  Files for MiniINI regression tester.

3.2. Requirements

MiniINI should compile on any standards compliant C++ compiler, and requires no third-party libraries. If you have gcc, there is a GNU makefile tested with gcc 4.x , which probably also works with older gcc versions.

3.3. Compiling/Installing with gcc

Type make in terminal. Then type make install as a root user (e.g. sudo make install if you have sudo) This will compile and copy optimized MiniINI build to /usr/lib/libminiini.a , debug build to /usr/lib/libminiini-dbg.a , and copy miniini headers to */usr/include/.

Debug and optimized versions can also be compiled separately using make debug and make optimized

You can also uninstall MiniINI by typing make uninstall as a root user.

3.4. Using MiniINI

First, you will need to include miniini.h header file and link with either debug or optimized miniini build. To include MiniINI, add this line to your code:

#include<miniini.h>

To link with MiniINI using GCC, add this to your compiler options:

-lminiini

for optimized or

-lminiini-dbg

for debug build.

If you didn’t install MiniINI, you’ll also need to add path with miniini.h to header paths of your compiler and path with libminiini.a or libminiini-dbg.a to linker paths.

For more info you can check reference manual in ./doc directory and example in ./example directory.

4. License

MiniINI is free/open source software distributed under the MIT/X11 license. This license allows you to use MiniINI in both open and closed source software, free of charge, and modify it if you need to.

Full text of the license:

5. Contact/Credits

MiniINI homepage at Launchpad: https://launchpad.net/miniini

MiniINI was created by Ferdinand Majerech aka Kiith-Sa (kiithsacmp@gmail.com)

MiniINI was created using Vim and GCC on Ubuntu Linux, as an ini reading library for Catom (https://launchpad.net/catom) .

Last updated 2010-01-05 13:29:46 CEST