rudeconfig - Man Page

read and manipulate .ini and config files

Synopsis

#include <rude/config.h>

rude::Config myconfig;

STATIC METHODS

static const char *rude::version();

static void rude::setDefaultConfigFile(const char *filepath);

static const char *rude::getDefaultConfigFile();

static void rude::setDefaultCommentCharacter(char c);

static char rude::getDefaultCommentCharacter();

static void rude::setDefaultDelimiter(char c);

static char rude::getDefaultDelimiter();

static void rude::setDefaultPreserveDeleted(bool shouldPreserve);

static void rude::setDefaultPreserveDeleted(bool shouldPreserve);

REDEFINING INSTANCE BEHAVIOR

void setConfigFile(const char *filepath);

const char * getConfigFile();

void preserveDeletedData(bool shouldPreserve);

void setCommentCharacter(char commentchar);

void setDelimiter(char keyvaluedelimiter);

LOADING AND SAVING FILES

bool save();

bool save(const char *filepath);

void clear();

bool load();

bool load(const char *filename);

const char *getError();

SECTION METHODS

int getNumSections() const;

const char *getSectionNameAt(int index) const;

bool setSection(const char *sectionname, bool shouldCreate);

bool setSection(const char *sectionname);

bool deleteSection(const char *sectionname);

KEY/VALUE DISCOVERY METHODS

int getNumDataMembers() const;

const char *getDataNameAt(int index) const;

bool exists(const char *name) const;

DATA ACCESSORS

bool getBoolValue(const char *name) const;

int getIntValue(const char *name) const;

double getDoubleValue(const char *name) const;

const char * getValue(const char *name) const;

const char * getStringValue(const char *name) const;

DATA MUTATORS

void setBoolValue(const char *name, bool value);

void setIntValue(const char *name, int value);

void setDoubleValue(const char *name, double value");

void setValue(const char *name, const char *value);

void setStringValue(const char *name, const char *value);

KEY/VALUE DELETION

bool deleteData(const char *name);

DESTRUCTOR

~Config();

Description

The rudeConfig library is used to read and manipulate .ini and configuration files.

configuration/.ini File Format

Configuration and .ini files have the following structure:

A configuration file contains one or more "sections".  Each "section" contains 0 or more "key=value" pairs.  Sections can also contain blank lines and comments

Sections are identified by the section name surrounded by square brackets - like [example section]. The unnamed, or default section, is represented by empty square brackets - as in []. The beginning of the configuration file, up to the first named section, is also considered part of the unnamed/default section. White space surrounding the section name is ignored.  Quotes can be used in section names if desired.  As such, the following section names are identical:

[State Codes]
[  State Codes  ]
[ "State Codes" ]

The default delimiter for key/value pairs is the equals (=) sign.   The default comment character is the hash (#).   These can be changed via the API to any character, with a few restrictions:  The key/value delimiter cannot be '\' (escape), '[' (left square bracket), or any end of line character.   The comment character cannot be '\' (escape), '[' (left square bracket) or '"' (double quote).   Furthermore, the key/value delimiter cannot be set to the same value as the comment character.

The key of each key/value pair within a section must be unique. If the same key appears more than once within a given section, all but the last key will be ignored. If more than one configuration file is are loaded into the same rude::Config object, duplicate key/value pairs will replace existing ones.

Although sections of a given name can be repeated in a physical configuration file, they are logically combined when the rude:Config object parses the file. If the rude:Config object is subsequently saved, then the sections will be merged- with all key/value pairs occurring one section.  An example of multiple sections with the same name is given here:

# beginning of example .ini file
[State Codes]
AZ = Arizona
CO = Colorado
[State Codes]
NY = New York
CA = California
[State Codes]
PA = Pennsylvania
IL = Illinios
#end of example .ini file

Comments do not have to start at the beginning of a line.  They can appear after section declarations (on the same line) and they can appear after key=value pairs.

# -- first line of config file --
# this is in the default section
# this is a comment
# the following line is a key=value pair
color=blue
[contact information]
# this is a new section
first name=Matthew
last name = Flood 	# comments are allowed after key=value pairs
[]
# since there is no section name, this is the default section again
size=large
[login info]
username=scruffy
password=$$324reeWrew65456
[contact information]
# this section is a continuation of contact information section listed earlier
#
# the following key=value pair demonstrates using quotes for multi-line values
address="111 example street
apartment Z"
city=boulder
# -- end of config file --

Examples

Examples, how-to's and tutorials can also be found at the rudeserver.com website

Basic Usage

#include <rude/config.h>

int main(void)
{
   // Create config object
   //
   rude::Config config;

   // load a configuration/.ini file
   config.load("myfile.ini");

   // read information
   //
   config.setSection("General Info");
   double cost = config.getDoubleValue("Cost");
   const char *company = config.getStringValue("Company Name");

   // create information
   //
   config.setSection("new section");
   config.setStringValue("animal type", "giraffe");
   config.setBoolValue("mammal", true);

   // save changes
   //
   config.save();
   return 0;
}

See Also

rudecgiparser(3), rudedatabase(3), rudesocket(3), rudesession(3)

Reporting Problems

Before reporting a problem, please check the rudeserver.com web site to verify that you have the latest version of rudeconfig; otherwise, obtain the latest version and see if the problem still exists.  Please read the  FAQ at:

             http://www.rudeserver.com/

before asking for help.  Send questions and/or comments to  matt@rudeserver.com

Authors

Copyright (C) 2000 Matthew Flood (matt@rudeserver.com)

This  software is provided "as-is," without any express or implied warranty.  In no event will the authors be held liable for any damages arising from the use of this software.  See the distribution directory with respect  to  requirements  governing  redistribution. Thanks to all the people who reported problems and suggested various improvements in rudeconfig; who are too numerous to cite here.

Referenced By

rudesocket(3).

January 19, 2006 Version 5.0 User Manuals