Please Help

RudeConfig™ Open Source C++ Config File Library

Version 5.0.5

DETAIL:  FIELD | CONSTR | METHOD Config

Class rude::Config

Config is the public interface for the configuration component.

Constructor Summary
Config()
          Default constructor
~Config()
          
 
Method Summary
 void clear()
          Removes the contents of the configuration file - completely wipes it out.
 bool deleteData( const char* name )
          Deletes the data member identified by name (if it exists) in the current section.
 bool deleteSection( const char* sectionname )
          Deletes the section identified by sectionname and all data associated with it
 bool exists( const char* name ) const
          Returns true if a data member exists with the given name within the current section
 bool getBoolValue( const char* name ) const
          Returns the boolean value of the data identified by name within the current section
 const char* getDataNameAt( int index ) const
          Enumeration method to discover data members within the current section
 double getDoubleValue( const char* name ) const
          Returns the double value, or 0 if a double value cannot be determined
 const char* getError()
          Returns the most recent error string, if there is one.
 int getIntValue( const char* name ) const
          Returns the integer value of the data identifed by name within the current section
 int getNumDataMembers() const
          Returns the number of data elements for the current section
 int getNumSections() const
          Returns the number of sections in the entire configuration file, including the default section - ""
 const char* getSectionNameAt( int index ) const
          Enumeration method to discover sections
 const char* getStringValue( const char* name ) const
          Returns the string-character value.
 bool load( const char* filename )
          Adds the file's configuration info to the current configuration object.
 bool load()
          Loads the default file into the configuration object.
 void preserveDeletedData( bool shouldPreserve )
          Sets whether or not deleted data will be preserved as comments.
 bool save( const char* filepath )
          Saves the configuration object to the specified file
 bool save()
          Saves the configuration to the default config file.
 void setBoolValue( const char* name, bool value )
          Sets the named value within the current section to "true" or "false"
 void setCommentCharacter( char commentchar )
          Set's the comment character ( initially set to '#' )
 void setConfigFile( const char* filepath )
          Set's the default filepath to be used by the load() and save() methods.
 void setDelimiter( char kayvaluedelimiter )
          Set's the delimiter for new config objects ( initially set to '=' )
 void setDoubleValue( const char* name, double value )
          Sets the named value within the current section to the specified double
 void setIntValue( const char* name, int value )
          Sets the named value within the current section to the specified integer
 bool setSection( const char* sectionname, bool shouldCreate )
          Sets the current working section, possibly creating a new section
 bool setSection( const char* sectionname )
          Sets the current working section, creating the section if it does not exist.
 void setStringValue( const char* name, const char* value )
          Sets the named value within the current section to the specified string
 static const char* version()
          Returns the version of the component.
 

Constructor Detail

Config

public Config();
Default constructor
Use to obtain an instance of the rude::Config component

Example:

rude::Config myconfig;

//OR

rude::Config *myconfig = new rude::Config();


~Config

public ~Config();


Method Detail

clear

public void clear();
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.

deleteData

public bool deleteData( const char* name );
Deletes the data member identified by name (if it exists) in the current section.
If the configuration object is saved,
then the data member will be commented out.
If a new value is later assigned to this
value (in the lifetime of the instance),
then it becomes undeleted (uncommented).

deleteSection

public bool deleteSection( const char* sectionname );
Deletes the section identified by sectionname 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 name becomes uncommented, but all
previous data members remain commented (as if deleted) unless/until recreated (see deleteData())

exists

public bool exists( const char* name ) const;
Returns true if a data member exists with the given name within the current section

Example:

Given the following configuration:

[Strong Body Parts]
arm=2
head=1
legs=2
neck=1
[Weak Body Parts]
eyes=2
belly=1
nose=1

You'll get the following results:

config->setSection("Strong Body Parts", true);

if(config->exists("arm"))
{
// yes, arm exists...
}

if(config->exists("belly"))
{
// returns false - belly isn't in that section.
}

config->setSection("Weak Body Parts", true);

if(config->exists("belly"))
{
// yes! belly is in this section....
}


getBoolValue

public bool getBoolValue( const char* name ) const;
Returns the boolean value of the data identified by name within the current section
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

Example:

Given the following configuration:

[Things that are and aren't]
Bed Bugs= TRUE
Aliens = 1
Freud= ON
Water= yes
ducks = false
carpenter = off
floppy = 0
sand = Nope

You'll get the following results:

config->setSection("Things that are and aren't");

config->getBoolValue("Aliens"); // returns true
config->getBoolValue("carpenter"); // returns false
// etc...


getDataNameAt

public const char* getDataNameAt( int index ) 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.
Example:

Given the following configuration:

[Contact Info]
name= Mark Twain
email address = mark@twain
phone = 123.456.789

You'll get the following results:

config->setSection("Contact Info");
config->getDataNameAt(0); // returns "name"
config->getDataNameAt(2); // returns "phone"
config->getDataNameAt(3); // returns NULL (out of range)


getDoubleValue

public double getDoubleValue( const char* name ) const;
Returns the double value, or 0 if a double value cannot be determined

getError

public const char* getError();
Returns the most recent error string, if there is one.
If no error exists, it will return the empty string ("").

getIntValue

public int getIntValue( const char* name ) const;
Returns the integer value of the data identifed by name within the current section
Returns 0 if the data does not exist or if an integer value cannot be determined.

getNumDataMembers

public int getNumDataMembers() const;
Returns the number of data elements for the current section
Example:

Given the following configuration:

[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


You'll get the following results:

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


getNumSections

public int getNumSections() const;
Returns the number of sections in the entire configuration file, including the default section - ""
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 are 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 default section exists even if the first line of the file is a [named section].
As such, the return value will always be >= 1.

getSectionNameAt

public const char* getSectionNameAt( int index ) 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 ("")

getStringValue

public const char* getStringValue( const char* name ) const;
Returns the string-character value.
Unless quoted, leading and trailing whitespace is stripped.

load

public bool load( const char* filename );
Adds the file's configuration info to the current configuration 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.

load

public bool load();
Loads the default file into the configuration object.
By default, the current file is 'default.conf',
but can be overridden by calling the setConfigFile() 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.

preserveDeletedData

public void preserveDeletedData( bool shouldPreserve );
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).

save

public bool save( const char* filepath );
Saves the configuration object to the specified file
The default config file path is not altered...
Use setConfigFile() to permanently set the default config file for load() and save()

save

public bool save();
Saves the configuration to the default config file.
Initially, the default config file is "./default.ini".
This filename can be changed by the setConfigFile() method.

setBoolValue

public void setBoolValue( const char* name, bool value );
Sets the named value within the current section to "true" or "false"
If the value is already set for the data item, the value is changed.
If the value is not already set, it is created

Example:

To create the following configuration entries:

[On Sale]
Hard Drives = true
Cases = false
Keyboards = false

Use this code:

config->setSection("On Sale", true);
config->setBoolValue("Hard Drives", true);
config->setBoolValue("Cases", false);
config->setBoolValue("Keyboards", false);
config->save();

Parameters:
name - the identifying name of the data member
value - The integer value of the data member

setCommentCharacter

public void setCommentCharacter( char commentchar );
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

setConfigFile

public void setConfigFile( const char* filepath );
Set's the default filepath to be used by the load() and save() methods.
The default filepath is initially set to "./default.ini"

setDelimiter

public void setDelimiter( char kayvaluedelimiter );
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.

setDoubleValue

public void setDoubleValue( const char* name, double value );
Sets the named value within the current section to the specified double
If the value is already set for the data item, the value is changed.
If the value is not already set, it is created

Example:

To create the following configuration entries:

[Prices]
Hard Drives = 59.95
Cases = 44.00
Keyboards = 12.25

Use this code:

config->setSection("Prices", true);
config->setDoubleValue("Hard Drives", 59.95);
config->setDoubleValue("Cases", 44.00);
config->setDoubleValue("Keyboards", 12.25);
config->save();

Parameters:
name - the identifying name of the data member
value - The double value of the data member

setIntValue

public void setIntValue( const char* name, int value );
Sets the named value within the current section to the specified integer
If the value is already set for the data item, the value is changed.
If the value is not already set, it is created

Example:

To create the following configuration entries:

[Inventory]
Hard Drives = 35
Cases = 24
Keyboards = 103

Use this code:

config->setSection("Inventory", true);
config->setIntValue("Hard Drives", 35);
config->setIntValue("Cases", 24);
config->setIntValue("Keyboards", 103);
config->save();

Parameters:
name - the identifying name of the data member
value - The integer value of the data member

setSection

public bool setSection( const char* sectionname, bool shouldCreate );
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 shouldCreate is true,
then the section will be created.
If the new section cannot be found, and shouldCreate is false,
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 creating sections

setSection

public bool setSection( const char* sectionname );
Sets the current working section, creating the section if it does not exist.
See setSection(const char *sectionname, bool shouldCreate) where shouldCreate = true.

setStringValue

public void setStringValue( const char* name, const char* value );
Sets the named value 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 by surrounding the value with quotes.
Likewise, if the value starts with a quote ("), then the value
will necessarily be surrounded by quotes to preserve it.
Note: Whitespace within the identifying fieldname (the key for the pair) is not preserved.

Example:

To create the following configuration entry:

[travel]
Travel Agent = Mary Johnson


Use this code:

config->setSection("travel", true);
config->setStringValue("Travel Agent", "Mary Johnson");
config->save();

Parameters:
name - the identifying name of the data member
value - The string value of the data member

version

public static const char* version();
Returns the version of the component.

The version is specified by X.Y where:
X is the version of the interface (Config), and
Y is the version of the implementation (ConfigImpl).

Example:

const char *version = Config::version();

DETAIL:  FIELD | CONSTR | METHOD Config
Generated on October 04, 2003 at 13:32