YARP  2.3.70
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:

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...
 
YARP_DEPRECATED bool configure (const char *policyName, int argc, char *argv[], bool skipFirstArgument=true)
 Sets up the finder. More...
 
bool configure (int argc, char *argv[], bool skipFirstArgument=true)
 Sets up the ResourceFinder. More...
 
bool setDefaultContext (const char *contextName)
 Sets the context for the current ResourceFinder object. More...
 
bool setDefaultContext (const yarp::os::ConstString &contextName)
 Sets the context for the current ResourceFinder object. More...
 
YARP_DEPRECATED bool setContext (const char *contextName)
 Deprecated name for setDefaultContext. More...
 
bool setDefault (const char *key, const yarp::os::ConstString &val)
 Provide a default value for a given key; the provided key will be converted to a yarp::os::Value, so also string representations for lists and numerical values are accepted. More...
 
bool setDefault (const char *key, const yarp::os::Value &val)
 Provide a default value for a given key. More...
 
bool setDefaultConfigFile (const char *fname)
 Provide a default value for the configuration file (can be overridden from command line with the –from argument) More...
 
yarp::os::ConstString findFile (const ConstString &name)
 Find the full path to a file. More...
 
yarp::os::ConstString findFileByName (const ConstString &name)
 Find the full path to a file. More...
 
yarp::os::ConstString findPath (const ConstString &name)
 Expand a partial path to a full path. More...
 
yarp::os::Bottle findPaths (const ConstString &name)
 Expand a partial path to a list of paths. More...
 
yarp::os::ConstString findPath ()
 Find the first existing directory in the search path. More...
 
yarp::os::ConstString getContext ()
 Return the default "context" or "application name" used in searching for configuration files. More...
 
yarp::os::ConstString getContextPath ()
 Return the path that the default context expands to, according to the policy. More...
 
yarp::os::Bottle getContexts ()
 Return the full stack of contexts used in searching for configuration files. More...
 
virtual bool check (const ConstString &key) const YARP_OVERRIDE
 Check if there exists a property of the given name. 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...
 
virtual bool isNull () const YARP_OVERRIDE
 Checks if the object is invalid. More...
 
virtual ConstString toString () const YARP_OVERRIDE
 Return a standard text representation of the content of the object. More...
 
virtual ResourceFinder findNestedResourceFinder (const char *key)
 Gets a section as a ResourceFinder object, retaining the context and configuration of the current ResourceFinder. More...
 
bool isConfigured () const
 
yarp::os::ConstString getHomeContextPath ()
 Return the path to the "user" context directory for the current context. More...
 
yarp::os::ConstString getHomeRobotPath ()
 Return the path to the "user" robot directory. More...
 
yarp::os::Bottle findPaths (const ConstString &name, const ResourceFinderOptions &options)
 
yarp::os::ConstString findPath (const ConstString &name, const ResourceFinderOptions &options)
 
yarp::os::ConstString findFile (const ConstString &name, const ResourceFinderOptions &options)
 
yarp::os::ConstString findFileByName (const ConstString &name, const ResourceFinderOptions &options)
 
bool readConfig (Property &config, const ConstString &key, const ResourceFinderOptions &options)
 
- 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...
 

Static Public Member Functions

static ResourceFindergetResourceFinderSingleton ()
 Access a ResourceFinder singleton whose lifetime will match that of the YARP library. More...
 
static ConstString getDataHome ()
 Location where user data files are stored. More...
 
static ConstString getDataHomeNoCreate ()
 Variant of getDataHome that will never create the directory returned. More...
 
static ConstString getConfigHome ()
 Location where user config files are stored. More...
 
static ConstString 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...
 

Private Member Functions

bool addContext (const char *appName)
 
bool clearContext ()
 
 ResourceFinder (Searchable &data, void *implementation)
 

Static Private Member Functions

static ConstString getDataHomeWithPossibleCreation (bool mayCreate)
 
static ConstString getConfigHomeWithPossibleCreation (bool mayCreate)
 
static ConstString createIfAbsent (bool mayCreate, const ConstString &path)
 

Private Attributes

void * implementation
 
bool owned
 
bool nullConfig
 
bool isConfiguredFlag
 
yarp::os::Property config
 

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 31 of file ResourceFinder.h.

Constructor & Destructor Documentation

◆ ResourceFinder() [1/3]

ResourceFinder::ResourceFinder ( )

Definition at line 1009 of file ResourceFinder.cpp.

◆ ResourceFinder() [2/3]

ResourceFinder::ResourceFinder ( const ResourceFinder alt)

Definition at line 1020 of file ResourceFinder.cpp.

◆ ~ResourceFinder()

ResourceFinder::~ResourceFinder ( )
virtual

Definition at line 1042 of file ResourceFinder.cpp.

◆ ResourceFinder() [3/3]

ResourceFinder::ResourceFinder ( Searchable data,
void *  implementation 
)
private

Definition at line 1031 of file ResourceFinder.cpp.

Member Function Documentation

◆ addContext()

bool ResourceFinder::addContext ( const char *  appName)
private

Definition at line 1083 of file ResourceFinder.cpp.

◆ check()

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

Definition at line 1202 of file ResourceFinder.cpp.

◆ clearContext()

bool ResourceFinder::clearContext ( )
private

Definition at line 1092 of file ResourceFinder.cpp.

◆ configure() [1/2]

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

Sets up the finder.

The policyName is used to find a file containing the default policy for searching for resource files. Policy can affect the environment variables that are checked, the directories that are searched, and the order of search.

For a policy [P], YARP looks for an environment variable of that name. If found, it tries to load the file [P]/[P].ini and use this to configure the search policy.

An example ini file:

* style capability
* capability_directory app
* default_capability default
* 

This would make the default search path include [P]/app/default and an added context [C] would add [P]/app/[C] to the search path.

Some elements of policy can be changed from the commandline.

Returns
true if configuration succeeded. Configuration fails if the user requests use of a policy and that policy cannot be found, of 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 sucess/failure (since it is perfectly valid for it to be absent).
Deprecated:
since YARP 2.3.65
Examples:
os/image_process_module.cpp.

Definition at line 1064 of file ResourceFinder.cpp.

◆ configure() [2/2]

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 sucess/failure (since it is perfectly valid for it to be absent).

Definition at line 1076 of file ResourceFinder.cpp.

◆ createIfAbsent()

ConstString ResourceFinder::createIfAbsent ( bool  mayCreate,
const ConstString path 
)
staticprivate

Definition at line 1345 of file ResourceFinder.cpp.

◆ find()

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

Definition at line 1208 of file ResourceFinder.cpp.

◆ findFile() [1/2]

yarp::os::ConstString ResourceFinder::findFile ( const ConstString 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 1112 of file ResourceFinder.cpp.

◆ findFile() [2/2]

yarp::os::ConstString ResourceFinder::findFile ( const ConstString name,
const ResourceFinderOptions options 
)

Definition at line 1120 of file ResourceFinder.cpp.

◆ findFileByName() [1/2]

yarp::os::ConstString ResourceFinder::findFileByName ( const ConstString 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 1129 of file ResourceFinder.cpp.

◆ findFileByName() [2/2]

yarp::os::ConstString ResourceFinder::findFileByName ( const ConstString name,
const ResourceFinderOptions options 
)

Definition at line 1137 of file ResourceFinder.cpp.

◆ findGroup()

Bottle & ResourceFinder::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 1214 of file ResourceFinder.cpp.

◆ findNestedResourceFinder()

ResourceFinder ResourceFinder::findNestedResourceFinder ( const char *  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 1261 of file ResourceFinder.cpp.

◆ findPath() [1/3]

yarp::os::ConstString ResourceFinder::findPath ( const ConstString 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 1147 of file ResourceFinder.cpp.

◆ findPath() [2/3]

yarp::os::ConstString ResourceFinder::findPath ( )

Find the first existing directory in the search path.

Definition at line 1181 of file ResourceFinder.cpp.

◆ findPath() [3/3]

yarp::os::ConstString ResourceFinder::findPath ( const ConstString name,
const ResourceFinderOptions options 
)

Definition at line 1155 of file ResourceFinder.cpp.

◆ findPaths() [1/2]

yarp::os::Bottle ResourceFinder::findPaths ( const ConstString 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 1164 of file ResourceFinder.cpp.

◆ findPaths() [2/2]

yarp::os::Bottle ResourceFinder::findPaths ( const ConstString name,
const ResourceFinderOptions options 
)

Definition at line 1172 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% On Linux and all others: /etc/yarp is returned. (an OSX-specific case remains to be defined)

Definition at line 1383 of file ResourceFinder.cpp.

◆ getConfigHome()

static ConstString 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% is returned. On Linux and all others: $HOME/.config/yarp is returned. (an OSX-specific case remains to be defined)

Definition at line 374 of file ResourceFinder.h.

◆ getConfigHomeNoCreate()

static ConstString yarp::os::ResourceFinder::getConfigHomeNoCreate ( )
inlinestatic

Variant of getConfigHome that will never create the directory returned.

Definition at line 384 of file ResourceFinder.h.

◆ getConfigHomeWithPossibleCreation()

ConstString ResourceFinder::getConfigHomeWithPossibleCreation ( bool  mayCreate)
staticprivate

Definition at line 1309 of file ResourceFinder.cpp.

◆ getContext()

ConstString 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 1231 of file ResourceFinder.cpp.

◆ getContextPath()

ConstString ResourceFinder::getContextPath ( )

Return the path that the default context expands to, according to the policy.

If no policy was used, behave as getHomeContextPath

Deprecated:
since YARP 2.3.60

Definition at line 1237 of file ResourceFinder.cpp.

◆ getContexts()

Bottle ResourceFinder::getContexts ( )

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

Definition at line 1255 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% 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 1353 of file ResourceFinder.cpp.

◆ getDataHome()

static ConstString 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% is returned. On Linux and all others: $HOME/.local/share is returned. (an OSX-specific case remains to be defined)

Definition at line 344 of file ResourceFinder.h.

◆ getDataHomeNoCreate()

static ConstString yarp::os::ResourceFinder::getDataHomeNoCreate ( )
inlinestatic

Variant of getDataHome that will never create the directory returned.

Definition at line 355 of file ResourceFinder.h.

◆ getDataHomeWithPossibleCreation()

ConstString ResourceFinder::getDataHomeWithPossibleCreation ( bool  mayCreate)
staticprivate

Definition at line 1272 of file ResourceFinder.cpp.

◆ getHomeContextPath()

ConstString ResourceFinder::getHomeContextPath ( )

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

Definition at line 1244 of file ResourceFinder.cpp.

◆ getHomeRobotPath()

ConstString ResourceFinder::getHomeRobotPath ( )

Return the path to the "user" robot directory.

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

◆ isConfigured()

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

Definition at line 306 of file ResourceFinder.h.

◆ isNull()

bool ResourceFinder::isNull ( ) const
virtual

Checks if the object is invalid.

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

Reimplemented from yarp::os::Searchable.

Definition at line 1220 of file ResourceFinder.cpp.

◆ operator=()

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

Definition at line 1053 of file ResourceFinder.cpp.

◆ readConfig()

bool ResourceFinder::readConfig ( Property config,
const ConstString key,
const ResourceFinderOptions options 
)

Definition at line 1416 of file ResourceFinder.cpp.

◆ setContext()

YARP_DEPRECATED bool yarp::os::ResourceFinder::setContext ( const char *  contextName)
inline

Deprecated name for setDefaultContext.

Deprecated:
since YARP 2.3.70

Definition at line 160 of file ResourceFinder.h.

◆ setDefault() [1/2]

bool ResourceFinder::setDefault ( const char *  key,
const yarp::os::ConstString val 
)

Provide a default value for a given key; the provided key will be converted to a yarp::os::Value, so also string representations for lists and numerical values are accepted.

Definition at line 1100 of file ResourceFinder.cpp.

◆ setDefault() [2/2]

bool ResourceFinder::setDefault ( const char *  key,
const yarp::os::Value val 
)

Provide a default value for a given key.

Definition at line 1107 of file ResourceFinder.cpp.

◆ setDefaultConfigFile()

bool yarp::os::ResourceFinder::setDefaultConfigFile ( const char *  fname)
inline

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

Definition at line 186 of file ResourceFinder.h.

◆ setDefaultContext() [1/2]

bool yarp::os::ResourceFinder::setDefaultContext ( const char *  contextName)
inline

Sets the context for the current ResourceFinder object.

A context is a folder collecting configuration files and data that may be used to configure modules at runtime. When the resource finder is configured with a specific contextName, contexts/<context-name> is added to the search path in which the initial configuration file and any additional files are sought.

Parameters
contextNameThe name of the context
Returns
true on success, false otherwise

Definition at line 136 of file ResourceFinder.h.

◆ setDefaultContext() [2/2]

bool yarp::os::ResourceFinder::setDefaultContext ( const yarp::os::ConstString 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 149 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

Definition at line 1195 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
Examples:
os/image_process_module.cpp.

Definition at line 1190 of file ResourceFinder.cpp.

◆ toString()

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

Definition at line 1226 of file ResourceFinder.cpp.

Member Data Documentation

◆ config

yarp::os::Property yarp::os::ResourceFinder::config
private

Definition at line 466 of file ResourceFinder.h.

◆ implementation

void* yarp::os::ResourceFinder::implementation
private

Definition at line 462 of file ResourceFinder.h.

◆ isConfiguredFlag

bool yarp::os::ResourceFinder::isConfiguredFlag
private

Definition at line 465 of file ResourceFinder.h.

◆ nullConfig

bool yarp::os::ResourceFinder::nullConfig
private

Definition at line 464 of file ResourceFinder.h.

◆ owned

bool yarp::os::ResourceFinder::owned
private

Definition at line 463 of file ResourceFinder.h.


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