rll::application_dirs class
#include <rll/directories.h>

Class for getting location of system directories for a specific application.

ProjectDirs computes the location of cache, config or data directories for a specific application, which are derived from the standard directories and the name of the project/organization.

For example if user named Alice, the following code:

using rll::application_dirs;
using enum rll::application_dirs::dir;

auto dirs = application_dirs("com", "Foo Corp", "Bar App");
std::cout << dirs[config].string() << std::endl; // or std::cout << dirs.config_dir() <<
std::endl;

will produce the following output:

Linux:   '/home/alice/.config/barapp'
Windows: 'C:\\Users\\Alice\\AppData\\Roaming\\Foo Corp\\Bar App'
MacOS:   '/Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App'

Public types

enum class dir: u8 { cache, config, config_local, data, data_local, preferences, runtime, state }
Supported application directory types.

Constructors, destructors, conversion operators

application_dirs(std::string_view qualifier, std::string_view vendor, std::string_view app)
Creates an application_dirs class from values describing the project.
application_dirs(meta::project_meta const& meta) explicit
Creates an application_dirs class from values describing the project.

Public functions

auto cache_dir() const →  std::filesystem::path const&
Returns the path to the project's cache directory.
auto config_dir() const →  std::filesystem::path const&
Returns the path to the project's config directory.
auto config_local_dir() const →  std::filesystem::path const&
Returns the path to the project's config_local directory.
void create() const
Creates the directories if they do not exist.
auto data_dir() const →  std::filesystem::path const&
Returns the path to the project's data directory.
auto data_local_dir() const →  std::filesystem::path const&
Returns the path to the project's data_local directory.
auto get(dir d) const →  std::filesystem::path const&
Returns the path to the directory.
auto operator[](dir d) const →  std::filesystem::path const&
Returns the path to the directory.
auto preference_dir() const →  std::filesystem::path const&
Returns the path to the project's preference directory.
auto project_path() const →  std::filesystem::path const&
Returns the project path fragment used to compute the project's cache/config/data directories.
void remove() const
Removes the directories and their contents from the filesystem.
auto runtime_dir() const →  optional<std::filesystem::path> const&
Returns the path to the project's runtime directory.
auto state_dir() const →  optional<std::filesystem::path> const&
Returns the path to the project's state directory.

Enum documentation

enum class rll::application_dirs::dir: u8

Supported application directory types.

Enumerators
cache

Cache directory.
config

Config directory.
config_local

Local config directory.
data

Data directory.
data_local

Local data directory.
preferences

Preferences directory.
runtime

Runtime directory. Can be unavailable on some platforms.
state

State directory. Can be unavailable on some platforms.

Function documentation

rll::application_dirs::application_dirs(std::string_view qualifier, std::string_view vendor, std::string_view app)

Creates an application_dirs class from values describing the project.

Parameters
qualifier The reverse domain name notation of the application, excluding the organization or application name itself.
vendor The name of the organization that develops this application, or for which the application is developed.
app The name of the application itself.
Exceptions
std::runtime_error if no valid home directory could be retrieved from the operating system.

Example values of qualifier:

  • "com.example"
  • "org"
  • "uk.co"
  • "io"
  • ""

Example values of vendor:

  • "Foo Corp"
  • "Bar Ltd"
  • "Example Inc"

Example values of app:

  • "Bar App"
  • "Foo App"

rll::application_dirs::application_dirs(meta::project_meta const& meta) explicit

Creates an application_dirs class from values describing the project.

Parameters
meta The project meta data.
Exceptions
std::runtime_error if no valid home directory could be retrieved from the operating system.

std::filesystem::path const& rll::application_dirs::cache_dir() const

Returns the path to the project's cache directory.

Returns The path to the project's cache directory.

Values on different platforms:

  • Linux: $XDG_CACHE_HOME/project_path or $HOME/.cache/project_path, for example: /home/alice/.cache/barapp
  • MacOS: $HOME/Library/Caches/project_path, for example: /Users/Alice/Library/Caches/com.Foo-Corp.Bar-App
  • Windows: LOCALAPPDATA%\project_path\cache, for example: C:\Users\Alice\AppData\Local\Foo Corp\Bar App\cache

std::filesystem::path const& rll::application_dirs::config_dir() const

Returns the path to the project's config directory.

Returns The path to the project's config directory.

Values on different platforms:

  • Linux: $XDG_CONFIG_HOME/project_path or $HOME/.config/project_path, for example: /home/alice/.config/barapp
  • MacOS: $HOME/Library/Application Support/project_path, for example: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
  • Windows: APPDATA%\project_path\config, for example: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config

std::filesystem::path const& rll::application_dirs::config_local_dir() const

Returns the path to the project's config_local directory.

Returns The path to the project's config_local directory.

Values on different platforms:

  • Linux: $XDG_CONFIG_HOME/project_path or $HOME/.config/project_path, for example: /home/alice/.config/barapp
  • MacOS: $HOME/Library/Application Support/project_path, for example: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
  • Windows: LOCALAPPDATA%\project_path\config, for example: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config

std::filesystem::path const& rll::application_dirs::data_dir() const

Returns the path to the project's data directory.

Returns The path to the project's data directory.

Values on different platforms:

  • Linux: $XDG_DATA_HOME/project_path or $HOME/.local/share/project_path, for example: /home/alice/.local/share/barapp
  • MacOS: $HOME/Library/Application Support/project_path, for example: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
  • Windows: LOCALAPPDATA%\project_path\data, for example: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\data

std::filesystem::path const& rll::application_dirs::data_local_dir() const

Returns the path to the project's data_local directory.

Returns The path to the project's data_local directory.

Values on different platforms:

  • Linux: $XDG_DATA_HOME/project_path or $HOME/.local/share/project_path, for example: /home/alice/.local/share/barapp
  • MacOS: $HOME/Library/Application Support/project_path, for example: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
  • Windows: LOCALAPPDATA%\project_path\data, for example: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\data

std::filesystem::path const& rll::application_dirs::get(dir d) const

Returns the path to the directory.

Parameters
d The directory type.
Returns The path to the directory.
Exceptions
std::system_error If the directory does not exist on this platform.

std::filesystem::path const& rll::application_dirs::operator[](dir d) const

Returns the path to the directory.

Parameters
d The directory type.
Returns The path to the directory.
Exceptions
std::system_error If the directory does not exist on this platform.

std::filesystem::path const& rll::application_dirs::preference_dir() const

Returns the path to the project's preference directory.

Values on different platforms:

  • Linux: $XDG_CONFIG_HOME/project_path or $HOME/.config/project_path, for example: /home/alice/.config/barapp
  • MacOS: $HOME/Library/Preferences/project_path, for example: /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App
  • Windows: LOCALAPPDATA%\project_path\config, for example: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config

std::filesystem::path const& rll::application_dirs::project_path() const

Returns the project path fragment used to compute the project's cache/config/data directories.

Returns The project path.

The value is derived from the constructor call and is platform-dependent.

optional<std::filesystem::path> const& rll::application_dirs::runtime_dir() const

Returns the path to the project's runtime directory.

Returns The path to the project's runtime directory or none if it is not available.

The runtime directory contains transient, non-essential data (like sockets or named pipes) that is expected to be cleared when the user's session ends.
Values on different platforms:

  • Linux: XDG_RUNTIME_DIR/project_path, for example: /run/user/1001/barapp
  • MacOS: -
  • Windows: -

optional<std::filesystem::path> const& rll::application_dirs::state_dir() const

Returns the path to the project's state directory.

Returns The path to the project's state directory or none if it is not available.

The state directory contains data that should be retained between sessions (unlike the runtime directory), but may not be important/portable enough to be synchronized across machines (unlike the config/preferences/data directories).
Values on different platforms:

  • Linux: $XDG_STATE_HOME/project_path or $HOME/.local/state/project_path, for example: /home/alice/.local/state/barapp
  • MacOS: -
  • Windows: -