xdg.hpp

Go to the documentation of this file.

/*
 * Copyright 2020 Robert Bosch GmbH
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef CLOE_UTILITY_XDG_HPP_
#define CLOE_UTILITY_XDG_HPP_

#include <functional>  // for function
#include <string>      // for string
#include <vector>      // for vector<>

#include <boost/filesystem/path.hpp>  // for path, operator/

namespace cloe {
namespace utility {

enum class XdgError {
  RELATIVE_XDG_PATH,

  HOME_UNSET,

  EMPTY_DEFAULT
};

// The following xdg_* functions are implementation functions, and aren't meant
// to be used directly.
#ifdef __linux__
boost::filesystem::path xdg_temp_dir();
#endif

boost::filesystem::path xdg_getenv_path(const std::string& env);
boost::filesystem::path xdg_path(const std::string& env,
                                 const boost::filesystem::path& default_path);
std::vector<boost::filesystem::path> xdg_paths(const std::string& env,
                                               const std::string& default_paths);

/*
 * Make sure to ask `is_empty()` on the result.
 */
boost::filesystem::path xdg_find(const boost::filesystem::path& file,
                                 const std::vector<boost::filesystem::path>& dirs);

std::vector<boost::filesystem::path> xdg_findall(const boost::filesystem::path& file,
                                                 const std::vector<boost::filesystem::path>& dirs);

void xdg_merge(const boost::filesystem::path& file,
               const std::vector<boost::filesystem::path>& dirs, bool reverse,
               std::function<bool(const boost::filesystem::path&)> mergefn);

inline boost::filesystem::path config_home() {
#ifdef __linux__
  return xdg_path("XDG_CONFIG_HOME", "~/.config");
#elif WIN32
  return xdg_path("XDG_CONFIG_HOME", xdg_getenv_path("LOCALAPPDATA"));
#endif
}

inline boost::filesystem::path data_home() {
#ifdef __linux__
  return xdg_path("XDG_DATA_HOME", "~/.local/share");
#elif WIN32
  return xdg_path("XDG_DATA_HOME", xdg_getenv_path("LOCALAPPDATA"));
#endif
}

inline boost::filesystem::path cache_home() {
#ifdef __linux__
  return xdg_path("XDG_CACHE_HOME", "~/.cache");
#elif WIN32
  return xdg_path("XDG_CACHE_HOME", xdg_getenv_path("TEMP"));
#endif
}

inline boost::filesystem::path runtime_dir() {
#ifdef __linux__
  return xdg_path("XDG_RUNTIME_DIR", xdg_temp_dir());
#elif WIN32
  return xdg_path("XDG_CACHE_HOME", xdg_getenv_path("TEMP"));
#endif
}

inline std::vector<boost::filesystem::path> config_dirs() {
#ifdef __linux__
  return xdg_paths("XDG_CONFIG_DIRS", "/etc/xdg");
#elif WIN32
  return xdg_paths("XDG_CONFIG_DIRS", xdg_getenv_path("APPDATA").string());
#endif
}

inline std::vector<boost::filesystem::path> data_dirs() {
#ifdef __linux__
  return xdg_paths("XDG_DATA_DIRS", "/usr/local/share:/usr/share");
#elif WIN32
  return xdg_paths("XDG_DATA_DIRS", xdg_getenv_path("APPDATA").string());
#endif
}

inline std::vector<boost::filesystem::path> all_config_dirs() {
  auto xs = config_dirs();
  xs.insert(xs.begin(), config_home());
  return xs;
}

inline std::vector<boost::filesystem::path> all_data_dirs() {
  auto xs = data_dirs();
  xs.insert(xs.begin(), data_home());
  return xs;
}

/*
 * The user_* functions return the correct path for the given suffix name.
 *
 * This is useful if you want to create a file.
 */
inline boost::filesystem::path user_config(const boost::filesystem::path& file) {
  return config_home() / file;
}
inline boost::filesystem::path user_data(const boost::filesystem::path& file) {
  return data_home() / file;
}
inline boost::filesystem::path user_cache(const boost::filesystem::path& file) {
  return cache_home() / file;
}
inline boost::filesystem::path user_runtime(const boost::filesystem::path& file) {
  return runtime_dir() / file;
}

/*
 * The find_* functions return the most relevant path for the given suffix
 * name that exists.
 *
 * This is useful if you want to read a file.
 */
inline boost::filesystem::path find_config(const boost::filesystem::path& file) {
  return xdg_find(file, all_config_dirs());
}
inline boost::filesystem::path find_data(const boost::filesystem::path& file) {
  return xdg_find(file, all_data_dirs());
}
inline boost::filesystem::path find_cache(const boost::filesystem::path& file) {
  return xdg_find(file, std::vector<boost::filesystem::path>{cache_home()});
}
inline boost::filesystem::path find_runtime(const boost::filesystem::path& file) {
  return xdg_find(file, std::vector<boost::filesystem::path>{runtime_dir()});
}

/*
 * The find_all_config and find_all_data functions return for config and data
 * all paths that contain the name suffix.
 *
 * This is useful if you can read multiple instances of the config or data.
 */
inline std::vector<boost::filesystem::path> find_all_config(const boost::filesystem::path& file) {
  return xdg_findall(file, all_config_dirs());
}
inline std::vector<boost::filesystem::path> find_all_data(const boost::filesystem::path& file) {
  return xdg_findall(file, all_data_dirs());
}

/*
 * The merge_config and merge_data follow the same logic as the find_all_*
 * functions, except that instead of returning the paths, they repeatedly
 * apply the supplied function to the path.
 *
 * Because in merging, the most important file should be loaded last, there
 * is a reverse option. If the function returns false, the merging is aborted.
 */
inline void merge_config(const boost::filesystem::path& file,
                         std::function<bool(const boost::filesystem::path&)>
                             mergefn,
                         bool reverse = false) {
  xdg_merge(file, all_config_dirs(), reverse, mergefn);
}

inline void merge_data(const boost::filesystem::path& file,
                       std::function<bool(const boost::filesystem::path&)>
                           mergefn,
                       bool reverse = false) {
  xdg_merge(file, all_data_dirs(), reverse, mergefn);
}

}  // namespace utility
}  // namespace cloe

#endif  // CLOE_UTILITY_XDG_HPP_