// Config.h
//
// Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005 Matthew Flood
// See file AUTHORS for contact information
//
// This file is part of RudeConfig.
//
// RudeConfig is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2, or (at your option)
// any later version.
//
// RudeConfig is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with RudeConfig; (see COPYING) if not, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
// 02111-1307, USA.
//------------------------------------------------------------------------
#ifndef INCLUDED_RUDE_CONFIG_H
#define INCLUDED_RUDE_CONFIG_H
namespace rude{
namespace config{
class ConfigImpl;
}
//=
// rude::Config is the public interface for the config/ini file reader.
//=
class Config{
// Bridge component
//
rude::config::ConfigImpl *d_implementation;
public:
//=
// Default constructor
// Use to obtain an instance of the rude::Config component
//
// <b>Example:</b>
// <code>
// rude::Config myconfig;
//
// //OR
//
// rude::Config *myconfig = new rude::Config();
// </code>
//=
Config();
//=
// Returns the version of the component.
//
// The version is specified by <b>X.Y</B> where:
// <B>X</B> is the version of the interface (this class), and
// <B>Y</B> is the version of the implementation (the internals).
//
// <b>Example:</b>
//
// <code>const char *version = Config::version();</code>
//=
static const char *version();
//=
// Sets the default filename to be used by all config objects
// Initially, this value is "default.ini"
// Methods affected include load(void) and save(void)
// This method does not affect already existing instances.
//=
static void setDefaultConfigFile(const char *filepath);
//=
// Returns the default filename to be used by all config objects
//=
static const char *getDefaultConfigFile();
//=
// Sets the default comment character to be used by all config objects
// The comment character affects how config files are parsed, and how they are written.
// Initially, the default comment character is set to '#'
// This method does not affect already existing instances.
//=
static void setDefaultCommentCharacter(char c);
//=
// Returns the default comment character to be used by all config objects
//=
static char getDefaultCommentCharacter();
//=
// Sets the default delimiter character to be used by all config objects
// The delimiter affects how config files are parsed, and how they are written.
// Initially, the default delimiter is set to '='
// This method does not affect already existing instances.
//=
static void setDefaultDelimiter(char c);
//=
// Returns the default delimiter character to be used by all config objects
//=
static char getDefaultDelimiter();
//=
// Sets the default behavior of all config objects in dealing with deleted values.
// The default behavior is for config objects to preserve deleted data as comments when
// the config object is saved
// This method does not affect already existing instances.
//=
static void setDefaultPreserveDeleted(bool shouldPreserve);
//=
// Returns the default deletion behavior
// true means deleted data will be preserved as comments when the config object is saved
// false means that deleted data will be discarded when the config object is saved
//=
static bool getDefaultPreserveDeleted();
//=
// Set's the default filepath to be used by the load() and save() methods
// The default filepath is initially set to "./default.ini"
// Affects the current instance only
//=
void setConfigFile(const char *filepath);
//=
// Returns the default filepath to be used by the load() and save() methods
// The default filepath is initially set to "./default.ini"
// Affects the current instance only
//=
const char * getConfigFile();
//=
// Sets whether or not deleted data will be preserved as comments.
// If set to true, deleted data will be converted into comments when
// the save() method is called. If set to false, deleted data
// will not be compeltely discarded. Default is false (no preserve).
// Affects the current instance only.
//=
void preserveDeletedData(bool shouldPreserve);
//=
// Set's the comment character ( initially set to '#' )
// If the comment character is set to NULL (0),
// then comments will not be written when save() is called
// Affects the current object only
//=
void setCommentCharacter(char commentchar);
//=
// Set's the delimiter for new config objects ( initially set to '=' )
// If the delimiter is set to NULL, then it will be assumed that
// the key and value are separated by whitespace.
// Affects the current object only
//=
void setDelimiter(char kayvaluedelimiter);
//=
//
// When called before load(), saves the configuration to the default config file.
// Initially, the default config file is "./default.ini".
//
// If load was called with an argument:
// load(const char *filename)
// then save() will use the same filename.
//
// The filename used by the instance can be changed by the setConfigFile() method.
//=
bool save();
//=
// Saves the configuration object to the specified file
// The default config file path for the instance is not altered...
// Use setConfigFile(const char *filename) or load(const char *filename) to set the default filename for the instance
//=
bool save(const char *filepath);
//=
// Removes the contents of the configuration file - completely wipes it out.
// Does not preserve anything. Afterwards, the current section is set
// to the empty section (""), which is the unnamed section
// at the beginning of the configuration file.
//=
void clear();
//=
// Loads the default file into the configuration object.
// By default, the current file is 'default.conf',
// but can be overridden by calling the setConfigFile(const char *filename) method.
// This method does not clear the config object before loading.
// If you load two or more configuration files that have the same sections,
// they are effectively merged. In this case, data members that have the same
// name will get the value of the last file loaded. This comes in handy if
// you load a global config file first, and you want to override
// some custom fields by subsequently loading a "preferences" file tailored to an individual.
// Use clear() if the config object already has data that you want to completely discard before loading
// a new file, or use another Config object instance.
//=
bool load();
//=
// Adds the file's configuration info to the current object.
// Does not delete any existing data in the config object.
// The default config file path is not altered...
// Use setConfigFile() to permanently set the default config file for load() and save()
// This method does not clear the config object before loading.
// Use clear() if the config object already has data that you want to discard.
//=
bool load(const char *filename);
//=
// Returns the most recent error string, if there is one.
// If no error exists, it will return the empty string ("").
//=
const char *getError();
//=
// Returns the number of sections in the entire configuration file
// This number includes the default section - "" (the empty section at the beginning of the file)
// Sections within the configuration file are identifed by [Square Brackets] surrounding the name of the section.
// Whitespace surrounding the section name is ignored. So [ This Section ] and [This Section] are identical.
// Section names <b>are</b> case sensitive.
// The default section is the empty section - the unnamed section at the beginning of the file that
// exists before any other [named] sections. This section exists even if the first line of the file
// contains a [named section]. The empty section will simply be void of any data.
// As such, the return value will always be >= 1.
//=
int getNumSections() const;
//=
// Enumeration method to discover sections
// Returns the section name at the given index,
// or NULL if the index is out of range
// If the section has no name, but is a valid index, then it will return the empty string ("")
//=
const char *getSectionNameAt(int index) const;
//=
// Sets the current working [section], possibly creating a new section
// The default section is "" (the untitled section at the beginning of the configuration file).
// If the new section cannot be found, and <b>shouldCreate</b> is <b>true</b>,
// then the section will be created and will exist at the end of all other sections.
// If the new section cannot be found, and <b>shouldCreate</b> is <b>false</b>,
// then the current section remains unchanged, and the method returns false.
// Leading and trailing whitespace is not preserved when the file is written,
// and as such should be avoided when naming sections
//=
bool setSection(const char *sectionname, bool shouldCreate);
//=
// Sets the current working section, creating the section if it does not exist.
// See <b><i>setSection(const char *sectionname, bool shouldCreate)</i></b> where <i>shouldCreate</i> = true.
//=
bool setSection(const char *sectionname);
//=
// Deletes the section identified by <i>sectionname</i> and all data associated with it
// Returns false if the section does not exist or has already been deleted.
// If the object is saved, the entire section will be commented out.
// If, during the lifetime of this object, the section is re-created, then the section will be revived, but all
// previous data members remain commented (as if deleted) unless/until recreated (see deleteData())
//=
bool deleteSection(const char *sectionname);
//=
// Returns the number of data elements for the current section
//
// <b>Example:</b>
//
// Given the following configuration:
//
//<font color=red>[Good Movies]
// The 5th Element
// Resevoir Dogs
// Braveheart
//
// [Bad Movies]
//
// Freddy Got Fingered
// CONfidential
//
// [Body Parts]
// arm=2
// head=1
// legs=2
// neck=1
// ears=2
// eyes=2
//
// </font>
//
// You'll get the following results:
// <code>
// config->setSection("Body Parts", true);
// config->getNumDataMembers(); // returns 6
//
// config->setSection("Bad Movies", true);
// config->getNumDataMembers(); // returns 2
//
// config->setSection("Good Movies", true);
// config->getNumDataMembers(); // returns 3
// </code>
//=
int getNumDataMembers() const;
//=
// Enumeration method to discover data members within the current section
// Returns the name of the data member at
// the specified index within the current
// section, or NULL if the index is out of range.
//
// <b>Example:</b>
//
// Given the following configuration:
//
//<font color=red>[Contact Info]
// name= Mark Twain
// email address = mark@twain
// phone = 123.456.789
// </font>
//
// You'll get the following results:
// <code>
// config->setSection("Contact Info");
// config->getDataNameAt(0); // returns "name"
// config->getDataNameAt(2); // returns "phone"
// config->getDataNameAt(3); // returns NULL (out of range)
//
// </code>
//=
const char *getDataNameAt(int index) const;
//=
// Returns true if a data member exists with the given
//name within the current section
//
//
// <b>Example:</b>
//
// Given the following configuration:
//
//<font color=red>
// [Strong Body Parts]
// arm=2
// head=1
// legs=2
// neck=1
//
// [Weak Body Parts]
// eyes=2
// belly=1
// nose=1
// </font>
//
// You'll get the following results:
// <code>
// config->setSection("Strong Body Parts");
//
// if(config->exists("arm"))
// {
// // yes, arm exists...
// }
//
// if(config->exists("belly"))
// {
// // returns false - belly isn't in that section.
// }
//
// config->setSection("Weak Body Parts");
//
// if(config->exists("belly"))
// {
// // yes! belly is in this section....
// }
// </code>
//=
bool exists(const char *name) const;
//=
// Returns the boolean value of the data identified by <i>name</i> within the current section
// This is a helper function that converts the string data stored in the config object to a boolean
// Returns true if the current value is "on" or 1,
// or if the value starts with the letter 't' or 'y'
// ( all of the above are case insensitive )
// returns false otherwise
//
// As such, it will interpret the following as true:
// Yes, yes, On, on, True, true, 1, T, t, Y, y
//
// Likewise, it will interpret the following as false:
// No, no, Off, off, False, false, 0, F, f, N, n
//
//
// <b>Example:</b>
//
// Given the following configuration:
//
//<font color=red>
// [Things that are and aren't]
// Bed Bugs= TRUE
// Aliens = 1
// Freud= ON
// Water= yes
// ducks = false
// carpenter = off
// floppy = 0
// sand = Nope
// </font>
// You'll get the following results:
// <code>
// config->setSection("Things that are and aren't");
//
// config->getBoolValue("Aliens"); // returns true
// config->getBoolValue("carpenter"); // returns false
// // etc...
// </code>
//=
bool getBoolValue(const char *name) const;
//=
// Returns the integer value of the data identifed by <i>name</i> within the current section
// This is a helper function that converts the string value stored in the config object to an int.
// Returns 0 if the data does not exist or if an integer value cannot be determined.
//=
int getIntValue(const char *name) const;
//=
// Returns the double value, or 0 if a double value cannot be determined
// Thie is a helper function that converts the string value stored in the config object to a double
//=
double getDoubleValue(const char *name) const;
//=
// Returns the string-character value.
// Unless the value is quoted, leading and trailing whitespace is stripped.
// If the value is quoted, the quotes are removed, and leading and trailing whitespace
// within the quotes are preserved.
//=
const char * getValue(const char *name) const;
//=
// Same as <code>const char *getValue(const char *name)</code>
// @deprecated
//=
const char * getStringValue(const char *name) const;
//=
// Sets the named value within the current section to "true" or "false"
// This is a helper function that converts a bool to the string value
// that the config object expects.
// If the value is already set for the data item, the value is changed.
// If the value is not already set, it is created
//
// <b>Example:</b>
//
// To create the following configuration entries:
//
// <font color=red>[On Sale]
// Hard Drives = true
// Cases = false
// Keyboards = false
// </font>
//
// Use this code:
// <code>
// config->setSection("On Sale");
// config->setBoolValue("Hard Drives", true);
// config->setBoolValue("Cases", false);
// config->setBoolValue("Keyboards", false);
// config->save();
// </code>
//
// @param name the identifying name of the data member
// @param value The integer value of the data member
//
//=
void setBoolValue(const char *name, bool value);
//=
// Sets the named value within the current section to the specified integer
// The config object stores values as strings- this is a helper method
// that converts an integer to the expected string value.
// If the value is already set for the data item, the value is changed.
// If the value is not already set, it is created
//
// <b>Example:</b>
//
// To create the following configuration entries:
//
// <font color=red>[Inventory]
// Hard Drives = 35
// Cases = 24
// Keyboards = 103
// </font>
//
// Use this code:
// <code>
// config->setSection("Inventory", true);
// config->setIntValue("Hard Drives", 35);
// config->setIntValue("Cases", 24);
// config->setIntValue("Keyboards", 103);
// config->save();
// </code>
//
// @param name the identifying name of the data member
// @param value The integer value of the data member
//
//=
void setIntValue(const char *name, int value);
//=
// Sets the value for a data item within the current section to the specified double
// The config object stores values as strings- this is a helper method
// that converts an integer to a string value to be stored.
// If the value is already set for the data item, the value is changed.
// If the value is not already set, it is created
//
// <b>Example:</b>
//
// To create the following configuration entries:
//
// <font color=red>[Prices]
// Hard Drives = 59.95
// Cases = 44.00
// Keyboards = 12.25
// </font>
//
// Use this code:
// <code>
// config->setSection("Prices", true);
// config->setDoubleValue("Hard Drives", 59.95);
// config->setDoubleValue("Cases", 44.00);
// config->setDoubleValue("Keyboards", 12.25);
// config->save();
// </code>
//
// @param name the identifying name of the data member
// @param value The double value of the data member
// @author Matt Flood
//
//=
void setDoubleValue(const char *name, double value);
//=
// Sets the value for a data item within the current section to the specified string
// If the value is already set for the data item, the value is changed.
// If the value is not already set, it is created.
// If leading and/or trailing whitespace exists within the value, it will be preserved in
// the config file. The config object will automatically surround the value with quotes.
// Likewise, if the value starts with a quote ("), then the value
// will necessarily be surrounded by quotes to preserve it. As such, programs do not have to, (and
// in fact should not ) perform their own quoting of values. You should provide you own
// quotes only when you are modifying the config/ini file using a text editor or some other means
// besides the RudeConfig object.
//
// Note: Leading and traling whitespace of the identifying fieldname (the key for the data item) is not preserved.
//
// <b>Example:</b>
//
// To create the following configuration entry:
//
// <font color=red>[travel]<br>Travel Agent = Mary Johnson</font>
//
// Use this code:
// <code>
// config->setSection("travel", true);
// config->setStringValue("Travel Agent", "Mary Johnson");
// config->save();
// </code>
//
// @param name the identifying name of the data member
// @param value The string value of the data member
// @author Matt Flood
//
//=
void setValue(const char *name, const char *value);
//=
// Same as setValue(const char *name, const char *value);
// @deprecated
//
//=
void setStringValue(const char *name, const char *value);
//=
// Deletes the data member identified by <i>name</i> (if it exists) in the current section.
// If the configuration object is saved,
// then the data member will be preserved by being commented out.
// If a new value is later assigned to this
// value (in the lifetime of the instance),
// then it becomes undeleted (uncommented).
// Values can only be revived this way using the same instance they were deleted with.
// Otherwise, they become permanent comments.
// See <code>preserveDeletedData(bool shouldPreserve)</code> to alter this behavior.
//
//=
bool deleteData(const char *name);
~Config();
};
} // end namespace rude
#endif
syntax highlighted by Code2HTML, v. 0.9.1