ms_customproperty Class Reference

The class is used as a base for property-containing classes, such as ms_mascotoptions. More...

#include <ms_customproperty.hpp>

Inheritance diagram for ms_customproperty:

Public Member Functions
	ms_customproperty ()
	Default constructor.
	~ms_customproperty ()
	Destructor.
void	appendProperty (const char *name, const char *value, const char *delimiter, const bool bFirstPlace=false)
	Adds a new property with the given parameters.
void	appendText (const char *line, const bool bFirstPlace=false)
	Adds a new non-parsed property.
void	copyFrom (const ms_customproperty *src)
	Copies all properties and comments from another instance.
void	defaultValues ()
	Removes all property entries and comments.
void	delNonEmpty ()
	Deletes all non-comment properties.
void	delProp (const char *name)
	Deletes all properties with the specified name.
void	delPropByNumber (const int index)
	Deletes a single property with the specified number only.
void	delPropStart (const char *nameBeginning)
	Deletes all properties whose names start with the given string.
int	findProperty (const char *name, const int startFrom=0) const
	Searches the list for a property with the given name.
int	findPropertyBeginning (const char *nameBeginning, const int startFrom=0) const
	Searches the list for a property with the partially matching name.
std::string	getDefaultDelimiter () const
	Return current default delimiter string used for parsing/storing properties.
std::string	getDelimiterByNumber (const int index) const
	Returns a specific delimiter used for the property.
int	getNumberOfProperties () const
	Returns a total number of property/comment entries.
std::string	getPreceedingComments () const
	Returns any comments preceeding the section.
std::string	getPropertyName (const int index) const
	Returns a property name for a given index.
std::string	getPropValStringByName (const char *name) const
	Retrieves property value by name.
std::string	getPropValStringByNumber (const int index) const
	Retrieves property raw text values by number.
void	setDefaultDelimiter (const char *delim)
	Allows to set a specific delimiter string to be used when no property-specific delimiter is supplied.
void	setPreceedingComments (const std::string &comments)
	Sets any comments preceeding the section.
void	setPropertyName (const int index, const char *name)
	Changes name of the property with the given index.
void	setPropValBoolByName (const char *name, const bool value, const bool bFirstPlace=false)
	Changes a boolean value of the first entry with the given name or creates a new property if it is not found.
void	setPropValCharByName (const char *name, const char value, const bool bFirstPlace=false)
	Changes a single character value of the first entry with the given name or creates a new property if it is not found.
void	setPropValFloatByName (const char *name, const double value, const bool bFirstPlace=false)
	Changes an floating point value of the first entry with the given name or creates a new property if it is not found.
void	setPropValInt64ByName (const char *name, const INT64 value, const bool bFirstPlace=false)
	Changes a long 64-bit integer value of the first entry with the given name or creates a new property if it is not found.
void	setPropValIntByName (const char *name, const int value, const bool bFirstPlace=false)
	Changes an integer value of the first entry with the given name or creates a new property if it is not found.
void	setPropValStringByName (const char *name, const char *value, const bool bFirstPlace=false)
	Changes a string value of the first entry with the given name or creates a new property if it is not found.
void	setPropValStringByNumber (const int index, const char *value)
	Changes an string value of an existing property with the given index.
bool	uncommentProp (const int index, const char *delimeter=0)
	Uncomments a line in the configuration file.

Detailed Description

The class is used as a base for property-containing classes, such as ms_mascotoptions.

This class functionality is designed to allow users store and retrieve specified and unspecified (custom) properties as well as comments.

Not every configuration file can hold custom properties and/or comments. Whether a configuration file can have custom properties or not depends on its format. For example, almost all sections of the main configuration file mascot.dat can have unspecified properties and comments, whereas Databases section of the same file cannot have either of them. Another example of non-supported custom properties is unimod.xml whose structure and syntax is defined in a corresponding xml-schema file and cannot be altered temporarily.

Normally, custom properties are used in the following cases:

• future releases of software can introduce additional properties that can still be retrieved using old msparser-library;
• when a client application needs to know exactly whether a certain property is explicitly specified in the configuration file or set to it's default value;
• additional comments can be added/accessed programmatically and then stored in the disc file;
• client application needs a raw text representation of a property instead of a set of parsed values.

Note that functionality related to comments is not particularly advanced. Comments are all treated uniformly like properties with empty names and can be retrieved only by number. New comments can be added only at the end of existing properties list using either appendText("# comment line preceded by a hash-character") or appendProperty("", "# comment line", ""). They can also be dropped/altered by number.

All properties in configuration files have three elements associated with them:

• Name - an empty case-insensitive string in case of comments.
• Value - raw text representation (comment line will normally start with # character).
• Delimiter - a string between name and value in the configuration file. It can be a space character, comma, colon, tab or a combination of them. Delimiting characters are usually stripped out of property name and value and stored separately. When adding a new property without explicitly specified delimiter string a default one will be used.

Not necessarily all these elements are used and stored in a file – consult the documentation of the particular configuration file format. An instance of the class rather serves as a container of properties only. It doesn't have any file reading/writing functionality.

Member Function Documentation

appendProperty()

void appendProperty	(	const char *	name,
		const char *	value,
		const char *	delimiter,
		const bool	bFirstPlace = false
	)

Adds a new property with the given parameters.

Parameters

name	a property name to use.
value	a property value to use.
delimiter	a specific delimiter or an empty string for a default one to be used.
bFirstPlace	forces a new property to be put on top of the list.

appendText()

void appendText	(	const char *	l,
		const bool	bFirstPlace = false
	)

Adds a new non-parsed property.

All property elements will be retrieved from the first parameter. Before calling this method, a specific default delimiter can be set using setDefaultDelimiter().

Parameters

l	raw text representation of the property to be parsed.
bFirstPlace	forces a new property to be put on top of the list.

delProp()

void delProp

(

const char *

str

)

Deletes all properties with the specified name.

Parameters

str	Property name to find a match and then delete.

delPropStart()

void delPropStart

(

const char *

str

)

Deletes all properties whose names start with the given string.

Parameters

str	Beginning a first part of the property name to delete.

findProperty()

int findProperty	(	const char *	name,
		const int	startFrom = 0
	)		const

Searches the list for a property with the given name.

If no property found with the given name -1 will be returned. There may be several property entries in the list with the same name.

Parameters

name	a property name to be found.
startFrom	a minimal property index to start search from.

Returns

a property index or -1 if no property found.

findPropertyBeginning()

int findPropertyBeginning	(	const char *	nameBeginning,
		const int	startFrom = 0
	)		const

Searches the list for a property with the partially matching name.

If no property found with the given name part -1 will be returned. There may be several property entries in the list whose names start with the given string.

Parameters

nameBeginning	first part of a property name to be found.
startFrom	a minimal property index to start search from.

Returns

a property index or -1 if no property found.

getDefaultDelimiter()

std::string getDefaultDelimiter

(

)

const

Return current default delimiter string used for parsing/storing properties.

Returns

default delimiter

getDelimiterByNumber()

std::string getDelimiterByNumber

(

const int

index

)

const

Returns a specific delimiter used for the property.

Parameters

index

Index for which to get a delimiter

Returns

corresponding delimiter

getNumberOfProperties()

int getNumberOfProperties

(

)

const

Returns a total number of property/comment entries.

Returns

Number of property/comment entries

getPreceedingComments()

std::string getPreceedingComments

(

)

const

Returns any comments preceeding the section.

Sections in the mascot.dat file may have comments preceeding them. In most cases, these comments need to stay 'attached' to the section.

Multiple line comments are supported by having a single string with newline characters

See also

setPreceedingComments()

Returns

any comments preceeding the section

getPropertyName()

std::string getPropertyName

(

const int

index

)

const

Returns a property name for a given index.

Parameters

index

property number from 0 to (getNumberOfProperties()-1).

Returns

Rroperty name of an empty string for comments.

getPropValStringByName()

std::string getPropValStringByName

(

const char *

name

)

const

Retrieves property value by name.

Don't use this method for comments as they all have empty name. Also note that there might be several entries corresponding to the same name . – only the first value will be returned. If in doubt use findProperty() and getPropValStringByNumber() instead.

Parameters

name	Name for which to get a property value

Returns

corresponding property value

getPropValStringByNumber()

std::string getPropValStringByNumber

(

const int

index

)

const

Retrieves property raw text values by number.

Parameters

index

Index for which to get a property value

Returns

corresponding property value

setDefaultDelimiter()

void setDefaultDelimiter

(

const char *

delim

)

Allows to set a specific delimiter string to be used when no property-specific delimiter is supplied.

Parameters

delim

String to set the default delimiter

setPreceedingComments()

void setPreceedingComments

(

const std::string &

comments

)

Sets any comments preceeding the section.

Sections in the mascot.dat file may have comments preceeding them. In most cases, these comments need to stay 'attached' to the section.

Multiple line comments are supported by having a single string with newline characters

See also

getPreceedingComments()

Parameters

comments

any comments preceeding the section

setPropertyName()

void setPropertyName	(	const int	index,
		const char *	name
	)

Changes name of the property with the given index.

Parameters

index	property number from 0 to (getNumberOfProperties()-1).
name	new name to be given to the property.

setPropValBoolByName()

void setPropValBoolByName	(	const char *	name,
		const bool	value,
		const bool	bFirstPlace = false
	)

Changes a boolean value of the first entry with the given name or creates a new property if it is not found.

A new value will be converted into 1 (for TRUE) or 0 (for FALSE) character.

Parameters

name	a name of the property to find or add.
value	a new boolean value for the property.
bFirstPlace	if not found a new property can be put on top of the list.

setPropValCharByName()

void setPropValCharByName	(	const char *	name,
		const char	value,
		const bool	bFirstPlace = false
	)

Changes a single character value of the first entry with the given name or creates a new property if it is not found.

Parameters

name	a name of the property to find or add.
value	a new single character value for the property.
bFirstPlace	if not found a new property can be put on top of the list.

setPropValFloatByName()

void setPropValFloatByName	(	const char *	name,
		const double	value,
		const bool	bFirstPlace = false
	)

Changes an floating point value of the first entry with the given name or creates a new property if it is not found.

Parameters

name	a name of the property to find or add.
value	a new floating point value for the property.
bFirstPlace	if not found a new property can be put on top of the list.

setPropValInt64ByName()

void setPropValInt64ByName	(	const char *	name,
		const INT64	value,
		const bool	bFirstPlace = false
	)

Changes a long 64-bit integer value of the first entry with the given name or creates a new property if it is not found.

Parameters

name	a name of the property to find or add.
value	a new long 64-bit integer value for the property.
bFirstPlace	if not found a new property can be put on top of the list.

setPropValIntByName()

void setPropValIntByName	(	const char *	name,
		const int	value,
		const bool	bFirstPlace = false
	)

Changes an integer value of the first entry with the given name or creates a new property if it is not found.

Parameters

name	a name of the property to find or add.
value	a new integer value for the property.
bFirstPlace	if not found a new property can be put on top of the list.

setPropValStringByName()

void setPropValStringByName	(	const char *	name,
		const char *	value,
		const bool	bFirstPlace = false
	)

Changes a string value of the first entry with the given name or creates a new property if it is not found.

Parameters

name	a name of the property to find or add.
value	a new string value for the property.
bFirstPlace	if not found a new property can be put on top of the list.

setPropValStringByNumber()

void setPropValStringByNumber	(	const int	index,
		const char *	str
	)

Changes an string value of an existing property with the given index.

Parameters

index	an index of an existing property.
str	String value for the property.

uncommentProp()

bool uncommentProp	(	const int	index,
		const char *	delimeter = 0
	)

Uncomments a line in the configuration file.

Removes a # and any white space. Finds the delimeter and extracts the property name and value.

Parameters

index	must be a value between 0 and getNumberOfProperties().
delimeter	will often be a space. If not supplied, the default delimeter will be used.

Returns

true if the delimiter was found, false otherwise

---

The documentation for this class was generated from the following files:

• ms_customproperty.hpp
• ms_customproperty.cpp