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

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

Namespaces

 detail
 

Functions

std::string sdkPrefix ()
 Return the default SDK prefix path. More...
 
std::string findBin (const std::string &name)
 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)
 Look for a configuration file. More...
 
std::string findData (const std::string &applicationName, const std::string &filename)
 
std::vector< std::string > listData (const std::string &applicationName, const std::string &pattern="*")
 
std::vector< std::string > confPaths (const std::string &applicationName="")
 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="")
 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...
 
void setWritablePath (const std::string &path)
 Set the writable files path for users. 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)
 

Detailed Description

Set of tools to handle SDK layouts.

* .. note::
*     Every string MUST be encoded in UTF-8. Every returned string are encoded in UTF-8.
* 

Function Documentation

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.
* 
qi::path::confPaths ( const std::string &  applicationName = "")

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

Parameters
applicationNameName of the application.
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.
* 
Examples:
qipath_example.cpp.
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.

qi::path::dataPaths ( const std::string &  applicationName = "")

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

Parameters
applicationNameName of the application.
Returns
A list of directories.
* 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.
* 
qi::path::findBin ( const std::string &  name)

Look for a binary.

Parameters
nameThe full name of the binary, 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 '.exe' suffix if needed.
* (without '.exe') (in UTF-8).
* 
qi::path::findConf ( const std::string &  applicationName,
const std::string &  filename 
)

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.
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>)
* 
Examples:
qipath_example.cpp.
qi::path::findData ( const std::string &  applicationName,
const std::string &  filename 
)

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.
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, 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.

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.
* 
qi::path::listData ( const std::string &  applicationName,
const std::string &  pattern = "*" 
)

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. 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/nao.xml
*   ~/.local/share/foo/models/romeo_with_laser_head.xml
*   /usr/share/foo/models/nao.xml
*   /usr/share/foo/models/romeo.xml
*
* then listData("foo", "models/*.xml") will return
*
*   ~/.local/share/foo/models/nao.xml
*   ~/.local/share/foo/models/romeo_with_laser_head.xml
*   /usr/share/foo/models/romeo.xml
* 
qi::path::sdkPrefix ( )

Return the default SDK prefix path.

Returns
The SDK prefix path. It's always a complete, native path.
Examples:
qipath_example.cpp.
void qi::path::setWritablePath ( const std::string &  path)

Set the writable files path for users.

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.
* 
Examples:
qipath_example.cpp.
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.
*