Defines a properties file for loading text files. More...

#include <Properties.h>

Public Types
enum	Type
	Data types supported by the properties class.

Public Member Functions
	~Properties ()
	Destructor.

const char *	getNextProperty ()

Properties *	getNextNamespace ()
	Get the next namespace.

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

Properties *	getNamespace (std::string_view id, bool searchNames=false, bool recurse=true) const
	Get a specific namespace by ID or name.

const char *	getNamespace () const
	Get the name of this Property's namespace.

std::string_view	getId () const
	Get the ID of this Property's namespace.

bool	exists (const char *name) const
	Check if a property with the given name is specified in this Properties object.

Type	getType (const char *name=NULL) const
	Returns the type of a property.

const char *	getString (const char name=NULL, const char defaultValue=NULL) const
	Get the value of the given property as a string.

bool	setString (const char name, const char value)
	Sets the value of the property with the specified name.

bool	getBool (const char *name=NULL, bool defaultValue=false) const
	Interpret the value of the given property as a boolean.

int	getInt (const char *name=NULL) const
	Interpret the value of the given property as an integer.

float	getFloat (const char *name=NULL) const
	Interpret the value of the given property as a floating-point number.

bool	getMat4 (const char name, Mat4 out) const
	Interpret the value of the given property as a Matrix.

bool	getVec2 (const char name, Vec2 out) const
	Interpret the value of the given property as a Vector2.

bool	getVec3 (const char name, Vec3 out) const
	Interpret the value of the given property as a Vector3.

bool	getVec4 (const char name, Vec4 out) const
	Interpret the value of the given property as a Vector4.

bool	getQuaternionFromAxisAngle (const char name, Quaternion out) const
	Interpret the value of the given property as a Quaternion specified as an axis angle.

bool	getColor (const char name, Vec3 out) const
	Interpret the value of the given property as an RGB color in hex and write this color to a Vector3.

bool	getColor (const char name, Vec4 out) const
	Interpret the value of the given property as an RGBA color in hex and write this color to a Vector4.

bool	getPath (const char name, std::string path) const
	Gets the file path for the given property if the file exists.

const char *	getVariable (const char name, const char defaultValue=NULL) const
	Returns the value of a variable that is set in this Properties object.

void	setVariable (const char name, const char value)
	Sets the value of the specified variable.

Static Public Member Functions
static Properties *	createNonRefCounted (std::string_view url)
	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).

static bool	parseVec2 (const char str, Vec2 out)
	Attempts to parse the specified string as a Vector2 value.

static bool	parseVec3 (const char str, Vec3 out)
	Attempts to parse the specified string as a Vector3 value.

static bool	parseVec4 (const char str, Vec4 out)
	Attempts to parse the specified string as a Vector4 value.

static bool	parseAxisAngle (const char str, Quaternion out)
	Attempts to parse the specified string as an axis-angle value.

static bool	parseColor (const char str, Vec3 out)
	Attempts to parse the specified string as an RGB color value.

static bool	parseColor (const char str, Vec4 out)
	Attempts to parse the specified string as an RGBA color value.

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::createNonRefCounted("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 Function Documentation

◆ createNonRefCounted()

static Properties * createNonRefCounted ( std::string_view 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. @script{create}

◆ getNextProperty()

const char * 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.

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

◆ getNamespace() [1/2]

Properties * getNamespace	(	std::string_view	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.

◆ getNamespace() [2/2]

const char * getNamespace ( ) const

Get the name of this Property's namespace.

Returns: The name of this Property's namespace.

◆ getId()

std::string_view 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.

◆ exists()

bool 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.

◆ getType()

Type 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.

◆ getString()

const char * 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.

◆ setString()

bool 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.

◆ getBool()

bool 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.

◆ getInt()

int 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.

◆ getFloat()

float 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.

◆ getMat4()

bool getMat4	(	const char *	name,
		Mat4 *	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.

◆ getVec2()

bool getVec2	(	const char *	name,
		Vec2 *	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.

◆ getVec3()

bool getVec3	(	const char *	name,
		Vec3 *	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.

◆ getVec4()

bool getVec4	(	const char *	name,
		Vec4 *	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.

◆ getQuaternionFromAxisAngle()

bool 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.

◆ getColor() [1/2]

bool getColor	(	const char *	name,
		Vec3 *	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.

◆ getColor() [2/2]

bool getColor	(	const char *	name,
		Vec4 *	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.

◆ getPath()

bool 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.

@script{ignore}

◆ getVariable()

const char * 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.

◆ setVariable()

void 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.

◆ parseVec2()

static bool parseVec2	(	const char *	str,
		Vec2 *	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.

◆ parseVec3()

static bool parseVec3	(	const char *	str,
		Vec3 *	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.

◆ parseVec4()

static bool parseVec4	(	const char *	str,
		Vec4 *	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.

◆ parseAxisAngle()

static bool 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.

◆ parseColor() [1/2]

static bool parseColor	(	const char *	str,
		Vec3 *	out )

static

Attempts 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.

◆ parseColor() [2/2]

static bool parseColor	(	const char *	str,
		Vec4 *	out )

static

Attempts 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.

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

Properties.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ createNonRefCounted()

◆ getNextProperty()

◆ getNamespace() [1/2]

◆ getNamespace() [2/2]

◆ getId()

◆ exists()

◆ getType()

◆ getString()

◆ setString()

◆ getBool()

◆ getInt()

◆ getFloat()

◆ getMat4()

◆ getVec2()

◆ getVec3()

◆ getVec4()

◆ getQuaternionFromAxisAngle()

◆ getColor() [1/2]

◆ getColor() [2/2]

◆ getPath()

◆ getVariable()

◆ setVariable()

◆ parseVec2()

◆ parseVec3()

◆ parseVec4()

◆ parseAxisAngle()

◆ parseColor() [1/2]

◆ parseColor() [2/2]