Helper class for finding config files and other external resources. More...

#include <yarp/os/ResourceFinder.h>

Inheritance diagram for yarp::os::ResourceFinder:

Classes
class	Private

Public Member Functions
	ResourceFinder ()

	ResourceFinder (const ResourceFinder &alt)

virtual	~ResourceFinder ()

const ResourceFinder &	operator= (const ResourceFinder &alt)

bool	configure (int argc, char *argv[], bool skipFirstArgument=true)
	Sets up the ResourceFinder.

bool	setDefaultContext (const std::string &contextName)
	Sets the context for the current ResourceFinder object.

bool	setDefault (const std::string &key, const std::string &val)
	Provide a default value for a given key.

bool	setDefault (const std::string &key, std::int32_t val)
	Provide a default value for a given key.

bool	setDefault (const std::string &key, yarp::conf::float64_t val)
	Provide a default value for a given key.

bool	setDefault (const std::string &key, const yarp::os::Value &val)
	Provide a default value for a given key.

bool	setDefaultConfigFile (const std::string &fname)
	Provide a default value for the configuration file (can be overridden from command line with the –from argument)

std::string	findFile (const std::string &name)
	Find the full path to a file.

std::string	findFileByName (const std::string &name)
	Find the full path to a file.

std::string	findPath (const std::string &name)
	Expand a partial path to a full path.

yarp::os::Bottle	findPaths (const std::string &name)
	Expand a partial path to a list of paths.

std::string	findPath ()
	Find the first existing directory in the search path.

std::string	getContext ()
	Return the default "context" or "application name" used in searching for configuration files.

yarp::os::Bottle	getContexts ()
	Return the full stack of contexts used in searching for configuration files.

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

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

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

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

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

virtual ResourceFinder	findNestedResourceFinder (const std::string &key)
	Gets a section as a ResourceFinder object, retaining the context and configuration of the current ResourceFinder.

bool	isConfigured () const

std::string	getHomeContextPath ()
	Return the path to the "user" context directory for the current context.

std::string	getHomeRobotPath ()
	Return the path to the "user" robot directory.

yarp::os::Bottle	findPaths (const std::string &name, const ResourceFinderOptions &options)

std::string	findPath (const std::string &name, const ResourceFinderOptions &options)

std::string	findFile (const std::string &name, const ResourceFinderOptions &options)

std::string	findFileByName (const std::string &name, const ResourceFinderOptions &options)

bool	readConfig (Property &config, const std::string &key, const ResourceFinderOptions &options)

bool	setVerbose (bool verbose=true)
	Request that information be printed to the console on how resources are being found.

bool	setQuiet (bool quiet=true)
	Request that information be suppressed from the console.

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

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

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

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

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

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

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

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

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

virtual	~Searchable ()
	Destructor.

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

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

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

Static Public Member Functions
static ResourceFinder &	getResourceFinderSingleton ()
	Access a ResourceFinder singleton whose lifetime will match that of the YARP library.

Detailed Description

Helper class for finding config files and other external resources.

More details on this class behaviour can be found in ResourceFinder Tutorials and Specification.

Definition at line 28 of file ResourceFinder.h.

Constructor & Destructor Documentation

◆ ResourceFinder() [1/2]

ResourceFinder::ResourceFinder ( )

Definition at line 730 of file ResourceFinder.cpp.

◆ ResourceFinder() [2/2]

ResourceFinder::ResourceFinder ( const ResourceFinder & alt )

Definition at line 741 of file ResourceFinder.cpp.

◆ ~ResourceFinder()

ResourceFinder::~ResourceFinder ( )

virtual

Definition at line 767 of file ResourceFinder.cpp.

Member Function Documentation

◆ check() [1/5]

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

Definition at line 903 of file ResourceFinder.cpp.

◆ check() [2/5]

virtual bool yarp::os::Searchable::check ( const std::string & key ) const

virtual

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.

◆ check() [3/5]

bool yarp::os::Searchable::check	(	const std::string &	key,
		const std::string &	comment
	)		const

virtual

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

Reimplemented from yarp::os::Searchable.

Definition at line 79 of file Searchable.cpp.

◆ check() [4/5]

yarp::os::Value yarp::os::Searchable::check	(	const std::string &	key,
		const Value &	fallback,
		const std::string &	comment = `""`
	)		const

virtual

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.

Reimplemented from yarp::os::Searchable.

Definition at line 156 of file Searchable.cpp.

◆ check() [5/5]

bool yarp::os::Searchable::check	(	const std::string &	key,
		Value *&	result,
		const std::string &	comment = `""`
	)		const

virtual

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.

Reimplemented from yarp::os::Searchable.

Definition at line 142 of file Searchable.cpp.

◆ configure()

bool ResourceFinder::configure	(	int	argc,
		char *	argv[],
		bool	skipFirstArgument = `true`
	)

Sets up the ResourceFinder.

Returns: true if configuration succeeded. Configuration fails if the user requests a configuration file to be read (via –from for example) and that file cannot be found. If a default configuration file has been set with ResourceFinder::setDefaultConfigFile, the presence or absence of that file doesn't by itself contribute to success/failure (since it is perfectly valid for it to be absent).

Definition at line 786 of file ResourceFinder.cpp.

◆ find()

Value & ResourceFinder::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.

Definition at line 909 of file ResourceFinder.cpp.

◆ findFile() [1/2]

std::string ResourceFinder::findFile ( const std::string & name )

Find the full path to a file.

The file is specified by the name of a key. The value of the key should be set up either on the command line, through a loaded config file, or by a call to setDefault.

If all else fails, findFile will try interpreting key as a file name - this is for backwards compatibility and is behavior that will probably go away - don't depend on it!

The file is searched in a hierarchy of paths as defined in ResourceFinder Tutorials and Specification.

Definition at line 830 of file ResourceFinder.cpp.

◆ findFile() [2/2]

std::string ResourceFinder::findFile	(	const std::string &	name,
		const ResourceFinderOptions &	options
	)

Definition at line 836 of file ResourceFinder.cpp.

◆ findFileByName() [1/2]

std::string ResourceFinder::findFileByName ( const std::string & name )

Find the full path to a file.

The name of the file is provided explicitly.

The file is searched in a hierarchy of paths as defined in ResourceFinder Tutorials and Specification.

Definition at line 843 of file ResourceFinder.cpp.

◆ findFileByName() [2/2]

std::string ResourceFinder::findFileByName	(	const std::string &	name,
		const ResourceFinderOptions &	options
	)

Definition at line 849 of file ResourceFinder.cpp.

◆ findGroup() [1/3]

Bottle & ResourceFinder::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.

Definition at line 915 of file ResourceFinder.cpp.

◆ findGroup() [2/3]

virtual Bottle & yarp::os::Searchable::findGroup ( const std::string & key ) const

virtual

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.

◆ findGroup() [3/3]

yarp::os::Bottle & yarp::os::Searchable::findGroup	(	const std::string &	key,
		const std::string &	comment
	)		const

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 115 of file Searchable.cpp.

◆ findNestedResourceFinder()

ResourceFinder ResourceFinder::findNestedResourceFinder ( const std::string & key )

virtual

Gets a section as a ResourceFinder object, retaining the context and configuration of the current ResourceFinder.

This is a thin wrapper around the Searchable::findGroup method.

Parameters

key	The section to look for

Returns: A ResourceFinder corresponding to the named section

Definition at line 953 of file ResourceFinder.cpp.

◆ findPath() [1/3]

std::string ResourceFinder::findPath ( )

Find the first existing directory in the search path.

Definition at line 883 of file ResourceFinder.cpp.

◆ findPath() [2/3]

std::string ResourceFinder::findPath ( const std::string & name )

Expand a partial path to a full path.

The path is specified by the name of a key. The value of the key should be set up either on the command line, through a loaded config file, or by a call to setDefault.

If all else fails, findPath will try interpreting key as a path - this is for backwards compatibility and is behavior that will probably go away - don't depend on it!

The path is searched in a hierarchy of paths as defined in ResourceFinder Tutorials and Specification.

Definition at line 857 of file ResourceFinder.cpp.

◆ findPath() [3/3]

std::string ResourceFinder::findPath	(	const std::string &	name,
		const ResourceFinderOptions &	options
	)

Definition at line 863 of file ResourceFinder.cpp.

◆ findPaths() [1/2]

yarp::os::Bottle ResourceFinder::findPaths ( const std::string & name )

Expand a partial path to a list of paths.

Like findPath(key), but continues on to find all instances of the path.

so findPaths("app") would return ["/foo/app", "/bar/app", ...] depending on the search path in effect. The first path is the list comes from the highest-priority location, and would be the path returned by findPath("app")

The path is searched in a hierarchy of paths as defined in ResourceFinder Tutorials and Specification.

Definition at line 870 of file ResourceFinder.cpp.

◆ findPaths() [2/2]

yarp::os::Bottle ResourceFinder::findPaths	(	const std::string &	name,
		const ResourceFinderOptions &	options
	)

Definition at line 876 of file ResourceFinder.cpp.

◆ getContext()

std::string ResourceFinder::getContext ( )

Return the default "context" or "application name" used in searching for configuration files.

The context is a keyword that is converted into a search path in a policy-specific way.

Definition at line 932 of file ResourceFinder.cpp.

◆ getContexts()

Bottle ResourceFinder::getContexts ( )

Return the full stack of contexts used in searching for configuration files.

Definition at line 947 of file ResourceFinder.cpp.

◆ getHomeContextPath()

std::string ResourceFinder::getHomeContextPath ( )

Return the path to the "user" context directory for the current context.

Definition at line 937 of file ResourceFinder.cpp.

◆ getHomeRobotPath()

std::string ResourceFinder::getHomeRobotPath ( )

Return the path to the "user" robot directory.

Definition at line 942 of file ResourceFinder.cpp.

◆ getResourceFinderSingleton()

ResourceFinder & ResourceFinder::getResourceFinderSingleton ( )

static

Access a ResourceFinder singleton whose lifetime will match that of the YARP library.

Returns: the ResourceFinder singleton

Definition at line 959 of file ResourceFinder.cpp.

◆ isConfigured()

bool yarp::os::ResourceFinder::isConfigured ( ) const

inline

Definition at line 212 of file ResourceFinder.h.

◆ isNull()

bool ResourceFinder::isNull ( ) const

overridevirtual

Checks if the object is invalid.

Returns: True if the object is invalid or "null".

Reimplemented from yarp::os::Searchable.

Definition at line 921 of file ResourceFinder.cpp.

◆ operator=()

const ResourceFinder & ResourceFinder::operator= ( const ResourceFinder & alt )

Definition at line 774 of file ResourceFinder.cpp.

◆ readConfig()

bool ResourceFinder::readConfig	(	Property &	config,
		const std::string &	key,
		const ResourceFinderOptions &	options
	)

Definition at line 965 of file ResourceFinder.cpp.

◆ setDefault() [1/4]

bool ResourceFinder::setDefault	(	const std::string &	key,
		const std::string &	val
	)

Provide a default value for a given key.

The provided val will be converted to a yarp::os::Value, so also string representations for lists and numerical values are accepted.

Definition at line 808 of file ResourceFinder.cpp.

◆ setDefault() [2/4]

bool ResourceFinder::setDefault	(	const std::string &	key,
		const yarp::os::Value &	val
	)

Provide a default value for a given key.

Definition at line 825 of file ResourceFinder.cpp.

◆ setDefault() [3/4]

bool ResourceFinder::setDefault	(	const std::string &	key,
		std::int32_t	val
	)

Provide a default value for a given key.

The provided val will be converted to a 32-bit integer yarp::os::Value.

Definition at line 815 of file ResourceFinder.cpp.

◆ setDefault() [4/4]

bool ResourceFinder::setDefault	(	const std::string &	key,
		yarp::conf::float64_t	val
	)

Provide a default value for a given key.

The provided val will be converted to a 64-bit floating point yarp::os::Value.

Definition at line 820 of file ResourceFinder.cpp.

◆ setDefaultConfigFile()

bool yarp::os::ResourceFinder::setDefaultConfigFile ( const std::string & fname )

inline

Provide a default value for the configuration file (can be overridden from command line with the –from argument)

Definition at line 103 of file ResourceFinder.h.

◆ setDefaultContext()

bool yarp::os::ResourceFinder::setDefaultContext ( const std::string & contextName )

inline

Sets the context for the current ResourceFinder object.

Parameters

contextName The name of the context

Returns: true on success, false otherwise

See also: setDefaultContext(const char *contextName)

Definition at line 60 of file ResourceFinder.h.

◆ setQuiet()

bool ResourceFinder::setQuiet ( bool quiet = true )

Request that information be suppressed from the console.

By default ResourceFinder will print messages if it fails to find files, for example.

Parameters

quiet suppress printing of information

Returns: true iff information will be suppressed

Deprecated:: since YARP 3.4

Definition at line 896 of file ResourceFinder.cpp.

◆ setVerbose()

bool ResourceFinder::setVerbose ( bool verbose = true )

Request that information be printed to the console on how resources are being found.

This is especially useful to understand why resources are not found or the wrong resource is picked up.

Parameters

verbose set/suppress printing of information

Returns: true iff information will be printed

Deprecated:: since YARP 3.4

Definition at line 890 of file ResourceFinder.cpp.

◆ toString()

std::string ResourceFinder::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.

Definition at line 927 of file ResourceFinder.cpp.

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

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

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ResourceFinder() [1/2]

◆ ResourceFinder() [2/2]

◆ ~ResourceFinder()

Member Function Documentation

◆ check() [1/5]

◆ check() [2/5]

◆ check() [3/5]

◆ check() [4/5]

◆ check() [5/5]

◆ configure()

◆ find()

◆ findFile() [1/2]

◆ findFile() [2/2]

◆ findFileByName() [1/2]

◆ findFileByName() [2/2]

◆ findGroup() [1/3]

◆ findGroup() [2/3]

◆ findGroup() [3/3]

◆ findNestedResourceFinder()

◆ findPath() [1/3]

◆ findPath() [2/3]

◆ findPath() [3/3]

◆ findPaths() [1/2]

◆ findPaths() [2/2]

◆ getContext()

◆ getContexts()

◆ getHomeContextPath()

◆ getHomeRobotPath()

◆ getResourceFinderSingleton()

◆ isConfigured()

◆ isNull()

◆ operator=()

◆ readConfig()

◆ setDefault() [1/4]

◆ setDefault() [2/4]

◆ setDefault() [3/4]

◆ setDefault() [4/4]

◆ setDefaultConfigFile()

◆ setDefaultContext()

◆ setQuiet()

◆ setVerbose()

◆ toString()