#include <Properties.h>

Classes
struct	Property
Public Types
enum	Type { NONE, STRING, NUMBER, VECTOR2, VECTOR3, VECTOR4, MATRIX }
Public Member Functions
	~Properties ()
const char *	getNextProperty ()
Properties *	getNextNamespace ()
void	rewind ()
Properties *	getNamespace (const char *id, bool searchNames=false, bool recurse=true) const
const char *	getNamespace () const
const char *	getId () const
bool	exists (const char *name) const
Type	getType (const char *name=NULL) const
const char *	getString (const char name=NULL, const char defaultValue=NULL) const
bool	setString (const char name, const char value)
bool	getBool (const char *name=NULL, bool defaultValue=false) const
int	getInt (const char *name=NULL) const
float	getFloat (const char *name=NULL) const
long	getLong (const char *name=NULL) const
bool	getMatrix (const char name, Matrix out) const
bool	getVector2 (const char name, Vector2 out) const
bool	getVector3 (const char name, Vector3 out) const
bool	getVector4 (const char name, Vector4 out) const
bool	getQuaternionFromAxisAngle (const char name, Quaternion out) const
bool	getColor (const char name, Vector3 out) const
bool	getColor (const char name, Vector4 out) const
bool	getPath (const char name, std::string path) const
const char *	getVariable (const char name, const char defaultValue=NULL) const
void	setVariable (const char name, const char value)
Static Public Member Functions
static Properties *	create (const char *url)
static bool	parseVector2 (const char str, Vector2 out)
static bool	parseVector3 (const char str, Vector3 out)
static bool	parseVector4 (const char str, Vector4 out)
static bool	parseAxisAngle (const char str, Quaternion out)
static bool	parseColor (const char str, Vector3 out)
static bool	parseColor (const char str, Vector4 out)

Detailed Description

Defines a properties file for loading text files.

A properties file has very simple syntax and can contain only namespaces and name/value pairs (the properties of a namespace). The file can have any file extension a user specifies.

Here's an example of a simple file that uses all the available features of the markup language:

    // This is a comment.
 
    // This property is in the default namespace:
    integerProperty = 5
 
    // This line defines a namespace of type "mynamespace" without an ID:
    mynamespace
    {
        // This namespace can be retrieved by searching for its ID, "spriteTexture",
        // or by its name "texture":
        texture spriteTexture 
        {
            fileName = sprite.png
            width = 64
            height = 64
        }
 
        // This property is in the "space" namespace:
        booleanProperty = true
 
        // It's legal to have a name without a value if you leave out the '=' character:
        foo
 
        // In fact, the '=' character is optional if you'd rather write:
        bar 23
 
        // But don't write this or you'll get an error:
        // illegalProperty =
 
        // Or this:
        // = 15
 
        // Properties objects let you retrieve values as various types.
        floatProperty = 3.333
        stringProperty = This is a string.
        vector3Property = 1.0, 5.0, 3.55
        colorProperty = 1.0, 0.4, 0.0, 1.0
    }

Retrieving information out of a file like this could be done in two ways. If the available namespaces and name/value pairs are known in advance they can be queried by ID or name. For example, if the namespace "spriteTexture" and its properties are required then they can be retrieved with a call to getNamespace() followed by calls to getString() and getInt(). A namespace is stored and retrieved as a Properties object. Reading the spriteTexture properties out of the file above in this way could be done with the following code:

    // Create the top-level Properties object.
    Properties* properties = Properties::create("example.properties");
    // Retrieve the "spriteTexture" namespace.
    Properties* spriteTexture = properties->getNamespace("spriteTexture");
 
    // Get the values of known texture properties out of the namespace.
    const char* fileName = spriteTexture->getString("fileName");
    int width = spriteTexture->getInt("width");
    int height = spriteTexture->getInt("height");
 
    // Deleting the top-level Properties object will clean up all nested namespaces.
    SAFE_DELETE(properties);

On the other hand, if the structure of the file is not known in advance its namespaces and name/value pairs can be retrieved one by one using the getNextNamespace() and getNextProperty() methods. The following method prints the contents of any properties file to the console:

    void printProperties(Properties* properties)
    {
        // Print the name and ID of the current namespace.
        const char* spacename = properties->getNamespace();
        const char* id = properties->getId();
        GP_WARN("Namespace: %s  ID: %s\n{", spacename, id);
 
        // Print all properties in this namespace.
        const char* name = properties->getNextProperty();
        const char* value = NULL;
        while (name != NULL)
        {
            value = properties->getString(name);
            GP_WARN("%s = %s", name, value);
            name = properties->getNextProperty();
        }
        GP_WARN("}\n");
 
        // Print the properties of every namespace within this one.
        Properties* space = properties->getNextNamespace();
        while (space != NULL)
        {
            printProperties(space);
            space = properties->getNextNamespace();
        }
    }

Note that this method does not keep track of the namespace hierarchy, but could be modified to do so. Also note that nothing in a properties file indicates the type of a property. If the type is unknown, its string can be retrieved and interpreted as necessary.

Member Enumeration Documentation

enum gameplay::Properties::Type

Data types supported by the properties class.

Constructor & Destructor Documentation

gameplay::Properties::~Properties ( )

Destructor.

Member Function Documentation

static Properties* gameplay::Properties::create ( const char * url ) [static]

Creates a Properties runtime settings from the specified URL, where the URL is of the format "<file-path>.<extension>#<namespace-id>/<namespace-id>/.../<namespace-id>" (and "#<namespace-id>/<namespace-id>/.../<namespace-id>" is optional).

Parameters:

url	The URL to create the properties from.

Returns:: The created Properties or NULL if there was an error.

bool gameplay::Properties::exists ( const char * name ) const

Check if a property with the given name is specified in this Properties object.

Parameters:

name	The name of the property to query.

Returns:: True if the property exists, false otherwise.

bool gameplay::Properties::getBool	(	const char *	name = `NULL`,
		bool	defaultValue = `false`
	)		const

Interpret the value of the given property as a boolean.

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.
defaultValue	the default value to return if the specified property does not exist within the properties file.

Returns:: true if the property exists and its value is "true", otherwise false.

bool gameplay::Properties::getColor	(	const char *	name,
		Vector3 *	out
	)		const

Interpret the value of the given property as an RGB color in hex and write this color to a Vector3. E.g. 0xff0000 represents red and sets the vector to (1, 0, 0). If the property does not exist, out will be set to Vector3(0.0f, 0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector3(0.0f, 0.0f, 0.0f).

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.
out	The vector to set to this property's interpreted value.

Returns:: True on success, false if the property does not exist or could not be scanned.

bool gameplay::Properties::getColor	(	const char *	name,
		Vector4 *	out
	)		const

Interpret the value of the given property as an RGBA color in hex and write this color to a Vector4. E.g. 0xff0000ff represents opaque red and sets the vector to (1, 0, 0, 1). If the property does not exist, out will be set to Vector4(0.0f, 0.0f, 0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector4(0.0f, 0.0f, 0.0f, 0.0f).

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.
out	The vector to set to this property's interpreted value.

Returns:: True on success, false if the property does not exist or could not be scanned.

float gameplay::Properties::getFloat ( const char * name = NULL ) const

Interpret the value of the given property as a floating-point number. If the property does not exist, zero will be returned. If the property exists but could not be scanned, an error will be logged and zero will be returned.

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.

Returns:: The value of the given property interpreted as a float. Zero if the property does not exist or could not be scanned.

const char* gameplay::Properties::getId ( ) const

Get the ID of this Property's namespace. The ID should be a unique identifier, but its uniqueness is not enforced.

Returns:: The ID of this Property's namespace.

int gameplay::Properties::getInt ( const char * name = NULL ) const

Interpret the value of the given property as an integer. If the property does not exist, zero will be returned. If the property exists but could not be scanned, an error will be logged and zero will be returned.

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.

Returns:: The value of the given property interpreted as an integer. Zero if the property does not exist or could not be scanned.

long gameplay::Properties::getLong ( const char * name = NULL ) const

Interpret the value of the given property as a long integer. If the property does not exist, zero will be returned. If the property exists but could not be scanned, an error will be logged and zero will be returned.

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.

Returns:: The value of the given property interpreted as a long. Zero if the property does not exist or could not be scanned.

bool gameplay::Properties::getMatrix	(	const char *	name,
		Matrix *	out
	)		const

Interpret the value of the given property as a Matrix. If the property does not exist, out will be set to the identity matrix. If the property exists but could not be scanned, an error will be logged and out will be set to the identity matrix.

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.
out	The matrix to set to this property's interpreted value.

Returns:: True on success, false if the property does not exist or could not be scanned.

Properties* gameplay::Properties::getNamespace	(	const char *	id,
		bool	searchNames = `false`,
		bool	recurse = `true`
	)		const

Get a specific namespace by ID or name. This method will optionally perform a depth-first search on all namespaces and inner namespaces within this Property.

Parameters:

id	The ID or name of the namespace to find.
searchNames	If true, namespace names are used in the search, instead of namespace IDs. By default this parameter is false and namespace IDs are searched.
recurse	If true, perform a depth-first search, otherwise search only the immediate child namespaces.

Returns:: A properties object with the given ID or name.

const char* gameplay::Properties::getNamespace ( ) const

Get the name of this Property's namespace.

Returns:: The name of this Property's namespace.

Properties* gameplay::Properties::getNextNamespace ( )

Get the next namespace.

const char* gameplay::Properties::getNextProperty ( )

Get the name of the next property.

If a valid next property is returned, the value of the property can be retrieved using any of the get methods in this class, passing NULL for the property name.

Returns:: The name of the next property, or NULL if there are no properties remaining.

bool gameplay::Properties::getPath	(	const char *	name,
		std::string *	path
	)		const

Gets the file path for the given property if the file exists.

This method will first search for the file relative to the working directory. If the file is not found then it will search relative to the directory the bundle file is in.

Parameters:

name	The name of the property.
path	The string to copy the path to if the file exists.

Returns:: True if the property exists and the file exists, false otherwise.

bool gameplay::Properties::getQuaternionFromAxisAngle	(	const char *	name,
		Quaternion *	out
	)		const

Interpret the value of the given property as a Quaternion specified as an axis angle. If the property does not exist, out will be set to Quaternion(). If the property exists but could not be scanned, an error will be logged and out will be set to Quaternion().

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.
out	The quaternion to set to this property's interpreted value.

Returns:: True on success, false if the property does not exist or could not be scanned.

const char* gameplay::Properties::getString	(	const char *	name = `NULL`,
		const char *	defaultValue = `NULL`
	)		const

Get the value of the given property as a string. This can always be retrieved, whatever the intended type of the property.

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.
defaultValue	The default value to return if the specified property does not exist.

Returns:: The value of the given property as a string, or the empty string if no property with that name exists.

Type gameplay::Properties::getType ( const char * name = NULL ) const

Returns the type of a property.

Parameters:

name	The name of the property to interpret, or NULL to return the current property's type.

Returns:: The type of the property.

const char* gameplay::Properties::getVariable	(	const char *	name,
		const char *	defaultValue = `NULL`
	)		const

Returns the value of a variable that is set in this Properties object.

Variables take on the format ${name} and are inherited from parent Property objects.

Parameters:

name	Name of the variable to get.
defaultValue	Value to return if the variable is not found.

Returns:: The value of the specified variable, or defaultValue if not found.

bool gameplay::Properties::getVector2	(	const char *	name,
		Vector2 *	out
	)		const

Interpret the value of the given property as a Vector2. If the property does not exist, out will be set to Vector2(0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector2(0.0f, 0.0f).

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.
out	The vector to set to this property's interpreted value.

Returns:: True on success, false if the property does not exist or could not be scanned.

bool gameplay::Properties::getVector3	(	const char *	name,
		Vector3 *	out
	)		const

Interpret the value of the given property as a Vector3. If the property does not exist, out will be set to Vector3(0.0f, 0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector3(0.0f, 0.0f, 0.0f).

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.
out	The vector to set to this property's interpreted value.

Returns:: True on success, false if the property does not exist or could not be scanned.

bool gameplay::Properties::getVector4	(	const char *	name,
		Vector4 *	out
	)		const

Interpret the value of the given property as a Vector4. If the property does not exist, out will be set to Vector4(0.0f, 0.0f, 0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector4(0.0f, 0.0f, 0.0f, 0.0f).

Parameters:

name	The name of the property to interpret, or NULL to return the current property's value.
out	The vector to set to this property's interpreted value.

Returns:: True on success, false if the property does not exist or could not be scanned.

static bool gameplay::Properties::parseAxisAngle	(	const char *	str,
		Quaternion *	out
	)		`[static]`

Attempts to parse the specified string as an axis-angle value.

The specified string is expected to contain four comma-separated values, where the first three values represents the axis and the fourth value represents the angle, in degrees.

On error, false is returned and the output is set to all zero values.

Parameters:

str	The string to parse.
out	A Quaternion populated with the orientation of the axis-angle, if successful.

Returns:: True if a valid axis-angle was parsed, false otherwise.

static bool gameplay::Properties::parseColor	(	const char *	str,
		Vector3 *	out
	)		`[static]`

Atempts to parse the specified string as an RGB color value.

Parameters:

str	The string to parse.
out	The value to populate if successful.

Returns:: True if a valid RGB color was parsed, false otherwise.

static bool gameplay::Properties::parseColor	(	const char *	str,
		Vector4 *	out
	)		`[static]`

Atempts to parse the specified string as an RGBA color value.

Parameters:

str	The string to parse.
out	The value to populate if successful.

Returns:: True if a valid RGBA color was parsed, false otherwise.

static bool gameplay::Properties::parseVector2	(	const char *	str,
		Vector2 *	out
	)		`[static]`

Attempts to parse the specified string as a Vector2 value.

On error, false is returned and the output is set to all zero values.

Parameters:

str	The string to parse.
out	The value to populate if successful.

Returns:: True if a valid Vector2 was parsed, false otherwise.

static bool gameplay::Properties::parseVector3	(	const char *	str,
		Vector3 *	out
	)		`[static]`

Attempts to parse the specified string as a Vector3 value.

On error, false is returned and the output is set to all zero values.

Parameters:

str	The string to parse.
out	The value to populate if successful.

Returns:: True if a valid Vector3 was parsed, false otherwise.

static bool gameplay::Properties::parseVector4	(	const char *	str,
		Vector4 *	out
	)		`[static]`

Attempts to parse the specified string as a Vector4 value.

On error, false is returned and the output is set to all zero values.

Parameters:

str	The string to parse.
out	The value to populate if successful.

Returns:: True if a valid Vector4 was parsed, false otherwise.

void gameplay::Properties::rewind ( )

Rewind the getNextProperty() and getNextNamespace() iterators to the beginning of the file.

bool gameplay::Properties::setString	(	const char *	name,
		const char *	value
	)

Sets the value of the property with the specified name.

If there is no property in this namespace with the current name, one is added. Otherwise, the value of the first property with the specified name is updated.

If name is NULL, the value current property (see getNextProperty) is set, unless there is no current property, in which case false is returned.

Parameters:

name	The name of the property to set.
value	The property value.

Returns:: True if the property was set, false otherwise.

void gameplay::Properties::setVariable	(	const char *	name,
		const char *	value
	)

Sets the value of the specified variable.

Parameters:

name	Name of the variable to set.
value	The value to set.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation