A class for storing options and configuration information. More...

#include <yarp/os/Property.h>

Inheritance diagram for yarp::os::Property:

Classes
class	Private

Public Member Functions
	Property ()
	Constructor. More...

	Property (int hash_size)
	Constructor. More...

	Property (const char *str)
	Initialize from a string, using fromString(). More...

	Property (const Property &rhs)
	Copy constructor. More...

	Property (Property &&rhs) noexcept
	Move constructor. More...

	Property (std::initializer_list< std::pair< std::string, yarp::os::Value >> values)
	Initializer list constructor. More...

	~Property () override
	Destructor. More...

Property &	operator= (const Property &prop)
	Copy assignment operator. More...

Property &	operator= (Property &&prop) noexcept
	Move assignment operator. More...

bool	check (const std::string &key) const override
	Check if there exists a property of the given name. More...

void	put (const std::string &key, const std::string &value)
	Associate the given `key` with the given string. More...

void	put (const std::string &key, const Value &value)
	Associate the given `key` with the given value. More...

void	put (const std::string &key, Value *value)
	Associate the given `key` with the given value. More...

void	put (const std::string &key, int value)
	Associate the given `key` with the given integer. More...

void	put (const std::string &key, double value)
	Associate the given `key` with the given floating point number. More...

Property &	addGroup (const std::string &key)
	Add a nested group. More...

void	unput (const std::string &key)
	Remove the association from the given `key` to a value, if present. More...

Value &	find (const std::string &key) const override
	Gets a value corresponding to a given keyword. More...

Bottle &	findGroup (const std::string &key) const override
	Gets a list corresponding to a given keyword. More...

void	clear ()
	Remove all associations. More...

void	fromString (const std::string &txt, bool wipe=true)
	Interprets a string as a list of properties. More...

void	fromCommand (int argc, char *argv[], bool skipFirst=true, bool wipe=true)
	Interprets a list of command arguments as a list of properties. More...

void	fromCommand (int argc, const char *argv[], bool skipFirst=true, bool wipe=true)
	Interprets a list of command arguments as a list of properties. More...

void	fromArguments (const char *arguments, bool wipe=true)
	Interprets a list of command arguments as a list of properties. More...

bool	fromConfigFile (const std::string &fname, bool wipe=true)
	Interprets a file as a list of properties. More...

bool	fromConfigFile (const std::string &fname, Searchable &env, bool wipe=true)
	Variant of fromConfigFile(fname, wipe) that includes extra "environment variables". More...

bool	fromConfigDir (const std::string &dirname, const std::string &section=std::string(), bool wipe=true)
	Interprets all files in a directory as lists of properties as described in fromConfigFile(). More...

void	fromConfig (const char *txt, bool wipe=true)
	Parses text in the configuration format described in fromConfigFile(). More...

void	fromConfig (const char *txt, Searchable &env, bool wipe=true)
	Variant of fromConfig(const char*, bool) that includes extra "environment variables". More...

void	fromQuery (const char *url, bool wipe=true)
	Parses text in a url. More...

std::string	toString () const override
	Return a standard text representation of the content of the object. More...

bool	read (ConnectionReader &reader) override
	Read this object from a network connection. More...

bool	write (ConnectionWriter &writer) const override
	Write this object to a network connection. More...

virtual bool	check (const std::string &key) const=0
	Check if there exists a property of the given name. More...

virtual bool	check (const std::string &key, const std::string &comment) const
	Check if there exists a property of the given name. More...

virtual bool	check (const std::string &key, Value *&result, const std::string &comment="") const
	Gets a value corresponding to a given keyword. More...

virtual Value	check (const std::string &key, const Value &fallback, const std::string &comment="") const
	Gets a value corresponding to a given keyword. More...

virtual Bottle &	findGroup (const std::string &key) const=0
	Gets a list corresponding to a given keyword. More...

Bottle &	findGroup (const std::string &key, const std::string &comment) const
	Gets a list corresponding to a given keyword. More...

Public Member Functions inherited from yarp::os::Searchable
	Searchable ()
	Default constructor. More...

	Searchable (const Searchable &rhs)=default
	Copy constructor. More...

	Searchable (Searchable &&rhs) noexcept=default
	Move constructor. More...

virtual	~Searchable ()
	Destructor. More...

Searchable &	operator= (const Searchable &rhs)=default
	Copy assignment operator. More...

Searchable &	operator= (Searchable &&rhs) noexcept=default
	Move assignment operator. More...

virtual bool	check (const std::string &key, const std::string &comment) const
	Check if there exists a property of the given name. More...

Bottle &	findGroup (const std::string &key, const std::string &comment) const
	Gets a list corresponding to a given keyword. More...

virtual bool	check (const std::string &key, Value *&result, const std::string &comment="") const
	Gets a value corresponding to a given keyword. More...

virtual Value	check (const std::string &key, const Value &fallback, const std::string &comment="") const
	Gets a value corresponding to a given keyword. More...

virtual bool	isNull () const
	Checks if the object is invalid. More...

Public Member Functions inherited from yarp::os::Portable
virtual Type	getType () const

Public Member Functions inherited from yarp::os::PortReader
virtual	~PortReader ()
	Destructor. More...

virtual Type	getReadType () const

Public Member Functions inherited from yarp::os::PortWriter
virtual	~PortWriter ()
	Destructor. More...

virtual void	onCompletion () const
	This is called when the port has finished all writing operations. More...

virtual void	onCommencement () const
	This is called when the port is about to begin writing operations. More...

virtual yarp::os::Type	getWriteType () const

Additional Inherited Members
Static Public Member Functions inherited from yarp::os::Portable
static bool	copyPortable (const PortWriter &writer, PortReader &reader)
	Copy one portable to another, via writing and reading. More...

Detailed Description

A class for storing options and configuration information.

Use put() to add keyword/value pairs, and get() or check() to look them up afterwards. It can read from configuration files using the fromConfigFile() method, and from command line options using the fromCommand() method, and from any Searchable object (include Bottle objects) using the fromString() method. Property objects can be searched efficiently.

Examples: bottle/main.cpp, dev/file_grabber/file_grabber.cpp, dev/grabber_client/grabber_client.cpp, dev/motortest/motortest.cpp, framerate/main.cpp, os/database/database.cpp, os/image_process/image_process.cpp, os/image_source/image_source.cpp, and property/main.cpp.

Definition at line 34 of file Property.h.

Constructor & Destructor Documentation

◆ Property() [1/6]

Property::Property ( )

Constructor.

Definition at line 919 of file Property.cpp.

◆ Property() [2/6]

Property::Property ( int hash_size )

Constructor.

Parameters

hash_size a scalar controlling efficiency of the hash map storing the data. Set to 0 for default size. The bigger this number, the more memory used, but the more efficient the map.

Deprecated:: Since YARP 3.3

Definition at line 927 of file Property.cpp.

◆ Property() [3/6]

Property::Property ( const char * str )

Initialize from a string, using fromString().

Definition at line 936 of file Property.cpp.

◆ Property() [4/6]

Property::Property ( const Property & rhs )

Copy constructor.

Definition at line 944 of file Property.cpp.

◆ Property() [5/6]

Property::Property ( Property && rhs )

noexcept

Move constructor.

Definition at line 952 of file Property.cpp.

◆ Property() [6/6]

Property::Property ( std::initializer_list< std::pair< std::string, yarp::os::Value >> values )

Initializer list constructor.

Parameters

[in] values,list of std::pair with which initialize the Property.

Definition at line 962 of file Property.cpp.

◆ ~Property()

Property::~Property ( )

override

Destructor.

Definition at line 972 of file Property.cpp.

Member Function Documentation

◆ addGroup()

Property & yarp::os::Property::addGroup ( const std::string & key )

Add a nested group.

Warning: the group object returned is valid only until the next read from the Property it was added to. As soon as there is a request for data from that Property, then it ceases to be usable.

Parameters

key the key

Returns: the nested group, represented as a Property

Definition at line 1215 of file Property.cpp.

◆ check() [1/5]

bool Property::check ( const std::string & key ) const

overridevirtual

Check if there exists a property of the given name.

Parameters

key	the name to check for

Returns: true iff a property of the given name exists, even if it doesn't have a value associated with it

Implements yarp::os::Searchable.

Examples: framerate/main.cpp, and property/main.cpp.

Definition at line 1024 of file Property.cpp.

◆ check() [2/5]

virtual bool yarp::os::Searchable::check

Check if there exists a property of the given name.

Parameters

key	the name to check for

Returns: true iff a property of the given name exists, even if it doesn't have a value associated with it

◆ check() [3/5]

bool yarp::os::Searchable::check

Check if there exists a property of the given name.

Parameters

key	the name to check for
comment	Human-readable explanation

Returns: true iff a property of the given name exists, even if it doesn't have a value associated with it

Definition at line 121 of file Searchable.cpp.

◆ check() [4/5]

yarp::os::Value yarp::os::Searchable::check

Gets a value corresponding to a given keyword.

Parameters

key	The keyword to look for
fallback	A default value to return if nothing found
comment	Optional human-readable explanation

Returns: A value corresponding to a given keyword, or the default if nothing is found. See the find() method for interpreting the value found.

Definition at line 198 of file Searchable.cpp.

◆ check() [5/5]

bool yarp::os::Searchable::check

Gets a value corresponding to a given keyword.

If a property does not exist, this returns false and does not modify the result pointer. If a property exists but does not have a value, this again returns false and does not modify the result pointer.

Property p;
p.fromString("(width 10) (height 15) (help)");
p.check("help")  // this is true
p.check("width") // this is true
p.check("foo")   // this is false
Value *v;
p.check("help", v)  // this is false, there is no value associated
p.check("width", v) // this is true, and v->asInt32() is 10

Parameters

key	The keyword to look for
result	A pointer to store the address of the result in
comment	Optional human-readable explanation

Returns: True if there is a value corresponding to a given keyword, false otherwise. See the find() method for interpreting the value found.

Definition at line 184 of file Searchable.cpp.

◆ clear()

void Property::clear ( )

Remove all associations.

Guarantees that find(key).isNull() will be true for all values of key.

Definition at line 1040 of file Property.cpp.

◆ find()

Value & Property::find ( const std::string & key ) const

overridevirtual

Gets a value corresponding to a given keyword.

Parameters

key	The keyword to look for

Returns: A value corresponding to a given keyword. If there is no such value, then the isNull() method called on the result will be true. Otherwise, the value can be read by calling result.asInt32(), result.asString(), etc. as appropriate.

Implements yarp::os::Searchable.

Examples: property/main.cpp.

Definition at line 1034 of file Property.cpp.

◆ findGroup() [1/3]

Bottle & Property::findGroup ( const std::string & key ) const

overridevirtual

Gets a list corresponding to a given keyword.

Parameters

key	The keyword to look for

Returns: A list corresponding to a given keyword. If there is no such list, then the isNull() method called on the result will be true. Otherwise, the elements of the list can be read through result.get(index) where result.get(0) is the keyword, and result.get(i) for i>=1 are the "real" elements of the list.

Implements yarp::os::Searchable.

Examples: property/main.cpp.

Definition at line 1125 of file Property.cpp.

◆ findGroup() [2/3]

virtual Bottle& yarp::os::Searchable::findGroup

Gets a list corresponding to a given keyword.

Parameters

key	The keyword to look for

Returns: A list corresponding to a given keyword. If there is no such list, then the isNull() method called on the result will be true. Otherwise, the elements of the list can be read through result.get(index) where result.get(0) is the keyword, and result.get(i) for i>=1 are the "real" elements of the list.

◆ findGroup() [3/3]

yarp::os::Bottle & yarp::os::Searchable::findGroup

Gets a list corresponding to a given keyword.

Parameters

key	The keyword to look for
comment	Human-readable explanation

Returns: A list corresponding to a given keyword. If there is no such list, then the isNull() method called on the result will be true. Otherwise, the elements of the list can be read through result.get(index) where result.get(0) is the keyword, and result.get(i) for i>=1 are the "real" elements of the list.

Definition at line 157 of file Searchable.cpp.

◆ fromArguments()

void Property::fromArguments	(	const char *	arguments,
		bool	wipe = `true`
	)

Interprets a list of command arguments as a list of properties.

Keys are named by beginning with --. For example, with argv = program_name --width 10 --height 15, the Property object will be the mapping {width => 10, height => 15}. Therefore:

prop.find("width").asInt32() // gives 10

prop.find("height").asInt32() // gives 15

If a key is duplicated, only the latest will be used. For example, with argv = program_name --foo bar --foo baz, the Property object will be the mapping {foo => baz}.

Parameters

arguments	the command arguments
wipe	should Property be emptied first

Definition at line 1071 of file Property.cpp.

◆ fromCommand() [1/2]

void Property::fromCommand	(	int	argc,
		char *	argv[],
		bool	skipFirst = `true`,
		bool	wipe = `true`
	)

Interprets a list of command arguments as a list of properties.

Keys are named by beginning with --. For example, with argv = program_name --width 10 --height 15, the Property object will be the mapping {width => 10, height => 15}. Therefore:

prop.find("width").asInt32() // gives 10

prop.find("height").asInt32() // gives 15

If a key is duplicated, only the latest will be used. For example, with argv = program_name --foo bar --foo baz, the Property object will be the mapping {foo => baz}.

Parameters

argc	the number of arguments
argv	the list of arguments
skipFirst	set to true if the first argument should be skipped (which is the right thing to do for arguments passed to main())
wipe	should Property be emptied first

Examples: framerate/main.cpp, and property/main.cpp.

Definition at line 1057 of file Property.cpp.

◆ fromCommand() [2/2]

void Property::fromCommand	(	int	argc,
		const char *	argv[],
		bool	skipFirst = `true`,
		bool	wipe = `true`
	)

Interprets a list of command arguments as a list of properties.

Keys are named by beginning with --. For example, with argv = program_name --width 10 --height 15, the Property object will be the mapping {width => 10, height => 15}. Therefore:

prop.find("width").asInt32() // gives 10

prop.find("height").asInt32() // gives 15

If a key is duplicated, only the latest will be used. For example, with argv = program_name --foo bar --foo baz, the Property object will be the mapping {foo => baz}.

Parameters

argc	the number of arguments
argv	the list of arguments
skipFirst	set to true if the first argument should be skipped (which is the right thing to do for arguments passed to main())
wipe	should Property be emptied first

Definition at line 1066 of file Property.cpp.

◆ fromConfig() [1/2]

void Property::fromConfig	(	const char *	txt,
		bool	wipe = `true`
	)

Parses text in the configuration format described in fromConfigFile().

Parameters

txt	the configuration text
wipe	should Property be emptied first

Definition at line 1093 of file Property.cpp.

◆ fromConfig() [2/2]

void Property::fromConfig	(	const char *	txt,
		Searchable &	env,
		bool	wipe = `true`
	)

Variant of fromConfig(const char*, bool) that includes extra "environment variables".

These will be expanded, along with any other variables in the environment, if present in the configuration file in $variable or ${variable} form.

Parameters


  
    txt the configuration text 
    env extra set of environment variables 
    wipe should Property be emptied first

Definition at line 1099 of file Property.cpp.

◆ fromConfigDir()

bool Property::fromConfigDir	(	const std::string &	dirname,
		const std::string &	section = `std::string()`,
		bool	wipe = `true`
	)

Interprets all files in a directory as lists of properties as described in fromConfigFile().

Parameters

dirname	the name of the file to read from
section	if specified names the subsection for each file, otherwise use the same section for all files
wipe	should Property be emptied first

Returns: true if file exists and can be read

Definition at line 1076 of file Property.cpp.

◆ fromConfigFile() [1/2]

bool Property::fromConfigFile	(	const std::string &	fname,
		bool	wipe = `true`
	)

Interprets a file as a list of properties.

For example, for a file containing:

width 10

height 15

the Property object will be the mapping {width => 10, height => 15}. In other words:

prop.find("width").asInt32() // gives 10

prop.find("height").asInt32() // gives 15

If a key is duplicated, only the latest will be used. For example, for a file containing:

foo bar

foo baz

the Property object will be the mapping {foo => baz}.

Lines of the form "[NAME]" will result in nested subproperties. For example, for a file containing:

[SIZE]
width 10
height 15
[APPEARANCE]
color red

the structure of the Property object will be "(SIZE (width 10) (height 15)) (APPEARANCE (color red))". In other words:

prop.findGroup("SIZE").find("width").asInt32() // gives 10

prop.findGroup("APPEARANCE").find("color").asString() // gives red

Warning: If a key in a group is duplicated, they will be both included as the value for the group, since the value will be a Bottle, that can include duplicate values. In this case, the Value returned by find(), will be the first and not the latter. For example, for a file containing:
[GROUP]

foo bar

foo baz

the structure of the Property object will be "(GROUP (foo bar) (foo baz))". Therefore
prop.findGroup("GROUP").toString() // gives "(foo bar) (foo baz)"

prop.findGroup("GROUP").find("foo").asString(); // gives "bar", and NOT "baz"

It is possible to nest configuration files. To include the configuration file "preamble.ini" inside another one, do:

[include "preamble.ini"]

This will insert the content of preamble.ini as if cut-and-pasted. If rather you would like the content included within a subsection called FOO, do instead:

[include FOO "preamble.ini"]

Parameters

fname	the name of the file to read from
wipe	should Property be emptied first

Returns: true if file exists and can be read

Examples: property/main.cpp.

Definition at line 1081 of file Property.cpp.

◆ fromConfigFile() [2/2]

bool Property::fromConfigFile	(	const std::string &	fname,
		Searchable &	env,
		bool	wipe = `true`
	)

Variant of fromConfigFile(fname, wipe) that includes extra "environment variables".

These will be expanded, along with any other variables in the environment, if present in the configuration file in $variable or ${variable} form.

Parameters

fname	the name of the file to read from
env	extra set of environment variables
wipe	should Property be emptied first

Returns: true if file exists and can be read

Definition at line 1088 of file Property.cpp.

◆ fromQuery()

void Property::fromQuery	(	const char *	url,
		bool	wipe = `true`
	)

Parses text in a url.

Anything of the form foo=bar is added as a property.

Parameters

url	the text of the url, of form `...prop1=val1&prop2=val2...`
wipe	should Property be emptied first

Definition at line 1153 of file Property.cpp.

◆ fromString()

void Property::fromString	(	const std::string &	txt,
		bool	wipe = `true`
	)

Interprets a string as a list of properties.

Uses the the same format as a Bottle. The first element of every sub-list is interpreted as a key. For example, with text = (width 10) (height 15), the Property object will be the mapping {width => 10, height => 15}. Therefore:

prop.find("width").asInt32() // gives 10

prop.find("height").asInt32() // gives 15

If a key is duplicated, only the latest will be used. For example, with text = (foo bar) (foo baz), the Property object will be the mapping {foo => baz}.

Parameters

txt	the textual form of the Property object
wipe	should Property be emptied first

Definition at line 1046 of file Property.cpp.

◆ operator=() [1/2]

Property & Property::operator= ( const Property & prop )

Copy assignment operator.

Definition at line 977 of file Property.cpp.

◆ operator=() [2/2]

Property & Property::operator= ( Property && prop )

noexcept

Move assignment operator.

Definition at line 988 of file Property.cpp.

◆ put() [1/5]

void Property::put	(	const std::string &	key,
		const std::string &	value
	)

Associate the given key with the given string.

After the association find(key).asString() will return that string. If key is already associated, the value will be replaced with the new one.

Parameters

key	the key
value	the string value

Examples: bottle/main.cpp.

Definition at line 998 of file Property.cpp.

◆ put() [2/5]

void Property::put	(	const std::string &	key,
		const Value &	value
	)

Associate the given key with the given value.

After the association find(key).asString() will return that value. If key is already associated, the value will be replaced with the new one.

Parameters

key	the key
value	the value

Definition at line 1003 of file Property.cpp.

◆ put() [3/5]

void Property::put	(	const std::string &	key,
		double	value
	)

Associate the given key with the given floating point number.

After the association find(key).asDouble() will return that number. If key is already associated, the value will be replaced with the new one.

Parameters

key	the key
value	the floating point value

Definition at line 1019 of file Property.cpp.

◆ put() [4/5]

void Property::put	(	const std::string &	key,
		int	value
	)

Associate the given key with the given integer.

After the association find(key).asInt32() will return that integer. If key is already associated, the value will be replaced with the new one.

Parameters

key	the key
value	the integer value

Definition at line 1014 of file Property.cpp.

◆ put() [5/5]

void Property::put	(	const std::string &	key,
		Value *	value
	)

Associate the given key with the given value.

After the association find(key) will return that value. The Property object is responsible for deallocating the value. If key is already associated, the value will be replaced with the new one.

Parameters

key	the key
value	the value

Definition at line 1009 of file Property.cpp.

◆ read()

bool Property::read ( ConnectionReader & reader )

overridevirtual

Read this object from a network connection.

Override this for your particular class.

Parameters

reader an interface to the network connection for reading

Returns: true iff the object is successfully read

Implements yarp::os::Portable.

Definition at line 1105 of file Property.cpp.

◆ toString()

std::string Property::toString ( ) const

overridevirtual

Return a standard text representation of the content of the object.

The representation is readable by the Bottle and Property classes.

Returns: A standard text representation of the content of the object.

Implements yarp::os::Searchable.

Examples: bottle/main.cpp.

Definition at line 1052 of file Property.cpp.

◆ unput()

void Property::unput ( const std::string & key )

Remove the association from the given key to a value, if present.

Guarantees that find(key).isNull() will be true.

Parameters

key the key

Definition at line 1029 of file Property.cpp.

◆ write()

bool Property::write ( ConnectionWriter & writer ) const

overridevirtual

Write this object to a network connection.

Override this for your particular class. Be aware that depending on the nature of the connections a port has, and what protocol they use, and how efficient the YARP implementation is, this method may be called once, twice, or many times, as the result of a single call to Port::write

Parameters

writer an interface to the network connection for writing

Returns: true iff the object is successfully written

Implements yarp::os::Portable.

Definition at line 1117 of file Property.cpp.

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

src/libYARP_os/src/yarp/os/Property.h
src/libYARP_os/src/yarp/os/Property.cpp

Classes

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Property() [1/6]

◆ Property() [2/6]

◆ Property() [3/6]

◆ Property() [4/6]

◆ Property() [5/6]

◆ Property() [6/6]

◆ ~Property()

Member Function Documentation

◆ addGroup()

◆ check() [1/5]

◆ check() [2/5]

◆ check() [3/5]

◆ check() [4/5]

◆ check() [5/5]

◆ clear()

◆ find()

◆ findGroup() [1/3]

◆ findGroup() [2/3]

◆ findGroup() [3/3]

◆ fromArguments()

◆ fromCommand() [1/2]

◆ fromCommand() [2/2]

◆ fromConfig() [1/2]

◆ fromConfig() [2/2]

◆ fromConfigDir()

◆ fromConfigFile() [1/2]

◆ fromConfigFile() [2/2]

◆ fromQuery()

◆ fromString()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ put() [1/5]

◆ put() [2/5]

◆ put() [3/5]

◆ put() [4/5]

◆ put() [5/5]

◆ read()

◆ toString()

◆ unput()

◆ write()