Class represents a set of properties. More...

#include <Properties.h>

Public Member Functions
void	clear (void)
	Clear the children.
bool	createNode (const std::string &key)
	Create newly node of Properties.
Properties *const	findNode (const std::string &key) const
	Get node of properties.
const std::string &	getDefault (const std::string &key) const
	Get the default values with specified key.
const char *	getDefaultValue (void) const
	Get default values.
const std::vector< Properties * > &	getLeaf (void) const
	Get elements of leaf.
const char *	getName (void) const
	Get Names.
Properties &	getNode (const std::string &key)
	Get node of properties.
const std::string &	getProperty (const std::string &key) const
	Search for the property with the specified key in this property.
const std::string &	getProperty (const std::string &key, const std::string &def) const
	Search for the property with the specified key in property list.
const Properties *	getRoot (void) const
	Get root element.
const char *	getValue (void) const
	Get values.
Properties *	hasKey (const char *key) const
	Check whether key exists in the children.
void	list (std::ostream &out)
	Prints this property list out to the specified output stream.
void	load (std::istream &inStream)
	Loads property list that consists of key:value from input stream.
Properties &	operator<< (const Properties &prop)
	Merge properties.
Properties &	operator= (const Properties &prop)
	Assignment operator.
const std::string &	operator[] (const std::string &key) const
	Search for the property with the specified key in property list.
std::string &	operator[] (const std::string &key)
	Search for the property with the specified key in property list.
	Properties (const char key="", const char value="")
	Constructor(Create only root node)
	Properties (std::map< std::string, std::string > &defaults)
	Constructor(Give the default value with map)
	Properties (const char *defaults[], long num=LONG_MAX)
	Constructor(Give the default value with char*[])
	Properties (const Properties &prop)
	Copy Constructor.
std::vector< std::string >	propertyNames (void) const
	Return an vector of all the keys in this property.
Properties *	removeNode (const char *leaf_name)
	Remove node of Properties.
void	save (std::ostream &out, const std::string &header)
	Save the property list to the specified stream.
std::string	setDefault (const std::string &key, const std::string &value)
	Set a default value associated with key in the property list.
void	setDefaults (const char *defaults[], long num=LONG_MAX)
	Set a default value together in the property list.
std::string	setProperty (const std::string &key, const std::string &value)
	Set a value associated with key in the property list.
int	size (void) const
	Get the number of Properties.
void	store (std::ostream &out, const std::string &header)
	Stores property list to the output stream.
virtual	~Properties (void)
	Destructor.
Static Protected Member Functions
static std::ostream &	_dump (std::ostream &out, const Properties &curr, int index)
	Save property's contents.
static Properties *	_getNode (std::vector< std::string > &keys, std::vector< Properties * >::size_type index, const Properties *curr)
	Get properties.
static void	_propertiyNames (std::vector< std::string > &names, std::string curr_name, const Properties *curr)
	Get property name list.
static void	_store (std::ostream &out, std::string curr_name, Properties *curr)
	Store the property name list.
static std::string	indent (int index)
	Create indents.
static bool	split (const std::string &str, const char delim, std::vector< std::string > &value)
	Split the string.
static void	splitKeyValue (const std::string &str, std::string &key, std::string &value)
	Split the string into a pair of the key and the value.
Private Attributes
std::string	default_value
std::vector< Properties * >	leaf
const std::string	m_empty
std::string	name
Properties *	root
std::string	value
Friends
std::ostream &	operator<< (std::ostream &lhs, const Properties &rhs)
	Output Properties to stream.

Detailed Description

Class represents a set of properties.

The Properties class represents a persistent set of properties. The Properties can be saved to a stream or loaded from a stream. Each key and its corresponding value in the property list is a string.

A property list can contain another property list as its "defaults". This second property list is searched if the property key is not found in the original property list.

It is recommended to use these method; setProperty() to get properties, setProperty() to set properties.

When propertis are stored in a stream or when they are loaded from the stream, the ISO 8859-1 character encoding is used. Characters that cannot be directly represented in this encoding can be used.

This class has almost same methods of Java's Properties class (java.util.Properties). Also, input and output files are compatible with outputs of Java's Properties class, but Unicode encoded property file is not be supported.

Definition at line 101 of file Properties.h.

Constructor & Destructor Documentation

coil::Properties::Properties	(	const char *	key = `""`,
		const char *	value = `""`
	)

Constructor(Create only root node)

Create a root node of Property with root's key and value. All values are set as default value.

Parameters:

key	Properties's keys(The default values:"")
value	Properties's values(The default values:"")

Definition at line 33 of file Properties.cpp.

coil::Properties::Properties ( std::map< std::string, std::string > & defaults )

Constructor(Give the default value with map)

Create Properties with default value of std::string map. All values are set as default value.

Parameters:

defaults map that is spcified as the default value

Definition at line 46 of file Properties.cpp.

coil::Properties::Properties	(	const char *	defaults[],
		long	num = `LONG_MAX`
	)

Constructor(Give the default value with char*[])

Creates an empty property list with the specified defaults. All values are set as the default values. The default values are given by array of char*, which should be pairs of "key" and "value". The end of list is specified by argument "num" which specifies number of array, or null character of key. The following is an example.

 const char* defaults = {
     "key1", "value1",
     "key2", "value2",
     "key3", "value3",
     "key4", "value4",
     "key5", "value5",
     "" };
 Properties p(defaults);
 // or
 Properties p(defaults, 10);

Parameters:

defaults	Array that specifies the default values
num	Number of elements that specifies the default value (The default value:LONG_MAX)

Definition at line 67 of file Properties.cpp.

coil::Properties::Properties ( const Properties & prop )

Copy Constructor.

All of given Properties's keys, values and default values are copied to new Properties.

Definition at line 81 of file Properties.cpp.

coil::Properties::~Properties ( void ) [virtual]

Destructor.

Definition at line 134 of file Properties.cpp.

Member Function Documentation

std::ostream & coil::Properties::_dump	(	std::ostream &	out,
		const Properties &	curr,
		int	index
	)		`[static, protected]`

Save property's contents.

Save the contents that were set to the property. The figure represented the depth of the property hierarchy is added when saving. If property with the value that is not set, the default value will be output.

Parameters:

out	Output stream of property's contents of save destination.
curr	Target property
index	Current property hierarchy

Definition at line 748 of file Properties.cpp.

Properties * coil::Properties::_getNode	(	std::vector< std::string > &	keys,
		std::vector< Properties * >::size_type	index,
		const Properties *	curr
	)		`[static, protected]`

Get properties.

Get properties specified by key list. In the key list, hierarchical relation in the properties is represented by a list format. If properties corresponding to specified key list do not exist, null will be returned.

Parameters:

keys	Target properties's key list representation for getting
index	Number of hierarchy of key list
curr	Target properties for the search

Returns:: Target properties for the search

Definition at line 651 of file Properties.cpp.

void coil::Properties::_propertiyNames	(	std::vector< std::string > &	names,
		std::string	curr_name,
		const Properties *	curr
	)		`[static, protected]`

Get property name list.

Get a property name list.

Get a list expressed by separating each property name with '.'.

Parameters:

names	Name list of property
curr_name	Current property's name
curr	Target properties

Definition at line 681 of file Properties.cpp.

void coil::Properties::_store	(	std::ostream &	out,
		std::string	curr_name,
		Properties *	curr
	)		`[static, protected]`

Store the property name list.

Store a list expressed by separating each property name with '.'.

Parameters:

out	Output stream of property's name list of save destination.
curr_name	Current property's name
curr	Target properties

Definition at line 710 of file Properties.cpp.

void coil::Properties::clear ( void )

Clear the children.

Definition at line 534 of file Properties.cpp.

bool coil::Properties::createNode ( const std::string & key )

Create newly node of Properties.

Create nowly node with specified key. If the node with the same key has been registered, error will be returned.

Parameters:

key	Newly node key

Returns:: Newly node creation result. false will be returned if the node with specified key has already existed.

Definition at line 474 of file Properties.cpp.

Properties *const coil::Properties::findNode ( const std::string & key ) const

Get node of properties.

Find node of properties.

Get node with specified key.

Parameters:

key	Target node key for getting

Returns:: Target node

Definition at line 439 of file Properties.cpp.

const std::string & coil::Properties::getDefault ( const std::string & key ) const

Get the default values with specified key.

Get the default value with specified key.

Return the default values with specified key. If the property with specified key does not exist, the method returns empty string.

Parameters:

key	The property key

Returns:: The value in this property list with the specified key value.

Definition at line 217 of file Properties.cpp.

const char* coil::Properties::getDefaultValue ( void ) const [inline]

Get default values.

Get Properties's default values.

Returns:: Properties's default values

Definition at line 321 of file Properties.h.

const std::vector<Properties*>& coil::Properties::getLeaf ( void ) const [inline]

Get elements of leaf.

Get Properties's elements of leaf.

Returns:: Elements of leaf

Definition at line 340 of file Properties.h.

const char* coil::Properties::getName ( void ) const [inline]

Get Names.

Get Properties's names.

Returns:: Properties's names

Definition at line 283 of file Properties.h.

Properties & coil::Properties::getNode ( const std::string & key )

Get node of properties.

Get node with specified key.

Parameters:

key	Target node key for getting

Returns:: Target node

Definition at line 455 of file Properties.cpp.

const std::string & coil::Properties::getProperty ( const std::string & key ) const

Search for the property with the specified key in this property.

Search for the property with the specified key in the property list.

Search for the property with the specified key in this property list. If the key is not found in this property list, the default property list, and its defaults, recursively, are then checked. The method returns null if the property is not found.

Parameters:

key	The property key.

Returns:: The value in this property list with the specified key value.

Definition at line 156 of file Properties.cpp.

const std::string & coil::Properties::getProperty	(	const std::string &	key,
		const std::string &	def
	)		const

Search for the property with the specified key in property list.

Search for the property with the specified key in the property list.

Search for the property with the specified key in this property list. The method returns the default value argument if the property is not found.

Parameters:

key	The property key
def	The default value.

Returns:: The value in this property list with the specified key value.

Definition at line 175 of file Properties.cpp.

const Properties* coil::Properties::getRoot ( void ) const [inline]

Get root element.

Get Properties's root element.

Returns:: Root element

Definition at line 359 of file Properties.h.

const char* coil::Properties::getValue ( void ) const [inline]

Get values.

Get Properties's values.

Returns:: Properties's values

Definition at line 302 of file Properties.h.

Properties * coil::Properties::hasKey ( const char * key ) const

Check whether key exists in the children.

Check whether the children with specified key exist. If the children exist, they will be returned.

Parameters:

key Check key

Returns:: Children node

Definition at line 517 of file Properties.cpp.

std::string coil::Properties::indent ( int index ) [static, protected]

Create indents.

Return indents according to specified figure. Returned indents are specified figure x two blanks.

Parameters:

index The specification of Number of indent

Returns:: Created indent

Definition at line 778 of file Properties.cpp.

void coil::Properties::list ( std::ostream & out )

Prints this property list out to the specified output stream.

Print this property list out to the specified output stream.

Prints this property list out to the specified output stream. This method is useful for debugging.

Parameters:

out	Output stream.

Definition at line 322 of file Properties.cpp.

void coil::Properties::load ( std::istream & inStream )

Loads property list that consists of key:value from input stream.

Load property list that consists of key:value from input stream.

Reads a property list (key and element pairs) from the input stream. The stream is assumed to be using the ISO 8859-1 character encoding. Each property is assumed to be registered in the input stream by each line, and each line terminator is should be a line break characters (\n or \r or \r\n). Lines are read from the input stream until end of file is reached.

A line that contains only white space characters or a line that its first non-white space character is an ASCII '#' or '!' is ignored. In a word, '#' or '!' represents comment lines.

All lines except the blank line or comment line is described the property that added to the table. However, if the line terminator is '\' and the next line continues, it is treated as a continuation line (See below). The key is composed of all characters. All of these key termination characters in the line starting with the first non-white space character and up to, but not including, the first unescaped '=', ':', or white space character other than a line terminator.

Line terminator characters can be included using \ escape sequences. Any white space after the key is skipped. If the first non-white space character after the key is '=' or ':', then it is ignored and any white space characters after it are also skipped. All remaining characters on the line become part of the associated element string. In element string, ASCII escape sequence such as \t and \n and \r and \\ and \" and \' and \ (backslash character and space) and \uxxxx have affect and they will be converted into a single character. Also, if termination character in the line is \, the next line will be treated as continuing. In that case, \ and break character will be destroyed, and also its first space character will be destroyed, so these characters on the line will not become part of the element string.

As an example, each of the following three lines specifies the key "Truth" and the associated element value "Beauty":

Truth = Beauty
Truth:Beauty
Truth\t\t\t:Beauty

As another example, the following three lines specify a single property:

fruits\t\t\t\tapple, banana, pear, \
cantaloupe, watermelon, \
kiwi, mango
The key is "fruits" and the associated element is: "apple, banana, pear, cantaloupe, watermelon, kiwi, mango". Note that a space appears before each \ so that a space will each comma in the final result; the \, line terminator, and leading white space on the continuation line are merely discarded and are not replaced by one or more other characters. As a third example, the line:

cheeses
specifies that the key is "cheeses" and the associated element is the empty string "".

Parameters:

inStream the input stream.

Definition at line 334 of file Properties.cpp.

Properties & coil::Properties::operator<< ( const Properties & prop )

Merge properties.

Merge properties that have set to the current properties.

Parameters:

prop	Properties for the merge

Returns:: Property merge result

Definition at line 550 of file Properties.cpp.

Properties & coil::Properties::operator= ( const Properties & prop )

Assignment operator.

All Properties's keys, values and default values of left side are deleted, all Properties's keys, values and default values of right side are copied to new Properties.

Definition at line 105 of file Properties.cpp.

const std::string & coil::Properties::operator[] ( const std::string & key ) const

Search for the property with the specified key in property list.

Search for the property with the specified key in the property list.

Search for the property with the specified key in this property list. If the key is not found in this property list, the default property list, and its defaults, recursively, are then checked. The method returns empty string if the property is not found.

Parameters:

key	The property key

Returns:: The value in this property list with the specified key value.

Definition at line 190 of file Properties.cpp.

std::string & coil::Properties::operator[] ( const std::string & key )

Search for the property with the specified key in property list.

Search for the property with the specified key in the property list.

Search for the property with the specified key in this property list. If the key is not found in this property list, the default property list, and its defaults, recursively, are then checked. The method returns empty string if the property is not found. If there is no element with the same value in the left value, insert the right value in corresponding property.

Parameters:

key	The property key

Returns:: The value in this property list with the specified key value.

Definition at line 202 of file Properties.cpp.

std::vector< std::string > coil::Properties::propertyNames ( void ) const

Return an vector of all the keys in this property.

Returns an enumeration of all the keys in this property list, including distinct keys in the default property list if a key of the same name has not already been found from the main properties list.

Returns:: A vector of all the keys in this property list, including the keys in the default property list.

Definition at line 410 of file Properties.cpp.

Properties * coil::Properties::removeNode ( const char * leaf_name )

Remove node of Properties.

Remove node of properties.

Remove properties with specified name. Properties that were deleted will be returned.

Parameters:

leaf_name Target property's name for the delete

Returns:: Deleted properties

Definition at line 493 of file Properties.cpp.

void coil::Properties::save	(	std::ostream &	out,
		const std::string &	header
	)

Save the property list to the specified stream.

It is not recommended. To save the property list, the store(ostream out, string header) method is recommended. This method is defined for compatibility of Java Properties.

Parameters:

out	The output stream
header	A description of the property list

Definition at line 381 of file Properties.cpp.

std::string coil::Properties::setDefault	(	const std::string &	key,
		const std::string &	value
	)

Set a default value associated with key in the property list.

Set the default value associated with key in the property list.

Set the default value to element specified by "key".

Parameters:

key	Property's key to set the default value
value	The default value that is set

Returns:: The specified default value

Definition at line 266 of file Properties.cpp.

void coil::Properties::setDefaults	(	const char *	defaults[],
		long	num = `LONG_MAX`
	)

Set a default value together in the property list.

Set the default value to the element specified by array together in the property list. The default values are given by array of char*, which should be pairs of "key" and "value". The end of list is specified by argument "num", which specifies number of array or null character of key.

Parameters:

defaults	Array that specifies the default values
num	Number of elements that specifies the default value (Default value:LONG_MAX)

Definition at line 295 of file Properties.cpp.

std::string coil::Properties::setProperty	(	const std::string &	key,
		const std::string &	value
	)

Set a value associated with key in the property list.

Set the value associated with key in the property list.

This method sets the "value" associated with "key" in the property list. If the property list has a value of "key", old value is returned.

Parameters:

key	The key to be placed into this property list.
value	The value corresponding to key.

Returns:: The previous value of the specified key in this property list, or null if it did not have one.

Definition at line 236 of file Properties.cpp.

int coil::Properties::size ( void ) const

Get the number of Properties.

Get the number of properties.

Get the number of Properties that has already set.

Returns:: Number of Properties

Definition at line 427 of file Properties.cpp.

bool coil::Properties::split	(	const std::string &	str,
		const char	delim,
		std::vector< std::string > &	value
	)		`[static, protected]`

Split the string.

Divide given string with given delimiter. If the given string is empty, error will be returned. When the given delimiter is escaped ('\' is set right before it) this method does not use as delimiter.

Parameters:

str	Target string for the division
delim	Delimiter
value	Division result list

Returns:: Division result

Definition at line 621 of file Properties.cpp.

void coil::Properties::splitKeyValue	(	const std::string &	str,
		std::string &	key,
		std::string &	value
	)		`[static, protected]`

Split the string into a pair of the key and the value.

Split the given string into a pair of the key and the value with the set delimiter. First, search whether the fist given string includes ':' or '=', and if either character is included, it is used as delimiter. If neither is included, try to divide it with ' '(space). When all delimiter candidates are not included, set the given string as key then set empty string to the its value. If any delimiter candidate is escaped ('\' is set right before it), this method does not use as delimiter.

Parameters:

str	Target string for the division
key	Division result key
value	Division result value

Definition at line 571 of file Properties.cpp.

void coil::Properties::store	(	std::ostream &	out,
		const std::string &	header
	)

Stores property list to the output stream.

Store the property list to the output stream.

Write this property list (key and element pairs) in this Properties table to the output stream in a format suitable for loading into a Properties table using the load method. The stream is written using the ISO 8859-1 character encoding. Properties from the defaults table of this Properties table (if any) are not written out by this method.

If the header argument is not null, then an ASCII # character, the comments string, and a line separator are first written to the output stream. Thus, the header can serve as an identifying comment.

Next, a comment line is always written, consisting of an ASCII # character, the current date and time (as if produced by the toString method of Date for the current time), and a line separator as generated by the Writer.

Then every entry in this Properties table is written out, one per line. For each entry the key string is written, then an ASCII =, then the associated element string. Each character of the key and element strings is examined to see whether it should be rendered as an escape sequence. The ASCII characters \, tab, form feed, newline, and carriage return are written as \\, \t, \f \n, and \r, respectively. Characters less than \u0020 and characters greater than \u007E are written as \uxxxx for the appropriate hexadecimal value xxxx. For the key, all space characters are written with a preceding \ character. For the element, leading space characters, but not embedded or trailing space characters, are written with a preceding \ character. The key and element characters #, !, =, and : are written with a preceding backslash to ensure that they are properly loaded.

After the entries have been written, the output stream is flushed. The output stream remains open after this method returns.

Parameters:

out	An output stream.
header	The description of the property list.

Definition at line 394 of file Properties.cpp.

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	lhs,
		const Properties &	rhs
	)		`[friend]`

Output Properties to stream.

Parameters:

lhs	Output stream
rhs	Properties

Returns:: Output stream

Definition at line 812 of file Properties.cpp.

Member Data Documentation

std::string coil::Properties::default_value [private]

Definition at line 1285 of file Properties.h.

std::vector<Properties*> coil::Properties::leaf [private]

Definition at line 1287 of file Properties.h.

const std::string coil::Properties::m_empty [private]

Definition at line 1288 of file Properties.h.

std::string coil::Properties::name [private]

Definition at line 1283 of file Properties.h.

Properties* coil::Properties::root [private]

Definition at line 1286 of file Properties.h.

std::string coil::Properties::value [private]

Definition at line 1284 of file Properties.h.

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

Public Member Functions

Static Protected Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation