qi::path namespace

qi::path is a set of functions to find binaries, libraries, data and configuration files on the system.

Reference

qi::Path Class Reference

Introduction

The Path class allow handling filesystem path in a cross-platform maner. The class assume that all string are encoded in UTF-8 if not specified otherwise. More...

#include <qi/path.hpp>

Public Functions

Path(const std::string& unicodePath)
Path(const char* unicodePath)
Path(const Path& path)
Path(const boost::filesystem::path& path)
~Path()
bool isEmpty() const
bool exists() const
bool isDir() const
bool isRegularFile() const
bool isSymlink() const
std::string filename() const
std::string extension() const
Path parent() const
Path absolute() const
PathVector files() const
PathVector recursiveFiles() const
PathVector dirs() const
string() const
std::string str() const
const boost::filesystem::path& bfsPath() const
Path operator/(const qi::Path& rhs) const
const Path& operator/=(const qi::Path& rhs) const
const Path& operator=(const qi::Path& rhs) const
bool operator==(const qi::Path& rhs) const
bool operator!=(const qi::Path& rhs) const

Public Static Functions

Path fromNative(const char* nativeCharsPath)
Path fromNative(const wchar_t* nativeCharsPath)
Path fromNative(const std::string& nativeCharsPath)
Path fromNative(const std::wstring& nativeCharsPath)

Detailed Description

The Path class allow handling filesystem path in a cross-platform maner. The class assume that all string are encoded in UTF-8 if not specified otherwise.

Function Documentation

static Path qi::Path::fromNative(const char* nativeCharsPath)

Brief:

Returns:A unicode-safe path from a string containing a native encoding path instead of UTF-8.
static Path qi::Path::fromNative(const wchar_t* nativeCharsPath)

Brief:

Returns:A unicode-safe path from a string containing a native encoding path instead of UTF-8.
static Path qi::Path::fromNative(const std::string& nativeCharsPath)

Brief:

Returns:A unicode-safe path from a string containing a native encoding path instead of UTF-8.
static Path qi::Path::fromNative(const std::wstring& nativeCharsPath)

Brief:

Returns:A unicode-safe path from a string containing a native encoding path instead of UTF-8.
qi::Path::Path(const std::string& unicodePath = std::string()

Brief:

Parameters:
  • unicodePath – Path value as UTF-8 string.

Default Constructor

qi::Path::Path(const char* unicodePath)

Brief:

Parameters:
  • unicodePath – Path value as UTF-8 string.
qi::Path::Path(const Path& path)

Copy Constructor.

qi::Path::Path(const boost::filesystem::path& path)

Copy Constructor from boost filesystem.

qi::Path::~Path()

Default destructor.

bool qi::Path::isEmpty() const

is the path empty?

bool qi::Path::exists() const

does this file exist?

bool qi::Path::isDir() const

is the path a directory?

bool qi::Path::isRegularFile() const

is the path a regular file?

bool qi::Path::isSymlink() const

is the path a symlink?

std::string qi::Path::filename() const

Brief:

Returns:the last component of the path as an UTF-8 string
std::string qi::Path::extension() const

Brief:

Returns:the extension of the last component of the path as an UTF-8 string
Path qi::Path::parent() const

Brief:

Returns:a Path to the parent
Path qi::Path::absolute() const

Brief:

Returns:an absolute Path of the current path
PathVector qi::Path::files() const

Brief:

Returns:a vector of files contained in the current path
PathVector qi::Path::recursiveFiles() const

Brief:

Returns:a vector of absolute path to files contained recursively in the current path
PathVector qi::Path::dirs() const

Brief:

Returns:a vector of dirs contained in the current path
qi::Path::operator std::string() const

Brief:

Returns:the path as an UTF-8 string
std::string qi::Path::str() const

Brief:

Returns:the path as an UTF-8 string
const boost::filesystem::path& qi::Path::bfsPath() const

Brief:

Returns:the path as a boost path representation
Path qi::Path::operator/(const qi::Path& rhs) const

concat two paths adding a directory separator between them

const Path& qi::Path::operator/=(const qi::Path& rhs) const

concat two paths adding a directory separator between them

const Path& qi::Path::operator=(const qi::Path& rhs) const

copy operator

bool qi::Path::operator==(const qi::Path& rhs) const
bool qi::Path::operator!=(const qi::Path& rhs) const

qi::path Namespace Reference

Introduction

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

Inner Definitions

Namespaces
Name Brief
qi::path::detail Implementation detail.
Classes
Name Brief
qi::path::ScopedDir
qi::path::ScopedFile
Functions
Name Brief
qi::path::sdkPrefix Return the default SDK prefix path.
qi::path::findBin Look for a binary.
qi::path::findLib Look for a library.
qi::path::findConf Look for a configuration file.
qi::path::findData Look for a file in all dataPaths(applicationName) directories, return the first match.
qi::path::listData 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.
qi::path::listLib
qi::path::confPaths Get the list of directories used when searching for configuration files for the given application name.
qi::path::dataPaths Get the list of directories used when searching for data files for the given application name.
qi::path::binPaths Get the list of directories used when searching for binaries.
qi::path::libPaths Get the list of directories used when searching for libraries.
qi::path::userWritableDataPath Get the writable data files path for users.
qi::path::userWritableConfPath Get the writable configuration files path for users.
qi::path::convertToDosPath Convert given path into DOS 8.3 path if it exists, else returns empty string (Windows only).
qi::path::parseQiPathConf

Detailed Description

Set of tools to handle SDK layouts.

Functions

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

Brief: Return the default SDK prefix path.

Returns:The SDK prefix path. It’s always a complete, native path.
std::string qi::path::findBin(const std::string& name, bool searchInPath = false)

Brief: Look for a binary.

Parameters:
  • name – The full name of the binary, or just the name.
  • searchInPath – if 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::findLib(const std::string& name)

Brief: Look for a library.

Parameters:
  • name – The 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::string qi::path::findConf(const std::string& applicationName, const std::string& filename, bool excludeUserWritablePath = false)

Brief: Look for a configuration file.

Parameters:
  • applicationName – Name of the application.
  • filename – Name of the file to look for. You can specify subdirectories using “/” as directory separator.
  • excludeUserWritablePath – If 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)

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

Parameters:
  • applicationName – Name of the application.
  • filename – Name of the file to look for. You can specify subdirectories using “/” as directory separator.
  • excludeUserWritablePath – If true, findData() won’t search into userWritableDataPath.
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 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::vector<std::string> qi::path::listData(const std::string& applicationName, const std::string& pattern = "*", bool excludeUserWritablePath = false)

Brief: 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:
  • applicationName – Name of the application.
  • pattern – wilcard pattern of the files to look for.
  • excludeUserWritablePath – If 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 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::confPaths(const std::string& applicationName = "", bool excludeUserWritablePath = false)

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

Parameters:
  • applicationName – Name of the application.
  • excludeUserWritablePath – If true, confPaths() won’t include userWritableConfPath.
Returns:

List of configuration directories.

This is used by the qi::path::findConf(const std::string&, const std::string&).

Warning

You should not assume those directories exist, nor that they are writeable.

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

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

Parameters:
  • applicationName – Name of the application.
  • excludeUserWritablePath – If true, dataPaths() won’t include userWritableDataPath.
Returns:

A list of directories.

This is used by the qi::path::findData(const std::string&, const std::string&) and the 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::vector<std::string> qi::path::binPaths()

Brief: Get the list of directories used when searching for binaries.

Returns:A list of directories.

This is used by the 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::libPaths()

Brief: Get the list of directories used when searching for libraries.

Returns:A list of directories.

This is used by the qi::path::findLib(const std::string&).

Warning

You should not assume those directories exist, nor that they are writeable.

std::string qi::path::userWritableDataPath(const std::string& applicationName, const std::string& filename)

Brief: Get the writable data files path for users.

Parameters:
  • applicationName – The name of the application.
  • filename – The 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.

std::string qi::path::userWritableConfPath(const std::string& applicationName, const std::string& filename = "")

Brief: Get the writable configuration files path for users.

Parameters:
  • applicationName – The name of the application.
  • filename – The 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::convertToDosPath(const std::string& pathString)

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::parseQiPathConf(const std::string& pathConf)

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

« qi::os | C++ qi base API | qi::PeriodicTask »
« previous | up | next »