YARP
Yet Another Robot Platform
yarp::os::ResourceFinder Class Reference

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

#include <yarp/os/ResourceFinder.h>

+ Inheritance diagram for yarp::os::ResourceFinder:

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.

Examples
os/image_process_module.cpp.

Definition at line 32 of file ResourceFinder.h.

Classes

class  Private
 

Public Member Functions

 ResourceFinder ()
 
 ResourceFinder (const ResourceFinder &alt)
 
virtual ~ResourceFinder ()
 
const ResourceFinderoperator= (const ResourceFinder &alt)
 
bool setVerbose (bool verbose=true)
 Request that information be printed to the console on how resources are being found. More...
 
bool setQuiet (bool quiet=true)
 Request that information be suppressed from the console. More...
 
bool configure (int argc, char *argv[], bool skipFirstArgument=true)
 Sets up the ResourceFinder. More...
 
bool setDefaultContext (const std::string &contextName)
 Sets the context for the current ResourceFinder object. More...
 
bool setDefault (const std::string &key, const std::string &val)
 Provide a default value for a given key. More...
 
bool setDefault (const std::string &key, std::int32_t val)
 Provide a default value for a given key. More...
 
bool setDefault (const std::string &key, yarp::conf::float64_t val)
 Provide a default value for a given key. More...
 
bool setDefault (const std::string &key, const yarp::os::Value &val)
 Provide a default value for a given key. More...
 
bool setDefaultConfigFile (const std::string &fname)
 Provide a default value for the configuration file (can be overridden from command line with the –from argument) More...
 
std::string findFile (const std::string &name)
 Find the full path to a file. More...
 
std::string findFileByName (const std::string &name)
 Find the full path to a file. More...
 
std::string findPath (const std::string &name)
 Expand a partial path to a full path. More...
 
yarp::os::Bottle findPaths (const std::string &name)
 Expand a partial path to a list of paths. More...
 
std::string findPath ()
 Find the first existing directory in the search path. More...
 
std::string getContext ()
 Return the default "context" or "application name" used in searching for configuration files. More...
 
yarp::os::Bottle getContexts ()
 Return the full stack of contexts used in searching for configuration files. More...
 
bool check (const std::string &key) const override
 Check if there exists a property of the given name. More...
 
Valuefind (const std::string &key) const override
 Gets a value corresponding to a given keyword. More...
 
BottlefindGroup (const std::string &key) const override
 Gets a list corresponding to a given keyword. More...
 
bool isNull () const override
 Checks if the object is invalid. More...
 
std::string toString () const override
 Return a standard text representation of the content of the object. More...
 
virtual ResourceFinder findNestedResourceFinder (const std::string &key)
 Gets a section as a ResourceFinder object, retaining the context and configuration of the current ResourceFinder. More...
 
bool isConfigured () const
 
std::string getHomeContextPath ()
 Return the path to the "user" context directory for the current context. More...
 
std::string getHomeRobotPath ()
 Return the path to the "user" robot directory. More...
 
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)
 
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 BottlefindGroup (const std::string &key) const=0
 Gets a list corresponding to a given keyword. More...
 
BottlefindGroup (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...
 
Searchableoperator= (const Searchable &rhs)=default
 Copy assignment operator. More...
 
Searchableoperator= (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...
 
BottlefindGroup (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...
 

Static Public Member Functions

static ResourceFindergetResourceFinderSingleton ()
 Access a ResourceFinder singleton whose lifetime will match that of the YARP library. More...
 
static std::string getDataHome ()
 Location where user data files are stored. More...
 
static std::string getDataHomeNoCreate ()
 Variant of getDataHome that will never create the directory returned. More...
 
static std::string getConfigHome ()
 Location where user config files are stored. More...
 
static std::string getConfigHomeNoCreate ()
 Variant of getConfigHome that will never create the directory returned. More...
 
static Bottle getDataDirs ()
 Locations where packaged data and config files are stored. More...
 
static Bottle getConfigDirs ()
 Locations where system administrator data and config files are stored. More...
 

Constructor & Destructor Documentation

◆ ResourceFinder() [1/2]

ResourceFinder::ResourceFinder ( )

Definition at line 745 of file ResourceFinder.cpp.

◆ ResourceFinder() [2/2]

ResourceFinder::ResourceFinder ( const ResourceFinder alt)

Definition at line 756 of file ResourceFinder.cpp.

◆ ~ResourceFinder()

ResourceFinder::~ResourceFinder ( )
virtual

Definition at line 782 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
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.

Definition at line 918 of file ResourceFinder.cpp.

◆ check() [2/5]

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

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

◆ check() [3/5]

bool yarp::os::Searchable::check

Check if there exists a property of the given name.

Parameters
keythe name to check for
commentHuman-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 84 of file Searchable.cpp.

◆ check() [4/5]

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

Gets a value corresponding to a given keyword.

Parameters
keyThe keyword to look for
fallbackA default value to return if nothing found
commentOptional 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 58 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
keyThe keyword to look for
resultA pointer to store the address of the result in
commentOptional 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 39 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).
Examples
os/image_process_module.cpp.

Definition at line 801 of file ResourceFinder.cpp.

◆ find()

Value & ResourceFinder::find ( const std::string &  key) const
overridevirtual

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

Implements yarp::os::Searchable.

Definition at line 924 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 845 of file ResourceFinder.cpp.

◆ findFile() [2/2]

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

Definition at line 851 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 858 of file ResourceFinder.cpp.

◆ findFileByName() [2/2]

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

Definition at line 864 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
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 930 of file ResourceFinder.cpp.

◆ findGroup() [2/3]

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

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.

◆ findGroup() [3/3]

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

Gets a list corresponding to a given keyword.

Parameters
keyThe keyword to look for
commentHuman-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 97 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
keyThe section to look for
Returns
A ResourceFinder corresponding to the named section

Definition at line 968 of file ResourceFinder.cpp.

◆ findPath() [1/3]

std::string ResourceFinder::findPath ( )

Find the first existing directory in the search path.

Definition at line 898 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 872 of file ResourceFinder.cpp.

◆ findPath() [3/3]

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

Definition at line 878 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 885 of file ResourceFinder.cpp.

◆ findPaths() [2/2]

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

Definition at line 891 of file ResourceFinder.cpp.

◆ getConfigDirs()

Bottle ResourceFinder::getConfigDirs ( )
static

Locations where system administrator data and config files are stored.

If $YARP_CONFIG_DIRS is set, that is returned. Otherwise: If $XDG_CONFIG_DIRS is set, "/yarp" or "\yarp" as appropriate is appended to each path and the result returned. Otherwise: On Windows ALLUSERSPROFILE%\yarp On Linux and all others: /etc/yarp is returned. (an OSX-specific case remains to be defined)

Definition at line 1103 of file ResourceFinder.cpp.

◆ getConfigHome()

static std::string yarp::os::ResourceFinder::getConfigHome ( )
inlinestatic

Location where user config files are stored.

If $YARP_CONFIG_HOME is set, that is returned. Otherwise: If $XDG_CONFIG_HOME is set, "yarp" is appended to it after the OS-appropriate directory separator, and the result returned. Otherwise: On Windows APPDATA%\yarp\config is returned. On Linux and all others: $HOME/.config/yarp is returned. (an OSX-specific case remains to be defined)

Definition at line 314 of file ResourceFinder.h.

◆ getConfigHomeNoCreate()

static std::string yarp::os::ResourceFinder::getConfigHomeNoCreate ( )
inlinestatic

Variant of getConfigHome that will never create the directory returned.

Definition at line 325 of file ResourceFinder.h.

◆ 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 947 of file ResourceFinder.cpp.

◆ getContexts()

Bottle ResourceFinder::getContexts ( )

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

Definition at line 962 of file ResourceFinder.cpp.

◆ getDataDirs()

Bottle ResourceFinder::getDataDirs ( )
static

Locations where packaged data and config files are stored.

If $YARP_DATA_DIRS is set, that is returned. Otherwise: If $XDG_DATA_DIRS is set, "/yarp" or "\yarp" as appropriate is appended to each path and the result returned. Otherwise: On Windows YARP_DIR%\share\yarp On Linux and all others: /usr/local/share/yarp:/usr/share/yarp is returned. (an OSX-specific case remains to be defined)

Definition at line 1071 of file ResourceFinder.cpp.

◆ getDataHome()

static std::string yarp::os::ResourceFinder::getDataHome ( )
inlinestatic

Location where user data files are stored.

If $YARP_DATA_HOME is set, that is returned. We do not check to see if that directory exists. Otherwise: (In all the following cases, we attempt to create the directory returned if it does not already exist). If $XDG_DATA_HOME is set, "yarp" is appended to it after the OS-appropriate directory separator, and the result returned. Otherwise: On Windows APPDATA%\yarp is returned. On Linux and all others: $HOME/.local/share is returned. (an OSX-specific case remains to be defined)

Definition at line 282 of file ResourceFinder.h.

◆ getDataHomeNoCreate()

static std::string yarp::os::ResourceFinder::getDataHomeNoCreate ( )
inlinestatic

Variant of getDataHome that will never create the directory returned.

Definition at line 294 of file ResourceFinder.h.

◆ getHomeContextPath()

std::string ResourceFinder::getHomeContextPath ( )

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

Definition at line 952 of file ResourceFinder.cpp.

◆ getHomeRobotPath()

std::string ResourceFinder::getHomeRobotPath ( )

Return the path to the "user" robot directory.

Definition at line 957 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 974 of file ResourceFinder.cpp.

◆ isConfigured()

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

Definition at line 243 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 936 of file ResourceFinder.cpp.

◆ operator=()

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

Definition at line 789 of file ResourceFinder.cpp.

◆ readConfig()

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

Definition at line 1136 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 823 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 840 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 830 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 835 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 134 of file ResourceFinder.h.

◆ setDefaultContext()

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

Sets the context for the current ResourceFinder object.

Parameters
contextNameThe name of the context
Returns
true on success, false otherwise
See also
setDefaultContext(const char *contextName)

Definition at line 91 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
quietsuppress printing of information
Returns
true iff information will be suppressed
Deprecated:
since YARP 3.4

Definition at line 911 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
verboseset/suppress printing of information
Returns
true iff information will be printed
Deprecated:
since YARP 3.4

Definition at line 905 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 942 of file ResourceFinder.cpp.


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