Class rude::Config
Config is the public interface for the configuration component.
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. |
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();
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
|
|