libqi-api  2.8.7.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Namespaces | Classes | Functions
qi::path Namespace Reference

Set of tools to handle SDK layouts. More...

Namespaces

 detail
 Implementation detail.
 

Classes

class  ScopedDir
 
class  ScopedFile
 

Functions

std::string sdkPrefix ()
 Return the default SDK prefix path. More...
 
std::string findBin (const std::string &name, bool searchInPath=false)
 Look for a binary. More...
 
std::string findLib (const std::string &name)
 Look for a library. More...
 
std::string findConf (const std::string &applicationName, const std::string &filename, bool excludeUserWritablePath=false)
 Look for a configuration file. More...
 
std::string findData (const std::string &applicationName, const std::string &filename, bool excludeUserWritablePath=false)
 Look for a file in all dataPaths(applicationName) directories, return the first match. More...
 
std::vector< std::string > listData (const std::string &applicationName, const std::string &pattern="*", bool excludeUserWritablePath=false)
 List data files matching the given pattern in all dataPaths(applicationName) directories. For each match, return the occurence from the first dataPaths prefix. Directories are discarded. More...
 
std::vector< std::string > listLib (const std::string &subfolder, const std::string &pattern="*")
 
std::vector< std::string > confPaths (const std::string &applicationName="", bool excludeUserWritablePath=false)
 Get the list of directories used when searching for configuration files for the given application name. More...
 
std::vector< std::string > dataPaths (const std::string &applicationName="", bool excludeUserWritablePath=false)
 Get the list of directories used when searching for data files for the given application name. More...
 
std::vector< std::string > binPaths ()
 Get the list of directories used when searching for binaries. More...
 
std::vector< std::string > libPaths ()
 Get the list of directories used when searching for libraries. More...
 
std::string userWritableDataPath (const std::string &applicationName, const std::string &filename)
 Get the writable data files path for users. More...
 
std::string userWritableConfPath (const std::string &applicationName, const std::string &filename="")
 Get the writable configuration files path for users. More...
 
std::string convertToDosPath (const std::string &pathString)
 Convert given path into DOS 8.3 path if it exists, else returns empty string (Windows only). More...
 
std::vector< std::string > parseQiPathConf (const std::string &prefix)
 

Detailed Description

Set of tools to handle SDK layouts.

Function Documentation

std::vector<std::string> qi::path::binPaths ( )

Get the list of directories used when searching for binaries.

Returns
A list of directories.
* This is used by the :cpp:func:`qi::path::findBin(const std::string&)`.
*
* .. warning:: You should not assume those directories exist, nor that they are
*    writeable.
* 
std::vector<std::string> qi::path::confPaths ( const std::string &  applicationName = "",
bool  excludeUserWritablePath = false 
)

Get the list of directories used when searching for configuration files for the given application name.

Parameters
applicationNameName of the application.
excludeUserWritablePathIf true, confPaths() won't include userWritableConfPath.
Returns
List of configuration directories.
* This is used by the :cpp:func:`qi::path::findConf(const std::string&, const std::string&)`.
*
* .. warning:: You should not assume those directories exist, nor
*    that they are writeable.
* 
std::string qi::path::convertToDosPath ( const std::string &  pathString)

Convert given path into DOS 8.3 path if it exists, else returns empty string (Windows only).

To use some API that doesn't support unicode on Windows, it is possible to convert a unicode path to an existing file into a DOS path without any accentuated characters. (for ex. "C:\test àé\" becomes "C:\TEST~1\" if it already exists)

On other platforms, simply return pathString.

std::vector<std::string> qi::path::dataPaths ( const std::string &  applicationName = "",
bool  excludeUserWritablePath = false 
)

Get the list of directories used when searching for data files for the given application name.

Parameters
applicationNameName of the application.
excludeUserWritablePathIf true, dataPaths() won't include userWritableDataPath.
Returns
A list of directories.
Remarks
For automatic tests, you can modify the user data path (e.g ~/.local/share/ on Unix systems) with :cpp:func:qi::path::detail::setWritablePath
* This is used by the :cpp:func:`qi::path::findData(const std::string&, const std::string&)`
* and the :cpp:func:`qi::path::listData(const std::string&, const std::string&)`.
*
* The list of paths is constructed like this:
*
* - first, a standard path in the home directory (like
*   ~/.local/share/<applicationName>/<filename>)
* - then <sdk_prefix>/share/<applicationName>/<filename> for each known SDK
*   prefix.
*
* .. warning:: You should not assume those directories exist,
*    nor that they are writeable.
* 
std::string qi::path::findBin ( const std::string &  name,
bool  searchInPath = false 
)

Look for a binary.

Parameters
nameThe full name of the binary, or just the name.
searchInPathif true, also search for the binary in the $PATH directories.
Returns
The complete, native path to the file found, an empty string otherwise.
* This will search in all SDK prefixes for a file named 'name'.
* It will then add '.exe' suffix if needed.
* (without '.exe') (in UTF-8).
* 
std::string qi::path::findConf ( const std::string &  applicationName,
const std::string &  filename,
bool  excludeUserWritablePath = false 
)

Look for a configuration file.

Parameters
applicationNameName of the application.
filenameName of the file to look for. You can specify subdirectories using "/" as directory separator.
excludeUserWritablePathIf true, findConf() won't search into userWritableConfPath.
Returns
The complete, native path of the file if it was found, an empty string otherwise.
* The file is searched in a list of possible directories,
* the first match is returned.
*
* The list of paths is constructed like this:
*
* - first, a standard path in the home directory (like
*   ~/.config/<applicationName>/<filename>)
* - then: <sdk_prefix>/etc/<applicationName>/<filename> for each known SDK
*   prefix.
* - then a standard path in the system. (like
*   /etc/<applicationName>/<filename>)
* 
std::string qi::path::findData ( const std::string &  applicationName,
const std::string &  filename,
bool  excludeUserWritablePath = false 
)

Look for a file in all dataPaths(applicationName) directories, return the first match.

Parameters
applicationNameName of the application.
filenameName of the file to look for. You can specify subdirectories using "/" as directory separator.
excludeUserWritablePathIf true, findData() won't search into userWritableDataPath.
Returns
The complete, native path of the file if it was found, an empty string otherwise.
Remarks
For automatic tests, you can modify the user data path to find data in (e.g. ~/.local/share/ on Unix systems) with :cpp:func:qi::path::detail::setWritablePath
* The file is searched in a list of possible directories, provided by the
* :cpp:func:`qi::path::dataPaths(const std::string&)`.
* The first match is returned.
*
* For instance if you have the following files on a unix system
*
* - ~/.local/share/foo/models/nao.xml
* - /usr/share/foo/models/nao.xml
*
* then listData("foo", "models/nao.xml") will return
*
* - ~/.local/share/foo/models/nao.xml
* 
std::string qi::path::findLib ( const std::string &  name)

Look for a library.

Parameters
nameThe full name of the library, or just the name.
Returns
The complete, native path to the file found, an empty string otherwise.
* This will search in all SDK prefixes for a file named 'name'.
* It will then add 'lib' prefix, and appropriated suffixes
* ('.dll' on windows, '.so' on linux, '.dylib' on mac).
* (without '.dll', '.so') (in UTF-8).
*
* You can specify subdirectories using "/" as directory separator
* (in UTF-8).
* 
std::vector<std::string> qi::path::libPaths ( )

Get the list of directories used when searching for libraries.

Returns
A list of directories.
* This is used by the :cpp:func:`qi::path::findLib(const std::string&)`.
*
* .. warning:: You should not assume those directories exist, nor that they are
*    writeable.
* 
std::vector<std::string> qi::path::listData ( const std::string &  applicationName,
const std::string &  pattern = "*",
bool  excludeUserWritablePath = false 
)

List data files matching the given pattern in all dataPaths(applicationName) directories. For each match, return the occurence from the first dataPaths prefix. Directories are discarded.

Parameters
applicationNameName of the application.
patternwilcard pattern of the files to look for.
excludeUserWritablePathIf true, listData() won't search into userWritableDataPath. You can specify subdirectories using "/" as directory separator.
Returns
An std::vector of the complete, native paths of the files that matched.
* Matches are searched in a list of possible directories, provided by the
* :cpp:func:`qi::path::dataPaths(const std::string&)`.
* When several matches collide, the first one is
* returned.
*
* For instance if you have the following files on a unix system
*
* - ~/.local/share/foo/models/mynao.xml
* - ~/.local/share/foo/models/myromeo_with_laser_head.xml
* - /usr/share/foo/models/mynao.xml
* - /usr/share/foo/models/myromeo.xml
*
* then listData("foo", "models/my*.xml") will return
*
* - ~/.local/share/foo/models/mynao.xml
* - ~/.local/share/foo/models/myromeo_with_laser_head.xml
* - /usr/share/foo/models/myromeo.xml
*
* note that /usr/share/foo/models/mynao.xml is not returned because a nao.xml file is already matched.
* 
std::vector<std::string> qi::path::listLib ( const std::string &  subfolder,
const std::string &  pattern = "*" 
)

same as listData but for libraries

std::vector<std::string> qi::path::parseQiPathConf ( const std::string &  prefix)

Recursively parse <sdk/share/qi/path.conf> files Generated by qibuild, this makes it possible to find files from the depencies build dir or sources

std::string qi::path::sdkPrefix ( )

Return the default SDK prefix path.

Returns
The SDK prefix path. It's always a complete, native path.
std::string qi::path::userWritableConfPath ( const std::string &  applicationName,
const std::string &  filename = "" 
)

Get the writable configuration files path for users.

Parameters
applicationNameThe name of the application.
filenameThe filename.
Returns
The directory or the file.
* If filename is empty, return the directory
* in which to write. Otherwise the path is constructed like this:
*
* Linux
*    <home>/.config/<applicatioName>/<filename>
*
* Windows
*    %AppData%\<applicatioName>\<filename>
*
* You can specify subdirectories using "/" as directory separator.
* 
std::string qi::path::userWritableDataPath ( const std::string &  applicationName,
const std::string &  filename 
)

Get the writable data files path for users.

Parameters
applicationNameThe name of the application.
filenameThe filename.
Returns
The directory or the file.
* If filename is empty, return the directory in which to write.
* Otherwise the path is constructed like this:
*
* Linux
*    <home>/.local/share/<applicationName>/<filename>
*
* Windows
*    %AppData%\<applicatioName>\<filename>
*
* You can specify subdirectories using "/" as directory separator.
*