YARP  2.3.70
Yet Another Robot Platform
yarp::os::Property Class Reference

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

#include <yarp/os/Property.h>

+ Inheritance diagram for yarp::os::Property:

Public Member Functions

 Property (int hash_size=0)
 Constructor. More...
 
 Property (const char *str)
 Initialize from a string, using fromString(). More...
 
 Property (const Property &prop)
 Copy constructor. More...
 
virtual ~Property ()
 Destructor. More...
 
const Propertyoperator= (const Property &prop)
 Assignment operator. More...
 
bool check (const ConstString &key) const YARP_OVERRIDE
 Check if there exists a property of the given name. More...
 
void put (const ConstString &key, const ConstString &value)
 Associate the given key with the given string. More...
 
void put (const ConstString &key, const Value &value)
 Associate the given key with the given value. More...
 
void put (const ConstString &key, Value *value)
 Associate the given key with the given value. More...
 
void put (const ConstString &key, int value)
 Associate the given key with the given integer. More...
 
void put (const ConstString &key, double value)
 Associate the given key with the given floating point number. More...
 
PropertyaddGroup (const ConstString &key)
 Add a nested group. More...
 
void unput (const ConstString &key)
 Remove the association from the given key to a value, if present. More...
 
virtual Valuefind (const ConstString &key) const YARP_OVERRIDE
 Gets a value corresponding to a given keyword. More...
 
virtual BottlefindGroup (const ConstString &key) const YARP_OVERRIDE
 Gets a list corresponding to a given keyword. More...
 
void clear ()
 Remove all associations. More...
 
void fromString (const ConstString &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 ConstString &fname, bool wipe=true)
 Interprets a file as a list of properties. More...
 
bool fromConfigFile (const ConstString &fname, Searchable &env, bool wipe=true)
 Variant of fromConfigFile(fname, wipe) that includes extra "environment variables". More...
 
bool fromConfigDir (const ConstString &dirname, const ConstString &section=ConstString(), 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...
 
ConstString toString () const YARP_OVERRIDE
 Return a standard text representation of the content of the object. More...
 
bool read (ConnectionReader &reader) YARP_OVERRIDE
 Read this object from a network connection. More...
 
bool write (ConnectionWriter &writer) YARP_OVERRIDE
 Write this object to a network connection. More...
 
- Public Member Functions inherited from yarp::os::Searchable
 Searchable ()
 Default constructor. More...
 
virtual ~Searchable ()
 Destructor. More...
 
virtual bool check (const ConstString &key, const ConstString &comment) const
 Check if there exists a property of the given name. More...
 
BottlefindGroup (const ConstString &key, const ConstString &comment) const
 Gets a list corresponding to a given keyword. More...
 
virtual bool check (const ConstString &key, Value *&result, const ConstString &comment="") const
 Gets a value corresponding to a given keyword. More...
 
virtual Value check (const ConstString &key, const Value &fallback, const ConstString &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 ()
 
- Public Member Functions inherited from yarp::os::PortReader
virtual ~PortReader ()
 Destructor. More...
 
virtual Type getReadType ()
 
- Public Member Functions inherited from yarp::os::PortWriter
virtual ~PortWriter ()
 Destructor. More...
 
virtual void onCompletion ()
 This is called when the port has finished all writing operations. More...
 
virtual void onCommencement ()
 This is called when the port is about to begin writing operations. More...
 
virtual Type getWriteType ()
 

Private Member Functions

void summon ()
 
bool check () const
 

Private Attributes

void * implementation
 
int hash_size
 

Additional Inherited Members

- Static Public Member Functions inherited from yarp::os::Portable
static bool copyPortable (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, cuda/cuda_gpu.cpp, dev/file_grabber.cpp, dev/grabber_client.cpp, dev/motortest.cpp, framerate/main.cpp, os/database.cpp, os/image_process.cpp, os/image_source.cpp, portaudio/sound_receiver.cpp, portaudio/sound_sender_mic.cpp, and property/main.cpp.

Definition at line 32 of file Property.h.

Constructor & Destructor Documentation

◆ Property() [1/3]

Property::Property ( int  hash_size = 0)

Constructor.

Parameters
hash_sizea 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.

Definition at line 882 of file Property.cpp.

◆ Property() [2/3]

Property::Property ( const char *  str)

Initialize from a string, using fromString().

Definition at line 888 of file Property.cpp.

◆ Property() [3/3]

Property::Property ( const Property prop)

Copy constructor.

Definition at line 896 of file Property.cpp.

◆ ~Property()

Property::~Property ( )
virtual

Destructor.

Definition at line 916 of file Property.cpp.

Member Function Documentation

◆ addGroup()

Property & yarp::os::Property::addGroup ( const ConstString 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
keythe key
Returns
the nested group, represented as a Property

Definition at line 1142 of file Property.cpp.

◆ check() [1/2]

bool Property::check ( const ConstString key) const
virtual

Check if there exists a property of the given name.

Parameters
keythe 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:
dev/motortest.cpp, framerate/main.cpp, os/database.cpp, os/image_process.cpp, os/image_source.cpp, and property/main.cpp.

Definition at line 957 of file Property.cpp.

◆ check() [2/2]

bool Property::check ( ) const
private

Definition at line 911 of file Property.cpp.

◆ clear()

void Property::clear ( )

Remove all associations.

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

Definition at line 975 of file Property.cpp.

◆ find()

Value & Property::find ( const ConstString key) const
virtual

Gets a value corresponding to a given keyword.

Parameters
keyThe 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.asInt(), result.asString(), etc. as appropriate.

Implements yarp::os::Searchable.

Examples:
os/database.cpp, and property/main.cpp.

Definition at line 969 of file Property.cpp.

◆ findGroup()

Bottle & Property::findGroup ( const ConstString key) const
virtual

Gets a list corresponding to a given keyword.

Parameters
keyThe 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.

Definition at line 1059 of file Property.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").asInt() // gives 10
prop.find("height").asInt() // 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
argumentsthe command arguments
wipeshould Property be emptied first

Definition at line 1007 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").asInt() // gives 10
prop.find("height").asInt() // 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
argcthe number of arguments
argvthe list of arguments
skipFirstset to true if the first argument should be skipped (which is the right thing to do for arguments passed to main())
wipeshould Property be emptied first
Examples:
dev/file_grabber.cpp, dev/motortest.cpp, framerate/main.cpp, os/database.cpp, os/image_process.cpp, os/image_source.cpp, and property/main.cpp.

Definition at line 992 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").asInt() // gives 10
prop.find("height").asInt() // 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
argcthe number of arguments
argvthe list of arguments
skipFirstset to true if the first argument should be skipped (which is the right thing to do for arguments passed to main())
wipeshould Property be emptied first

Definition at line 1002 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
txtthe configuration text
wipeshould Property be emptied first

Definition at line 1029 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
txtthe configuration text
envextra set of environment variables
wipeshould Property be emptied first

Definition at line 1035 of file Property.cpp.

◆ fromConfigDir()

bool Property::fromConfigDir ( const ConstString dirname,
const ConstString section = ConstString(),
bool  wipe = true 
)

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

Parameters
dirnamethe name of the file to read from
sectionif specified names the subsection for each file, otherwise use the same section for all files
wipeshould Property be emptied first
Returns
true if file exists and can be read

Definition at line 1012 of file Property.cpp.

◆ fromConfigFile() [1/2]

bool Property::fromConfigFile ( const ConstString 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").asInt() // gives 10
prop.find("height").asInt() // 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").asInt() // 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
fnamethe name of the file to read from
wipeshould Property be emptied first
Returns
true if file exists and can be read
Examples:
property/main.cpp.

Definition at line 1017 of file Property.cpp.

◆ fromConfigFile() [2/2]

bool Property::fromConfigFile ( const ConstString 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
fnamethe name of the file to read from
envextra set of environment variables
wipeshould Property be emptied first
Returns
true if file exists and can be read

Definition at line 1024 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
urlthe text of the url, of form ...prop1=val1&prop2=val2...
wipeshould Property be emptied first

Definition at line 1085 of file Property.cpp.

◆ fromString()

void Property::fromString ( const ConstString 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").asInt() // gives 10
prop.find("height").asInt() // 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
txtthe textual form of the Property object
wipeshould Property be emptied first
Examples:
cuda/cuda_gpu.cpp, and dev/file_grabber.cpp.

Definition at line 981 of file Property.cpp.

◆ operator=()

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

Assignment operator.

Definition at line 924 of file Property.cpp.

◆ put() [1/5]

void Property::put ( const ConstString key,
const ConstString 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
keythe key
valuethe string value
Examples:
bottle/main.cpp, dev/grabber_client.cpp, dev/motortest.cpp, os/database.cpp, portaudio/sound_receiver.cpp, and portaudio/sound_sender_mic.cpp.

Definition at line 931 of file Property.cpp.

◆ put() [2/5]

void Property::put ( const ConstString 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
keythe key
valuethe value

Definition at line 936 of file Property.cpp.

◆ put() [3/5]

void Property::put ( const ConstString 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
keythe key
valuethe value

Definition at line 942 of file Property.cpp.

◆ put() [4/5]

void Property::put ( const ConstString key,
int  value 
)

Associate the given key with the given integer.

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

Parameters
keythe key
valuethe integer value

Definition at line 947 of file Property.cpp.

◆ put() [5/5]

void Property::put ( const ConstString 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
keythe key
valuethe floating point value

Definition at line 952 of file Property.cpp.

◆ read()

bool Property::read ( ConnectionReader reader)
virtual

Read this object from a network connection.

Override this for your particular class.

Parameters
readeran interface to the network connection for reading
Returns
true iff the object is successfully read

Implements yarp::os::Portable.

Definition at line 1041 of file Property.cpp.

◆ summon()

void Property::summon ( )
private

Definition at line 904 of file Property.cpp.

◆ toString()

ConstString Property::toString ( ) const
virtual

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 987 of file Property.cpp.

◆ unput()

void Property::unput ( const ConstString key)

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

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

Parameters
keythe key
Examples:
os/database.cpp.

Definition at line 963 of file Property.cpp.

◆ write()

bool Property::write ( ConnectionWriter writer)
virtual

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
writeran interface to the network connection for writing
Returns
true iff the object is successfully written

Implements yarp::os::Portable.

Definition at line 1052 of file Property.cpp.

Member Data Documentation

◆ hash_size

int yarp::os::Property::hash_size
private

Definition at line 431 of file Property.h.

◆ implementation

void* yarp::os::Property::implementation
private

Definition at line 430 of file Property.h.


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