Path

Contents

• Paths in general
• Resolve and extract paths
• Finding files or paths in MIRA distributions
• API Reference

Paths in general

A Path is mainly a typedef for to the boost::filesystem::path class. However, the path headers provide additional functionality to the boost classes.

Resolve and extract paths

Whenever one of your methods expects a file or a path as a parameter, you should use the Path class. Furthermore, you should always call resolvePath() before accessing or opening the file. This has the following advantages

• All symbolic links are resolved
• All environmental variables are resolved
• The path will be absolute
• All additional special variables MIRA provides are evaluated and resolved (like find see The find place holder)

void myFunction(const Path& path)
{
    Path resolved = resolvePath(path);
    if (boost::filesystem::exists(resolved))
        load(resolved);
}

Finding files or paths in MIRA distributions

MIRA uses project directories to store executables, libraries and installed config files. Since the environment variable MIRA_PATH should normally hold all paths that point to installation directories of different projects built with MIRA, it can be used to search for files (e.g. config files). There are multiple functions that can be used to search for files and directories in all installed MIRA projects (assuming MIRA_PATH is set correctly).

For the next examples assume the following directory structure:

root
  |
  |-mira1
  |  |--config
  |      |-robot
  |      |  |-file1.xml
  |      |  |-file2.xml
  |-mira2
     |--config
         |-robot
         |  |-file1.xml
         |  |-file3.xml

Additionally assume MIRA_PATH=/root/mira1:/root/mira2.

findProjectFile

findProjectFile(filename) will search for the first match of filename in the given subdirectory structure of all paths in MIRA_PATH. Therefore it concatenates each path contained in the MIRA_PATH with the filename and returns the first file found that matches the concatenated filename.

Path file = findProjectFile("config/robot/file1.xml"); // returns /root/mira1/config/robot/file1.xml

The above example will search for:

• /root/mira1/config/robot/file1.xml
• /root/mira2/config/robot/file1.xml

findProjectFiles

Like findProjectFile() findProjectFiles(filename) will concatenate filename with each path in the MIRA_PATH variable but will return all found files in the given subdirectory structure.

// returns
// /root/mira1/config/robot/file1.xml,
// /root/mira2/config/robot/file1.xml
std::vector<Path> files = findProjectFiles("config/robot/file1.xml");

// also wildcards are allowed
// returns 
// /root/mira1/config/robot/file1.xml,
// /root/mira1/config/robot/file2.xml,
// /root/mira2/config/robot/file1.xml,
// /root/mira2/config/robot/file3.xml
std::vector<Path> files = findProjectFiles("config/robot/file*.xml");

findProjectDirectory

findProjectDirectory(dirname) works like findProjectFile but for directories. It concatenates dirname with all paths contained in MIRA_PATH and returns the first existing folder matching the name.

Path path = findProjectDirectory("config/robot"); // returns /root/mira1/config/robot

The above example will search for:

• /root/mira1/config/robot
• /root/mira2/config/robot

findProjectDirectories

Like findProjectDirectory() findProjectDirectory(dirname) will concatenate dirname with each path in the MIRA_PATH variable but will return all found directories in the given subdirectory structure.

// returns
// /root/mira1/config/robot, 
// /root/mira2/config/robot
std::vector<Path> paths = findProjectDirectories("config/robot");

Find files or paths recursively in subdirectories

The findProjectFiles and findProjectDirectories functions allow to find files/directories that not only match the concatenation of the file-/dirname with all paths contained in the MIRA_PATH variable. This means that one can search for a file or directory structure recursively in any subpath of each MIRA_PATHs path.

// returns
// /root/mira1/config/robot/file1.xml,
// /root/mira2/config/robot/file1.xml
std::vector<Path> files = findProjectFiles("file1.xml", true);

// returns
// /root/mira1/config/robot,
// /root/mira2/config/robot
std::vector<Path> paths = findProjectDirectories("robot", true);

The above examples will look for file1.xml / robot in every subfolder of /root/mira1 and root/mira2.

The find place holder

resolvePath() automatically resolves a find placeholder. This placeholder can be used to search for files in the MIRA project dirs contained in the MIRA_PATH. The syntax is like the one of an environment variable:

Path p = resolvePath("${find etc/file1.xml}");

A find placeholder is resolved by calling findProjectPath(). findProjectPath() tries to first find a file using findProjectFile(). If no file is found, it uses findProjectDirectory() to look for a directory. If no directory is found, it will call findProjectFiles() with recursive mode set to true to look for files also in subdirectories. If no file is found, it finally calls findProjectDirectories() with recursive mode set to true. If no directory is found in subdirectories, an exception is thrown. If multiple matches (files or directories) are found it will also throw an exception.

The findpkg place holder

resolvePath() automatically resolves a findkg placeholder. This placeholder can be used to search for installed packages in the MIRA project dirs contained in the MIRA_PATH. The syntax is like the one of an environment variable:

Path p = resolvePath("${findpkg MyPackage}");

A findpkg placeholder is resolved by calling findPackage(). The placeholder is replaced by the root directory of the package. If no package is found an exception is thrown.