Dire
Complete cross-platform solution for data and user directories discovery.
Loading...
Searching...
No Matches
dire Namespace Reference

Classes

struct  BaseDirsBundle
 
class  IReallyWantMyOwnPlatformProjectName
 
class  PlatformProjectName
 
struct  ProjectDirsBundle
 
struct  UserDirsBundle
 

Typedefs

using Path = std::filesystem::path
 
template<typename T >
using Optional = std::optional< T >
 

Functions

auto home_dir () -> Optional< Path >
 
auto cache_dir () -> Optional< Path >
 
auto config_dir () -> Optional< Path >
 
auto config_local_dir () -> Optional< Path >
 
auto data_dir () -> Optional< Path >
 
auto data_local_dir () -> Optional< Path >
 
auto preference_dir () -> Optional< Path >
 
auto executable_dir () -> Optional< Path >
 
auto runtime_dir () -> Optional< Path >
 
auto state_dir () -> Optional< Path >
 
auto name (std::string domain, std::string org, std::string app_name) -> PlatformProjectName
 
auto cache_dir (PlatformProjectName project_name) -> Optional< Path >
 
auto config_dir (PlatformProjectName project_name) -> Optional< Path >
 
auto config_local_dir (PlatformProjectName project_name) -> Optional< Path >
 
auto data_dir (PlatformProjectName project_name) -> Optional< Path >
 
auto data_local_dir (PlatformProjectName project_name) -> Optional< Path >
 
auto preference_dir (PlatformProjectName project_name) -> Optional< Path >
 
auto runtime_dir (PlatformProjectName project_name) -> Optional< Path >
 
auto state_dir (PlatformProjectName project_name) -> Optional< Path >
 
auto audio_dir () -> Optional< Path >
 
auto desktop_dir () -> Optional< Path >
 
auto document_dir () -> Optional< Path >
 
auto download_dir () -> Optional< Path >
 
auto picture_dir () -> Optional< Path >
 
auto video_dir () -> Optional< Path >
 
auto public_dir () -> Optional< Path >
 
auto font_dir () -> Optional< Path >
 
auto template_dir () -> Optional< Path >
 

Typedef Documentation

◆ Optional

template<typename T >
using dire::Optional = typedef std::optional<T>

◆ Path

using dire::Path = typedef std::filesystem::path

Function Documentation

◆ audio_dir()

auto dire::audio_dir ( ) -> Optional< Path >

Typically used to store audio files, programs which download and/or work with audio files may also use it.

Platform Method Example
Linux $XDG_MUSIC_DIR /home/foo/Music
Mac home_dir() + "/Music" /Users/Foo/Music
Windows Known Folder API FOLDERID_Music C:\Users\Foo\Music

◆ cache_dir() [1/2]

auto dire::cache_dir ( ) -> Optional< Path >

A directory for program caches.
Only caches should be stored here (files safe to delete, i.e. download caches), not files that are meant to be persisted.

For configuration files: config_dir, config_local_dir or preference_dir

  • Files used to alter the behaviour of the application to the user preferences.
  • The user may wish and typically does back up those.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_CACHE_HOME or $HOME/.cache /home/foo/.cache
Mac home_dir() + "/Library/Caches" /Users/Foo/Library/Caches
Windows Known Folder API FOLDERID_LocalAppData C:\Users\Foo\AppData\Local

◆ cache_dir() [2/2]

auto dire::cache_dir ( PlatformProjectName  project_name) -> Optional< Path >

A directory for program caches.
Only caches should be stored here (files safe to delete, i.e. download caches), not files that are meant to be persisted.

For configuration files: config_dir, config_local_dir or preference_dir

  • Files used to alter the behaviour of the application to the user preferences.
  • The user may wish and typically does back up those.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_CACHE_HOME or $HOME/.cache /home/foo/.cache
Mac home_dir() + "/Library/Caches" /Users/Foo/Library/Caches
Windows Known Folder API FOLDERID_LocalAppData C:\Users\Foo\AppData\Local

◆ config_dir() [1/2]

auto dire::config_dir ( ) -> Optional< Path >

A directory for program configuration files.
Only configuration files should be stored here, as users often back up this directory.

On linux and macOS this is the same as config_local_dir.
On windows this directory can be synchronized in a domain.

For applications that are meant for power users, developers, etc., prefer this. Otherwise, prefer preference_dir.
This matters on macOS as it stores the configuration files in $HOME/.config instead of $HOME/Library/Application Support.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_CONFIG_HOME or $HOME/.config /home/foo/.config
Mac home_dir() + "/.config" /Users/Foo/.config
Windows Known Folder API FOLDERID_RoamingAppData C:\Users\Foo\AppData\Roaming

◆ config_dir() [2/2]

auto dire::config_dir ( PlatformProjectName  project_name) -> Optional< Path >

A directory for program configuration files.
Only configuration files should be stored here, as users often back up this directory.

On linux and macOS this is the same as config_local_dir.
On windows this directory can be synchronized in a domain.

For applications that are meant for power users, developers, etc., prefer this. Otherwise, prefer preference_dir.
This matters on macOS as it stores the configuration files in $HOME/.config instead of $HOME/Library/Application Support.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_CONFIG_HOME or $HOME/.config /home/foo/.config
Mac home_dir() + "/.config" /Users/Foo/.config
Windows Known Folder API FOLDERID_RoamingAppData C:\Users\Foo\AppData\Roaming

◆ config_local_dir() [1/2]

auto dire::config_local_dir ( ) -> Optional< Path >

A directory for program configuration files for the current user only.
Only configuration files should be stored here, as users often back up this directory.

On linux and macOS this is the same as config_dir.
On windows this directory cannot be synchronized in the domain as opposed to config_dir.

For applications that are meant for power users, developers, etc., prefer this. Otherwise, prefer preference_dir.
This matters on macOS as it stores the configuration files in $HOME/.config instead of $HOME/Library/Application Support.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_CONFIG_HOME or $HOME/.config /home/foo/.config
Mac home_dir() + "/.config" /Users/Foo/.config
Windows Known Folder API FOLDERID_LocalAppData C:\Users\Foo\AppData\Local

◆ config_local_dir() [2/2]

auto dire::config_local_dir ( PlatformProjectName  project_name) -> Optional< Path >

A directory for program configuration files for the current user only.
Only configuration files should be stored here, as users often back up this directory.

On linux and macOS this is the same as config_dir.
On windows this directory cannot be synchronized in the domain as opposed to config_dir.

For applications that are meant for power users, developers, etc., prefer this. Otherwise, prefer preference_dir.
This matters on macOS as it stores the configuration files in $HOME/.config instead of $HOME/Library/Application Support.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_CONFIG_HOME or $HOME/.config /home/foo/.config
Mac home_dir() + "/.config" /Users/Foo/.config
Windows Known Folder API FOLDERID_LocalAppData C:\Users\Foo\AppData\Local

◆ data_dir() [1/2]

auto dire::data_dir ( ) -> Optional< Path >

A directory for program data files.
Used for files inherently portable across machines like icons, fonts, desktop entries and such.

On linux and macOS this is the same as data_local_dir.
On windows this directory can be synchronized in a domain.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For configuration files: config_dir, config_local_dir or preference_dir

  • Files used to alter the behaviour of the application to the user preferences.
  • The user may wish and typically does back up those.
Platform Method Example
Linux $XDG_DATA_HOME or $HOME/.local/share /home/foo/.local/share
Mac home_dir() + "/Library/Application Support" /Users/Foo/Library/Application Support
Windows Known Folder API FOLDERID_RoamingAppData C:\Users\Foo\AppData\Roaming

◆ data_dir() [2/2]

auto dire::data_dir ( PlatformProjectName  project_name) -> Optional< Path >

A directory for program data files.
Used for files inherently portable across machines like icons, fonts, desktop entries and such.

On linux and macOS this is the same as data_local_dir.
On windows this directory can be synchronized in a domain.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For configuration files: config_dir, config_local_dir or preference_dir

  • Files used to alter the behaviour of the application to the user preferences.
  • The user may wish and typically does back up those.
Platform Method Example
Linux $XDG_DATA_HOME or $HOME/.local/share /home/foo/.local/share
Mac home_dir() + "/Library/Application Support" /Users/Foo/Library/Application Support
Windows Known Folder API FOLDERID_RoamingAppData C:\Users\Foo\AppData\Roaming

◆ data_local_dir() [1/2]

auto dire::data_local_dir ( ) -> Optional< Path >

A directory for program data files for the current user only.
Used for files inherently portable across machines like icons, fonts, desktop entries and such.

On linux and macOS this is the same as data_dir.
On windows this directory cannot be synchronized in the domain as opposed to data_dir.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For configuration files: config_dir, config_local_dir or preference_dir

  • Files used to alter the behaviour of the application to the user preferences.
  • The user may wish and typically does back up those.
Platform Method Example
Linux $XDG_DATA_HOME or $HOME/.local/share /home/foo/.local/share
Mac home_dir() + "/Library/Application Support" /Users/Foo/Library/Application Support
Windows Known Folder API FOLDERID_LocalAppData C:\Users\Foo\AppData\Local

◆ data_local_dir() [2/2]

auto dire::data_local_dir ( PlatformProjectName  project_name) -> Optional< Path >

A directory for program data files for the current user only.
Used for files inherently portable across machines like icons, fonts, desktop entries and such.

On linux and macOS this is the same as data_dir.
On windows this directory cannot be synchronized in the domain as opposed to data_dir.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For configuration files: config_dir, config_local_dir or preference_dir

  • Files used to alter the behaviour of the application to the user preferences.
  • The user may wish and typically does back up those.
Platform Method Example
Linux $XDG_DATA_HOME or $HOME/.local/share /home/foo/.local/share
Mac home_dir() + "/Library/Application Support" /Users/Foo/Library/Application Support
Windows Known Folder API FOLDERID_LocalAppData C:\Users\Foo\AppData\Local

◆ desktop_dir()

auto dire::desktop_dir ( ) -> Optional< Path >

This is the directory whose contents are displayed on the desktop (on Linux desktops are not always available, which is typically the case for Tiling Window Managers).

Platform Method Example
Linux $XDG_DESKTOP_DIR /home/foo/Desktop
Mac home_dir() + "/Desktop" /Users/Foo/Desktop
Windows Known Folder API FOLDERID_Desktop C:\Users\Foo\Desktop

◆ document_dir()

auto dire::document_dir ( ) -> Optional< Path >

Used mostly for plaintext and text processor documents. Lots of other programs may use it as well, especially ones made for designing.

Platform Method Example
Linux $XDG_DOCUMENTS_DIR /home/foo/Documents
Mac home_dir() + "/Documents" /Users/Foo/Documents
Windows Known Folder API FOLDERID_Documents C:\Users\Foo\Documents

◆ download_dir()

auto dire::download_dir ( ) -> Optional< Path >

Mostly used by browsers for saved files. Some other programs may utilize it as well.

Platform Method Example
Linux $XDG_DOWNLOAD_DIR /home/foo/Downloads
Mac home_dir() + "/Downloads" /Users/Foo/Downloads
Windows Known Folder API FOLDERID_Downloads C:\Users\Foo\Downloads

◆ executable_dir()

auto dire::executable_dir ( ) -> Optional< Path >

A user writable directory for binaries. This is not officialy supported by the XDG specification!

This directory doesn't exist on windows and macOS!

Platform Method Example
Linux $XDG_BIN_HOME /home/foo/.local/bin
Mac nullopt nullopt
Windows nullopt nullopt

◆ font_dir()

auto dire::font_dir ( ) -> Optional< Path >

Directory for font files.

It doesn't exist on windows, as it doesn't have a one, standard directory for fonts.
They are typically put and found in \WINDIR%\Fonts - typically C:\Windows\Fonts
or \LOCALAPPDATA%\Microsoft\Windows\Fonts\ - typically C:\Users\Foo\AppData\Local\Microsoft\Windows\Fonts.

Platform Method Example
Linux $XDG_DATA_HOME/fonts or $HOME/.local/share/fonts /home/foo/Public
Mac home_dir() + "/Library/Fonts" /Users/Foo/Library/Fonts
Windows nullopt nullopt

◆ home_dir()

auto dire::home_dir ( ) -> Optional< Path >

◆ name()

auto dire::name ( std::string  domain,
std::string  org,
std::string  app_name 
) -> PlatformProjectName

Used to obtain a platform specific PlatformProjectName which is used for obtaining project specific directories for caches, configs and such.

If you want to override the name to your own one, initialize PlatformProjectName directly with IReallyWantMyOwnPlatformProjectName.

On linux only app_name is used and produces a name that is lowercased and with spaces removed. On windows only app_name and org are used and produces a path like domain / name without other modifications. On mac all three are used and produce a name like domain.org.app_name with all free segments lowercased and spaces replaced with hyphens. e.g. dire::name("me", "dich0tomy", "dire") will produce:

Platform Result
Linux dire
Mac me.dich0tomy.dire
Windows Dichotomy/Dire

◆ picture_dir()

auto dire::picture_dir ( ) -> Optional< Path >

Typically used by programs for downloading and manipulating images.

Platform Method Example
Linux $XDG_PICTURES_DIR /home/foo/Pictures
Mac home_dir() + "/Pictures" /Users/Foo/Pictures
Windows Known Folder API FOLDERID_Pictures C:\Users\Foo\Pictures

◆ preference_dir() [1/2]

auto dire::preference_dir ( ) -> Optional< Path >

A directory for program configuration files.
Only configuration files should be stored here, as users often back up this directory.

For applications that are meant for ordinary users prefer this.
For applications meant for developers and power users prefer config_dir or config_local_dir.
This matters on macOS as it stores the configuration files in $HOME/Library/Application Support instead of $HOME/.config.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_CACHE_HOME or $HOME/.cache /home/foo/.cache
Mac home_dir() + "/Library/Caches" /Users/Foo/Library/Caches
Windows Known Folder API FOLDERID_LocalAppData C:\Users\Foo\AppData\Local

◆ preference_dir() [2/2]

auto dire::preference_dir ( PlatformProjectName  project_name) -> Optional< Path >

A directory for program configuration files.
Only configuration files should be stored here, as users often back up this directory.

For applications that are meant for ordinary users prefer this.
For applications meant for developers and power users prefer config_dir or config_local_dir.
This matters on macOS as it stores the configuration files in $HOME/Library/Application Support instead of $HOME/.config.

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For state files: state_dir (doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir))

  • State of the app - logs, history and such.
  • Typically not portable files unique for the machine the app runs on.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_CACHE_HOME or $HOME/.cache /home/foo/.cache
Mac home_dir() + "/Library/Caches" /Users/Foo/Library/Caches
Windows Known Folder API FOLDERID_LocalAppData C:\Users\Foo\AppData\Local

◆ public_dir()

auto dire::public_dir ( ) -> Optional< Path >

A directory that all users have access to. This is especially useful for windows and mac which have native solutions for sharing these over network.

Platform Method Example
Linux $XDG_PUBLICSHARE_DIR /home/foo/Public
Mac home_dir() + "/Public" /Users/Foo/Public
Windows Known Folder API FOLDERID_Public C:\Users\Foo\Public

◆ runtime_dir() [1/2]

auto dire::runtime_dir ( ) -> Optional< Path >

Used for user-specific non-essential runtime files and other file objects (such as sockets, named pipes, ...)

  • The directory MUST be owned by the user, and the user MUST be the only one having read and write access to it
  • Its Unix access mode MUST be 0700
  • It should be used for communication and synchronization purposes
  • Large files should not be placed in here, since it might reside in runtime memory and cannot necessarily be swapped out to disk
  • It may be subject to periodic cleanup.

This directory doesn't exist on windows and macOS!

Platform Method Example
Linux $XDG_RUNTIME_DIR /run/foo/1000
Mac nullopt nullopt
Windows nullopt nullopt

◆ runtime_dir() [2/2]

auto dire::runtime_dir ( PlatformProjectName  project_name) -> Optional< Path >

Used for user-specific non-essential runtime files and other file objects (such as sockets, named pipes, ...)

  • The directory MUST be owned by the user, and the user MUST be the only one having read and write access to it
  • Its Unix access mode MUST be 0700
  • It should be used for communication and synchronization purposes
  • Large files should not be placed in here, since it might reside in runtime memory and cannot necessarily be swapped out to disk
  • It may be subject to periodic cleanup.

This directory doesn't exist on windows and macOS!

Platform Method Example
Linux $XDG_RUNTIME_DIR /run/foo/1000
Mac nullopt nullopt
Windows nullopt nullopt

◆ state_dir() [1/2]

auto dire::state_dir ( ) -> Optional< Path >

A directory for state files - logs, history and such.

This directory doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir).

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For configuration files: config_dir, config_local_dir or preference_dir

  • Files used to alter the behaviour of the application to the user preferences.
  • The user may wish and typically does back up those.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_STATE_HOME or $HOME/.local/state /home/foo/.local/state
Mac nullopt nullopt
Windows nullopt nullopt

◆ state_dir() [2/2]

auto dire::state_dir ( PlatformProjectName  project_name) -> Optional< Path >

A directory for state files - logs, history and such.

This directory doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir).

For cache files: cache_dir

  • Intermediate files created for more expensive processes.
  • Saved data used to speed up the application by not computing things unnecessarilly.
  • Generally cached files that the user will not care for.

For configuration files: config_dir, config_local_dir or preference_dir

  • Files used to alter the behaviour of the application to the user preferences.
  • The user may wish and typically does back up those.

For data files: data_dir, data_local_dir

  • Files portable across machines - icons, fonts, desktop entries and such.
Platform Method Example
Linux $XDG_STATE_HOME or $HOME/.local/state /home/foo/.local/state
Mac nullopt nullopt
Windows nullopt nullopt

◆ template_dir()

auto dire::template_dir ( ) -> Optional< Path >

Directory for user template files.

On linux users can drop all kinds of template files there, which the desktop environment then picks up and allows creating new documents based on them from a contextual menu.

On windows this folder is typically dependent on user programs, like the software from the Microsoft suite or its other alternatives - which means there's a bigger chance for it to fail!

Platform Method Example
Linux $XDG_TEMPLATES_DIR /home/foo/Templates
Mac nullopt nullopt
Windows Known Folder API FOLDERID_Templates C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates

◆ video_dir()

auto dire::video_dir ( ) -> Optional< Path >

Typically used by programs for downloading videos.

Mac has a special case here and names the dir Movies

Platform Method Example
Linux $XDG_VIDEOS_DIR /home/foo/Videos
Mac home_dir() + "/Pictures" /Users/Foo/Movies
Windows Known Folder API FOLDERID_Videos C:\Users\Foo\Videos