Matrix Science header
Public Member Functions

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:
Inheritance graph
[legend]

List of all members.

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:

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:

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

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

Adds a new property with the given parameters.

Parameters:
namea property name to use.
valuea property value to use.
delimitera specific delimiter or an empty string for a default one to be used.
bFirstPlaceforces a new property to be put on top of the list.
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:
lraw text representation of the property to be parsed.
bFirstPlaceforces a new property to be put on top of the list.
void delProp ( const char *  str )

Deletes all properties with the specified name.

Parameters:
strProperty name to find a match and then delete.
void delPropStart ( const char *  str )

Deletes all properties whose names start with the given string.

Parameters:
strBeginning a first part of the property name to delete.
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:
namea property name to be found.
startFroma minimal property index to start search from.
Returns:
a property index or -1 if no property found.
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:
nameBeginningfirst part of a property name to be found.
startFroma minimal property index to start search from.
Returns:
a property index or -1 if no property found.
std::string getDefaultDelimiter (  ) const

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

Returns:
default delimiter
std::string getDelimiterByNumber ( const int  index ) const

Returns a specific delimiter used for the property.

Parameters:
indexIndex for which to get a delimiter
Returns:
corresponding delimiter
int getNumberOfProperties (  ) const

Returns a total number of property/comment entries.

Returns:
Number of property/comment entries
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
std::string getPropertyName ( const int  index ) const

Returns a property name for a given index.

Parameters:
indexproperty number from 0 to (getNumberOfProperties()-1).
Returns:
Rroperty name of an empty string for comments.
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:
nameName for which to get a property value
Returns:
corresponding property value
std::string getPropValStringByNumber ( const int  index ) const

Retrieves property raw text values by number.

Parameters:
indexIndex for which to get a property value
Returns:
corresponding property value
void setDefaultDelimiter ( const char *  delim )

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

Parameters:
delimString to set the default delimiter
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:
commentsany comments preceeding the section
void setPropertyName ( const int  index,
const char *  name 
)

Changes name of the property with the given index.

Parameters:
indexproperty number from 0 to (getNumberOfProperties()-1).
namenew name to be given to the property.
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:
namea name of the property to find or add.
valuea new boolean value for the property.
bFirstPlaceif not found a new property can be put on top of the list.
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:
namea name of the property to find or add.
valuea new single character value for the property.
bFirstPlaceif not found a new property can be put on top of the list.
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:
namea name of the property to find or add.
valuea new floating point value for the property.
bFirstPlaceif not found a new property can be put on top of the list.
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:
namea name of the property to find or add.
valuea new long 64-bit integer value for the property.
bFirstPlaceif not found a new property can be put on top of the list.
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:
namea name of the property to find or add.
valuea new integer value for the property.
bFirstPlaceif not found a new property can be put on top of the list.
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:
namea name of the property to find or add.
valuea new string value for the property.
bFirstPlaceif not found a new property can be put on top of the list.
void setPropValStringByNumber ( const int  index,
const char *  str 
)

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

Parameters:
indexan index of an existing property.
strString value for the property.
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:
indexmust be a value between 0 and getNumberOfProperties().
delimeterwill 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:

Copyright © 2022 Matrix Science Ltd.  All Rights Reserved. Generated on Thu Mar 31 2022 01:12:31