Skip to main content

MediaDirsExt

std::os::unix::fs

Trait MediaDirsExt 

Source 
pub trait MediaDirsExt: Sized {
    // Required methods
    fn xdg() -> Result<Self>;
    fn templates(&self) -> Option<&Path>;
    fn set_templates(&mut self, path: PathBuf) -> &mut Self;
}
ⓘ This trait cannot be implemented outside std.
🔬This is a nightly-only experimental API. (fs_media_dirs #162083)
Available on Unix only.
Expand description

XDG-specific extensions to fs::MediaDirs.

The XDG conventions are defined by the Freedesktop.org project through the xdg-user-dirs tool. This configuration is generally present on desktop Linux distributions, although adoption is less widespread than the base directory specification.

The XDG conventions are written to be usable on any Unix-like filesystem, thus this extension being provided in os::unix rather than os::linux. However, while some tooling does use XDG conventions on macOS, note that macOS has its own separate conventions for user directories. Consider carefully what conventions your users will expect your application to follow along with any legacy path compatibility you might need to support.

Required Methods§

Source

fn xdg() -> Result<Self>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Load the user directory paths according to the xdg-user-dirs tool.

This directly reads and parses the $XDG_CONFIG_HOME/user-dirs.dirs file as defined and maintained by the xdg-user-dirs tool.

§Errors

Errors if the user’s home directory cannot be determined or if the $XDG_CONFIG_HOME/user-dirs.dirs file cannot be read.

§Implementation-specific behavior

Only the format maintained by xdg-user-dirs-update is supported. Any configuration that does not match the expected format will result in loading an unspecified path or None for that directory. To be more specific:

  • Any line not in the format of XDG_{NAME}_DIR={path} where {NAME} is one of DESKTOP, DOWNLOAD, TEMPLATES, PUBLICSHARE, DOCUMENTS, MUSIC, PICTURES, or VIDEOS is ignored.
  • {path} must be a "-quoted shell-escaped path.
  • {path} may only start with / or $HOME/. A home-relative path is returned relative to env::home_dir; shell expansion is not performed.
  • A directory set to just $HOME marks it as removed, and results in a None value for that path.
  • If shell expansion syntax other than a leading $HOME is present, the produced directory path is unspecified. This is invalid config according to the xdg-user-dirs tooling.

This behavior may change in the future. One example change that we explicitly reserve the right to make is to load paths that we currently ignore, such as path formats that are not canonically supported by xdg-user-dirs but which may occur in manually-edited user-dirs.dirs.

Source

fn templates(&self) -> Option<&Path>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

The OS-privileged user “Templates” directory, often the Templates folder in the user’s home directory.

As a media directory, this should typically be used as a default path for file selection dialogs, not for automatically accessed file paths.

Source

fn set_templates(&mut self, path: PathBuf) -> &mut Self

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Set the paths for Self::templates.

§Panics

Panics if the provided path is not absolute.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§