Ignition Common

API Reference

4.5.0

Functions to handle getting system paths, keeps track of: More...

#include <ignition/common/SystemPaths.hh>

Public Member Functions

 SystemPaths ()
 Constructor for SystemPaths. More...
 
virtual ~SystemPaths ()
 Destructor. More...
 
void AddFilePaths (const std::string &_path)
 Add colon (semicolon on windows) delimited paths to find files. These paths will be used with the FindFile function. More...
 
void AddFindFileCallback (std::function< std::string(const std::string &)> _cb)
 Add a callback to use when FindFile() can't find a file. The callback should return a full local path to the requested file, or and empty string if the file was not found in the callback. The path should use platform-specific directory separators. Callbacks will be called in the order they were added until a path is found (if a callback is set using SetFindFileCallback(), that one is called first). More...
 
void AddFindFileURICallback (std::function< std::string(const URI &)> _cb)
 Add a callback to use when FindFileURI() can't find a file. The callback should return a full local path to the requested file, or and empty string if the file was not found in the callback. The path should use platform-specific directory separators. Callbacks will be called in the order they were added until a path is found (if a callback is set using SetFindFileURICallback(), that one is called first). More...
 
void AddPluginPaths (const std::string &_path)
 Add colon (semicolon on windows) delimited paths to plugins. More...
 
void AddSearchPathSuffix (const std::string &_suffix)
 add _suffix to the list of path search suffixes More...
 
void ClearFilePaths ()
 clear out SystemPaths::filePaths More...
 
void ClearPluginPaths ()
 clear out SystemPaths::pluginPaths More...
 
std::string FilePathEnv () const
 Get the file path environment variable in use. The environment variable contains a set of colon (semicolon on windows) delimited paths. These paths are used with the FindFile functions. More...
 
const std::list< std::string > & FilePaths ()
 Get the file paths. More...
 
std::string FindFile (const std::string &_filename, const bool _searchLocalPath=true, const bool _verbose=true) const
 Find a file in the set search paths (not recursive) More...
 
std::string FindFileURI (const std::string &_uri) const
 Find a file or path using a URI. More...
 
std::string FindFileURI (const URI &_uri) const
 Find a file or path using a URI. If URI is not an absolute path, the URI's path will be matched against all added paths and environment variables (including URI authority as needed). More...
 
std::string FindSharedLibrary (const std::string &_libName)
 Find a shared library by name in the plugin paths. More...
 
std::string LogPath () const
 Get the log path. If IGN_LOG_PATH environment variable is set, then this path is used. If not, the path is $HOME/.ignition, and in case even HOME is not set, /tmp/ignition is used. If the directory does not exist, it is created in the constructor of SystemPaths. More...
 
const std::list< std::string > & PluginPaths ()
 Get the plugin paths. More...
 
void SetFilePathEnv (const std::string &_env)
 Set the file path environment variable to use, and clears any previously set file paths. The default environment variable is IGN_FILE_PATH. The environment variable should be a set of colon (semicolon on windows) delimited paths. These paths will be used with the FindFile function. More...
 
void SetFindFileCallback (std::function< std::string(const std::string &)> _cb)
 Set the callback to use when ignition can't find a file. The callback should return a complete path to the requested file, or and empty string if the file was not found in the callback. The path should use platform-specific directory separators. More...
 
void SetFindFileURICallback (std::function< std::string(const std::string &)> _cb)
 Set the callback to use when ignition can't find a file uri. The callback should return a complete path to the requested file, or and empty string if the file was not found in the callback. The path should use platform-specific directory separators. More...
 
void SetPluginPathEnv (const std::string &_env)
 Set the plugin path environment variable to use. More...
 

Static Public Member Functions

static char Delimiter ()
 Get the delimiter that the current operating system uses to separate different paths from each other. More...
 
static std::string LocateLocalFile (const std::string &_filename, const std::vector< std::string > &_paths)
 look for a file in a set of search paths (not recursive) This method checks if a file exists in given directories. It does so by joining each path with the filename and checking if the file exists. If the file exists in multiple paths the first one is found. More...
 
static std::string NormalizeDirectoryPath (const std::string &_path)
 Format the directory path to use "/" as a separator with "/" at the end. More...
 
static std::list< std::stringPathsFromEnv (const std::string &_env)
 Return all paths given by an environment variable. More...
 

Detailed Description

Functions to handle getting system paths, keeps track of:

  • SystemPaths::pluginPaths - plugin library paths for common::WorldPlugin

Constructor & Destructor Documentation

◆ SystemPaths()

Constructor for SystemPaths.

◆ ~SystemPaths()

virtual ~SystemPaths ( )
virtual

Destructor.

Member Function Documentation

◆ AddFilePaths()

void AddFilePaths ( const std::string _path)

Add colon (semicolon on windows) delimited paths to find files. These paths will be used with the FindFile function.

Parameters
[in]_pathA colon (semicolon on windows) delimited string of paths. The path can have either forward slashes or platform- specific directory separators, both are okay.

◆ AddFindFileCallback()

void AddFindFileCallback ( std::function< std::string(const std::string &)>  _cb)

Add a callback to use when FindFile() can't find a file. The callback should return a full local path to the requested file, or and empty string if the file was not found in the callback. The path should use platform-specific directory separators. Callbacks will be called in the order they were added until a path is found (if a callback is set using SetFindFileCallback(), that one is called first).

Parameters
[in]_cbThe callback function, which takes a file path or URI and returns the full local path.

◆ AddFindFileURICallback()

void AddFindFileURICallback ( std::function< std::string(const URI &)>  _cb)

Add a callback to use when FindFileURI() can't find a file. The callback should return a full local path to the requested file, or and empty string if the file was not found in the callback. The path should use platform-specific directory separators. Callbacks will be called in the order they were added until a path is found (if a callback is set using SetFindFileURICallback(), that one is called first).

Parameters
[in]_cbThe callback function, which takes a file path or URI and returns the full local path.

◆ AddPluginPaths()

void AddPluginPaths ( const std::string _path)

Add colon (semicolon on windows) delimited paths to plugins.

Parameters
[in]_paththe directory to add

◆ AddSearchPathSuffix()

void AddSearchPathSuffix ( const std::string _suffix)

add _suffix to the list of path search suffixes

Parameters
[in]_suffixThe suffix to add

◆ ClearFilePaths()

void ClearFilePaths ( )

clear out SystemPaths::filePaths

◆ ClearPluginPaths()

void ClearPluginPaths ( )

clear out SystemPaths::pluginPaths

◆ Delimiter()

static char Delimiter ( )
static

Get the delimiter that the current operating system uses to separate different paths from each other.

◆ FilePathEnv()

std::string FilePathEnv ( ) const

Get the file path environment variable in use. The environment variable contains a set of colon (semicolon on windows) delimited paths. These paths are used with the FindFile functions.

Returns
Name of the environment variable
See also
SetFilePathEnv

◆ FilePaths()

const std::list<std::string>& FilePaths ( )

Get the file paths.

Returns
a list of paths (with forward slashes as directory separators)

◆ FindFile()

std::string FindFile ( const std::string _filename,
const bool  _searchLocalPath = true,
const bool  _verbose = true 
) const

Find a file in the set search paths (not recursive)

Parameters
[in]_filenameName of the file to find.
[in]_searchLocalPathTrue to search in the current working directory.
[in]_verboseFalse to omit console messages.
Returns
Returns full path name to file with platform-specific directory separators, or empty string on error.

◆ FindFileURI() [1/2]

std::string FindFileURI ( const std::string _uri) const

Find a file or path using a URI.

Parameters
[in]_urithe uniform resource identifier
Returns
Returns full path name to file with platform-specific directory separators, or an empty string if URI couldn't be found.
See also
FindFileURI(const URI &_uri)

◆ FindFileURI() [2/2]

std::string FindFileURI ( const URI _uri) const

Find a file or path using a URI. If URI is not an absolute path, the URI's path will be matched against all added paths and environment variables (including URI authority as needed).

Parameters
[in]_urithe uniform resource identifier
Returns
Returns full path name to file with platform-specific directory separators, or an empty string if URI couldn't be found.

◆ FindSharedLibrary()

std::string FindSharedLibrary ( const std::string _libName)

Find a shared library by name in the plugin paths.

This will try different combinations of library names on different platforms. For example searching for "MyLibName" may try finding "MyLibName", "libMyLibName.so", "MyLibName.dll", etc...

Parameters
[in]_libNameName of shared libary to look for
Returns
Path to file with platform-specific directory separators, or empty string on error.

◆ LocateLocalFile()

static std::string LocateLocalFile ( const std::string _filename,
const std::vector< std::string > &  _paths 
)
static

look for a file in a set of search paths (not recursive) This method checks if a file exists in given directories. It does so by joining each path with the filename and checking if the file exists. If the file exists in multiple paths the first one is found.

Parameters
[in]_filenameName of the file to find
[in]_pathspaths to look for the file
Returns
Returns a path that will work from the current directory or an empty string if the file was not found. The returned path will be normalized, i.e. backslashes will be substituted with forward slashes.

◆ LogPath()

std::string LogPath ( ) const

Get the log path. If IGN_LOG_PATH environment variable is set, then this path is used. If not, the path is $HOME/.ignition, and in case even HOME is not set, /tmp/ignition is used. If the directory does not exist, it is created in the constructor of SystemPaths.

Returns
the path

◆ NormalizeDirectoryPath()

static std::string NormalizeDirectoryPath ( const std::string _path)
static

Format the directory path to use "/" as a separator with "/" at the end.

Parameters
[in]_pathPath to normalize
Returns
Normalized path

◆ PathsFromEnv()

static std::list<std::string> PathsFromEnv ( const std::string _env)
static

Return all paths given by an environment variable.

Parameters
[in]_envEnvironment variable.
Returns
A list of paths listed by the environment variable.

◆ PluginPaths()

const std::list<std::string>& PluginPaths ( )

Get the plugin paths.

Returns
a list of paths (with forward slashes as directory separators)

◆ SetFilePathEnv()

void SetFilePathEnv ( const std::string _env)

Set the file path environment variable to use, and clears any previously set file paths. The default environment variable is IGN_FILE_PATH. The environment variable should be a set of colon (semicolon on windows) delimited paths. These paths will be used with the FindFile function.

Parameters
[in]_envname of the environment variable
See also
FilePathEnv

◆ SetFindFileCallback()

void SetFindFileCallback ( std::function< std::string(const std::string &)>  _cb)

Set the callback to use when ignition can't find a file. The callback should return a complete path to the requested file, or and empty string if the file was not found in the callback. The path should use platform-specific directory separators.

Parameters
[in]_cbThe callback function.
Deprecated:
Use AddFindFileCallback instead

◆ SetFindFileURICallback()

void SetFindFileURICallback ( std::function< std::string(const std::string &)>  _cb)

Set the callback to use when ignition can't find a file uri. The callback should return a complete path to the requested file, or and empty string if the file was not found in the callback. The path should use platform-specific directory separators.

Parameters
[in]_cbThe callback function.
Deprecated:
Use AddFindFileURICallback instead

◆ SetPluginPathEnv()

void SetPluginPathEnv ( const std::string _env)

Set the plugin path environment variable to use.

Parameters
[in]_envname of the environment variable

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