qi::path namespace

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

Summary

Global Namespaces

• namespace qi::path

  Functions (namespace qi::path)

  qi::path::sdkPrefix

  qi::path::findLib

  qi::path::convertToDosPath

  qi::path::libPaths

  qi::path::findConf

  qi::path::userWritableDataPath

  qi::path::confPaths

  qi::path::findBin

  qi::path::dataPaths

  qi::path::listLib

  qi::path::binPaths

  qi::path::findData

  qi::path::listData

  qi::path::userWritableConfPath

Global Classes

• class qi::Path

  Functions (class qi::Path)

  qi::Path::operator=

  qi::Path::dirs

  qi::Path::absolute

  qi::Path::operator/

  qi::Path::parent

  qi::Path::recursiveFiles

  qi::Path::isEmpty

  qi::Path::isDir

  qi::Path::str

  qi::Path::operator std::string

  qi::Path::extension

  qi::Path::isRegularFile

  qi::Path::exists

  qi::Path::operator!=

  qi::Path::isSymlink

  qi::Path::filename

  qi::Path::Path

  qi::Path::operator/=

  qi::Path::files

  qi::Path::operator==

  qi::Path::fromNative

  qi::Path::bfsPath

  qi::Path::~Path

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

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.