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