Directories

https://docs.rs/directories/
Admin
Directories is a Rust library that provides platform-specific, user-accessible locations for finding...
Tokens:21,894
Snippets:157
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: Using ProjectDirs::from to get config_dir

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Shows how to create a ProjectDirs instance and call config_dir. The example uses user Alice and ProjectDirs::from("com", "Foo Corp", "Bar App"). Output paths for Linux, Windows, and macOS are shown in comments.

```rust
use directories::ProjectDirs;
if let Some(proj_dirs) = ProjectDirs::from("com", "Foo Corp",  "Bar App") {
    proj_dirs.config_dir();
    // 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
}
```

--------------------------------

### Using UserDirs::new() to access user directories

Source: https://docs.rs/directories/latest/directories/struct.UserDirs.html

Shows how to create a `UserDirs` instance and call `audio_dir()`. The example is computed with a user named Alice and shows expected paths on Linux, Windows, and macOS. `UserDirs::new()` returns `None` if no valid home directory can be retrieved.

```rust
use directories::UserDirs;
if let Some(user_dirs) = UserDirs::new() {
    user_dirs.audio_dir();
    // Linux:   /home/alice/Music
    // Windows: C:\Users\Alice\Music
    // macOS:   /Users/Alice/Music
}
```

--------------------------------

### Get config directory with BaseDirs::new()

Source: https://docs.rs/directories/latest/directories/struct.BaseDirs.html

Example usage of BaseDirs::new() to get the config directory. The example assumes a user named Alice and shows the expected paths on Linux, Windows, and macOS. Use ProjectDirs instead for project-specific directories.

```rust
use directories::BaseDirs;
if let Some(base_dirs) = BaseDirs::new() {
    base_dirs.config_dir();
    // Linux:   /home/alice/.config
    // Windows: C:\Users\Alice\AppData\Roaming
    // macOS:   /Users/Alice/Library/Application Support
}
```

--------------------------------

### Test ProjectDirs initialization

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Unit tests for verifying ProjectDirs::from with various qualifier, organization, and application name combinations.

```rust
#[test]
fn test_project_dirs() {
    let proj_dirs = ::ProjectDirs::from("qux", "FooCorp", "BarApp");
    println!("ProjectDirs::from(\"qux\", \"FooCorp\", \"BarApp\")\n{:?}", proj_dirs);
    let proj_dirs = ::ProjectDirs::from("qux.zoo", "Foo Corp", "Bar-App");
    println!("ProjectDirs::from(\"qux.zoo\", \"Foo Corp\", \"Bar-App\")\n{:?}", proj_dirs);
    let proj_dirs = ::ProjectDirs::from("com", "Foo Corp.", "Bar App");
    println!("ProjectDirs::from(\"com\", \"Foo Corp.\", \"Bar App\")\n{:?}", proj_dirs);
}
```

--------------------------------

### ProjectDirs::from()

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Creates a new `ProjectDirs` instance computing the location of cache, config, or data directories for a specific application, derived from standard directories and the project/organization name. Returns `Option<ProjectDirs>`.

```APIDOC
## ProjectDirs::from()

### Description
Creates a new `ProjectDirs` instance computing the location of cache, config, or data directories for a specific application, derived from standard directories and the project/organization name.

### Method
Factory function

### Signature
`pub fn from(qualifier: &str, organization: &str, application: &str) -> Option<ProjectDirs>`

### Parameters
- `qualifier` (&str) - Required - The qualifier (e.g., reverse domain name) for the project.
- `organization` (&str) - Required - The organization name.
- `application` (&str) - Required - The application name.

### Returns
- `Option<ProjectDirs>` - `Some(ProjectDirs)` if the directories could be determined, `None` otherwise.

### Example
```rust
use directories::ProjectDirs;
if let Some(proj_dirs) = ProjectDirs::from("com", "Foo Corp",  "Bar App") {
    proj_dirs.config_dir();
    // 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
}
```
```

--------------------------------

### project_dirs_from function

Source: https://docs.rs/directories/latest/src/directories/lin.rs.html

Helper to create ProjectDirs from application name by normalizing the input string.

```rust
pub fn project_dirs_from(_qualifier: &str, _organization: &str, application: &str) -> Option<ProjectDirs> {
    ProjectDirs::from_path(PathBuf::from(&trim_and_lowercase_then_replace_spaces(application, "")))
}
```

--------------------------------

### Implement state_dir method

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the state directory path based on the operating system, returning None if not applicable.

```rust
pub fn state_dir(&self) -> Option<&Path> {
    self.state_dir.as_ref().map(|p| p.as_path())
}
```

--------------------------------

### Test UserDirs initialization

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Unit test for verifying UserDirs::new() output.

```rust
#[test]
fn test_user_dirs() {
    println!("UserDirs::new())\n{:?}", ::UserDirs::new());
}
```

--------------------------------

### UserDirs::new()

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Creates a new `UserDirs` instance providing paths of user-facing standard directories, following the conventions of the operating system. Returns `Option<UserDirs>`.

```APIDOC
## UserDirs::new()

### Description
Creates a new `UserDirs` instance providing paths of user-facing standard directories, following the conventions of the operating system the library is running on.

### Method
Factory function

### Signature
`pub fn new() -> Option<UserDirs>`

### Returns
- `Option<UserDirs>` - `Some(UserDirs)` if the directories could be determined, `None` otherwise.

### Example
```rust
use directories::UserDirs;
if let Some(user_dirs) = UserDirs::new() {
    user_dirs.audio_dir();
    // Linux:   /home/alice/Music
    // Windows: C:\Users\Alice\Music
    // macOS:   /Users/Alice/Music
}
```
```

--------------------------------

### ProjectDirs::config_dir

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the path to the project's configuration directory. The location varies by platform: Linux uses $XDG_CONFIG_HOME or $HOME/.config, macOS uses $HOME/Library/Application Support, and Windows uses {FOLDERID_LocalAppData}\config.

```APIDOC
## ProjectDirs::config_dir

### Description
Returns the path to the project's configuration directory.

### Method Signature
pub fn config_dir(&self) -> &Path

### Platform Paths
| Platform | Value | Example |
| --- | --- | --- |
| Linux | $XDG_CONFIG_HOME/_project_path_ or $HOME/.config/_project_path_ | /home/alice/.config/barapp |
| macOS | $HOME/Library/Application Support/_project_path_ | /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App |
| Windows | {FOLDERID_LocalAppData}\_project_path_\config | C:\Users\Alice\AppData\Local\Foo Corp\Bar App\config |

### Returns
- **&Path** - The path to the configuration directory.
```

--------------------------------

### ProjectDirs::video_dir

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the path to the user's video directory. The path is platform-dependent and follows the conventions shown in the documentation.

```APIDOC
## ProjectDirs::video_dir

### Description
Returns the path to the user's video directory. The path is platform-dependent and follows the conventions shown in the documentation.

### Method Signature
pub fn video_dir(&self) -> Option<&Path>

### Return Value
- **Option<&Path>** - Some containing the path to the video directory, or None if not available.

### Platform Values
| Platform | Value | Example |
| -------- | ----- | ------- |
| macOS | $HOME/Movies | /Users/Alice/Movies |
| Windows | {FOLDERID_Videos} | C:\Users\Alice\Videos |

```

--------------------------------

### ProjectDirs::from

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Creates a ProjectDirs struct from values describing the project. The returned value depends on the operating system and is either Some containing project directory paths based on the state of the system's paths at the time new() was invoked, or None if no valid home directory path could be retrieved from the operating system.

```APIDOC
## ProjectDirs::from

### Description
Creates a ProjectDirs struct from values describing the project. The returned value depends on the operating system and is either Some containing project directory paths based on the state of the system's paths at the time new() was invoked, or None if no valid home directory path could be retrieved from the operating system. The use of this method (instead of ProjectDirs::from_path) is strongly encouraged, as its results will follow operating system standards on Linux, macOS and Windows.

### Method
from

### Signature
pub fn from(qualifier: &str, organization: &str, application: &str) -> Option<ProjectDirs>

### Parameters
- **qualifier** (&str) - Required - The reverse domain name notation of the application, excluding the organization or application name itself. An empty string can be passed if no qualifier should be used (only affects macOS). Example values: "com.example", "org", "uk.co", "io", "".
- **organization** (&str) - Required - The name of the organization that develops this application, or for which the application is developed. An empty string can be passed if no organization should be used (only affects macOS and Windows). Example values: "Foo Corp", "Alice and Bob Inc", "".
- **application** (&str) - Required - The name of the application itself. Example values: "Bar App", "ExampleProgram", "Unicorn-Programme".

### Returns
- **Option<ProjectDirs>** - Some if the project directories could be created, None otherwise.

```

--------------------------------

### ProjectDirs::preference_dir

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the path to the project's preference directory. The location varies by platform: Linux uses $XDG_CONFIG_HOME or $HOME/.config, macOS uses $HOME/Library/Preferences, and Windows uses {FOLDERID_RoamingAppData}\config.

```APIDOC
## ProjectDirs::preference_dir

### Description
Returns the path to the project's preference directory.

### Method Signature
pub fn preference_dir(&self) -> &Path

### Platform Paths
| Platform | Value | Example |
| --- | --- | --- |
| Linux | $XDG_CONFIG_HOME/_project_path_ or $HOME/.config/_project_path_ | /home/alice/.config/barapp |
| macOS | $HOME/Library/Preferences/_project_path_ | /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App |
| Windows | {FOLDERID_RoamingAppData}\_project_path_\config | C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config |

### Returns
- **&Path** - The path to the preference directory.
```

--------------------------------

### project_dirs_from_path function

Source: https://docs.rs/directories/latest/src/directories/lin.rs.html

Constructs project-specific directory paths by appending a project path to standard XDG base directories.

```rust
pub fn project_dirs_from_path(project_path: PathBuf) -> Option<ProjectDirs> {
    if let Some(home_dir)    = dirs_sys::home_dir() {
        let cache_dir        = env::var_os("XDG_CACHE_HOME") .and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".cache")).join(&project_path);
        let config_dir       = env::var_os("XDG_CONFIG_HOME").and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".config")).join(&project_path);
        let config_local_dir = config_dir.clone();
        let data_dir         = env::var_os("XDG_DATA_HOME")  .and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".local/share")).join(&project_path);
        let data_local_dir   = data_dir.clone();
        let preference_dir   = config_dir.clone();
        let runtime_dir      = env::var_os("XDG_RUNTIME_DIR").and_then(dirs_sys::is_absolute_path).map(|o| o.join(&project_path));
        let state_dir        = env::var_os("XDG_STATE_HOME") .and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".local/state")).join(&project_path);

        let project_dirs = ProjectDirs {
            project_path:     project_path,
            cache_dir:        cache_dir,
            config_dir:       config_dir,
            config_local_dir: config_local_dir,
            data_dir:         data_dir,
            data_local_dir:   data_local_dir,
            preference_dir:   preference_dir,
            runtime_dir:      runtime_dir,
            state_dir:        Some(state_dir)
        };
        Some(project_dirs)
    } else {
        None
    }
}
```

--------------------------------

### desktop_dir

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the path to the user's desktop directory. Platform-specific values: Linux uses XDG_DESKTOP_DIR, macOS uses $HOME/Desktop, Windows uses {FOLDERID_Desktop}.

```APIDOC
## desktop_dir

### Description
Returns the path to the user's desktop directory.

### Method Signature
pub fn desktop_dir(&self) -> Option<&Path>

### Platform Values
| Platform | Value                | Example                |
| ------- | -------------------- | ---------------------- |
| Linux   | XDG_DESKTOP_DIR      | /home/alice/Desktop    |
| macOS   | $HOME/Desktop        | /Users/Alice/Desktop   |
| Windows | {FOLDERID_Desktop}   | C:\Users\Alice\Desktop |

### Returns
Option<&Path> - The path to the desktop directory, or None if not available.
```

--------------------------------

### preference_dir

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Returns the path to the project's preference directory. The path is platform-specific and based on environment variables or standard locations.

```APIDOC
## preference_dir

### Description
Returns the path to the project's preference directory.

### Method
pub fn preference_dir(&self) -> &Path

### Parameters
None

### Return Value
&Path - The path to the project's preference directory.

### Platform Values
- Linux: $XDG_CONFIG_HOME/_project_path_ or $HOME/.config/_project_path_ (e.g., /home/alice/.config/barapp)
- macOS: $HOME/Library/Preferences/_project_path_ (e.g., /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App)
- Windows: {FOLDERID_RoamingAppData}\_project_path_\config (e.g., C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config)
```

--------------------------------

### video_dir

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the path to the user's video directory. Platform-specific values: Linux uses XDG_VIDEOS_DIR, macOS uses $HOME/Videos, Windows uses {FOLDERID_Videos}.

```APIDOC
## video_dir

### Description
Returns the path to the user's video directory.

### Method Signature
pub fn video_dir(&self) -> Option<&Path>

### Platform Values
| Platform | Value               | Example               |
| ------- | ------------------- | --------------------- |
| Linux   | XDG_VIDEOS_DIR      | /home/alice/Videos    |
| macOS   | $HOME/Videos        | /Users/Alice/Videos   |
| Windows | {FOLDERID_Videos}   | C:\Users\Alice\Videos |

### Returns
Option<&Path> - The path to the video directory, or None if not available.
```

--------------------------------

### trim_and_lowercase_then_replace_spaces function

Source: https://docs.rs/directories/latest/src/directories/lin.rs.html

Internal utility to format application names for directory path usage.

```rust
fn trim_and_lowercase_then_replace_spaces(name: &str, replacement: &str) -> String {
```

--------------------------------

### ProjectDirs::config_dir

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Returns the path to the project's config directory. The path is platform-specific and follows operating system standards.

```APIDOC
## ProjectDirs::config_dir

### Description
Returns the path to the project's config directory. The path is platform-specific and follows operating system standards.

### Method
config_dir

### Signature
pub fn config_dir(&self) -> &Path

### Returns
- **&Path** - The path to the config directory.

### Platform Values
- **Linux**: $XDG_CONFIG_HOME/_project_path_ or $HOME/.config/_project_path_ - Example: /home/alice/.config/barapp
- **macOS**: $HOME/Library/Application Support/_project_path_ - Example: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
- **Windows**: {FOLDERID_RoamingAppData}\_project_path_\config - Example: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config

```

--------------------------------

### Test BaseDirs initialization

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Unit test for verifying BaseDirs::new() output.

```rust
#[test]
fn test_base_dirs() {
    println!("BaseDirs::new())\n{:?}", ::BaseDirs::new());
}
```

--------------------------------

### user_dirs function

Source: https://docs.rs/directories/latest/src/directories/lin.rs.html

Resolves standard user directories such as audio, desktop, and documents by querying the system and XDG data paths.

```rust
pub fn user_dirs() -> Option<UserDirs> {
    if let Some(home_dir) = dirs_sys::home_dir() {
        let data_dir  = env::var_os("XDG_DATA_HOME").and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".local/share"));
        let font_dir  = data_dir.join("fonts");
        let mut user_dirs_map = dirs_sys::user_dirs(&home_dir);

        let user_dirs = UserDirs {
            home_dir:     home_dir,
            audio_dir:    user_dirs_map.remove("MUSIC"),
            desktop_dir:  user_dirs_map.remove("DESKTOP"),
            document_dir: user_dirs_map.remove("DOCUMENTS"),
            download_dir: user_dirs_map.remove("DOWNLOAD"),
            font_dir:     Some(font_dir),
            picture_dir:  user_dirs_map.remove("PICTURES"),
            public_dir:   user_dirs_map.remove("PUBLICSHARE"),
            template_dir: user_dirs_map.remove("TEMPLATES"),
            video_dir:    user_dirs_map.remove("VIDEOS")
        };
        Some(user_dirs)
    } else {
        None
    }
}
```

--------------------------------

### BaseDirs::new()

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Creates a new `BaseDirs` instance providing paths of user-invisible standard directories, following the conventions of the operating system. Returns `Option<BaseDirs>`.

```APIDOC
## BaseDirs::new()

### Description
Creates a new `BaseDirs` instance providing paths of user-invisible standard directories, following the conventions of the operating system the library is running on.

### Method
Factory function

### Signature
`pub fn new() -> Option<BaseDirs>`

### Returns
- `Option<BaseDirs>` - `Some(BaseDirs)` if the directories could be determined, `None` otherwise.

### Example
```rust
use directories::BaseDirs;
if let Some(base_dirs) = BaseDirs::new() {
    base_dirs.config_dir();
    // Linux:   /home/alice/.config
    // Windows: C:\Users\Alice\AppData\Roaming
    // macOS:   /Users/Alice/Library/Application Support
}
```
```

--------------------------------

### ProjectDirs::data_dir

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the path to the project's data directory. The location varies by platform: Linux uses $XDG_DATA_HOME or $HOME/.local/share, macOS uses $HOME/Library/Application Support, and Windows uses {FOLDERID_RoamingAppData}\data.

```APIDOC
## ProjectDirs::data_dir

### Description
Returns the path to the project's data directory.

### Method Signature
pub fn data_dir(&self) -> &Path

### Platform Paths
| Platform | Value | Example |
| --- | --- | --- |
| Linux | $XDG_DATA_HOME/_project_path_ or $HOME/.local/share/_project_path_ | /home/alice/.local/share/barapp |
| macOS | $HOME/Library/Application Support/_project_path_ | /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App |
| Windows | {FOLDERID_RoamingAppData}\_project_path_\data | C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\data |

### Returns
- **&Path** - The path to the data directory.
```

--------------------------------

### ProjectDirs::from_path

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Creates a ProjectDirs struct directly from a PathBuf value. The argument is used verbatim and is not adapted to operating system standards. Its use is strongly discouraged; use ProjectDirs::from instead.

```APIDOC
## ProjectDirs::from_path

### Description
Creates a ProjectDirs struct directly from a PathBuf value. The argument is used verbatim and is not adapted to operating system standards. The use of this method is strongly discouraged, as its results will not follow operating system standards on at least two of three platforms. Use ProjectDirs::from instead.

### Method
from_path

### Signature
pub fn from_path(project_path: PathBuf) -> Option<ProjectDirs>

### Parameters
- **project_path** (PathBuf) - Required - The path to use verbatim for the project directories.

### Returns
- **Option<ProjectDirs>** - Some if the project directories could be created, None otherwise.

```

--------------------------------

### download_dir

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the path to the user's download directory. Platform-specific values: Linux uses XDG_DOWNLOAD_DIR, macOS uses $HOME/Downloads, Windows uses {FOLDERID_Downloads}.

```APIDOC
## download_dir

### Description
Returns the path to the user's download directory.

### Method Signature
pub fn download_dir(&self) -> Option<&Path>

### Platform Values
| Platform | Value                  | Example                  |
| ------- | ---------------------- | ------------------------ |
| Linux   | XDG_DOWNLOAD_DIR       | /home/alice/Downloads    |
| macOS   | $HOME/Downloads        | /Users/Alice/Downloads   |
| Windows | {FOLDERID_Downloads}   | C:\Users\Alice\Downloads |

### Returns
Option<&Path> - The path to the download directory, or None if not available.
```

--------------------------------

### UserDirs::new

Source: https://docs.rs/directories/latest/directories/struct.UserDirs.html

Creates a UserDirs struct that holds paths to user-facing directories. Returns None if no valid home directory path can be retrieved.

```APIDOC
## UserDirs::new

### Description
Creates a `UserDirs` struct which holds the paths to user-facing directories for audio, font, video, etc. data on the system. The returned value depends on the operating system and is either `Some`, containing a snapshot of the state of the system's paths at the time `new()` was invoked, or `None`, if no valid home directory path could be retrieved from the operating system.

### Method
`pub fn new() -> Option<UserDirs>`

### Returns
- `Option<UserDirs>` - `Some` if a valid home directory path could be retrieved, otherwise `None`.

### Example
```rust
use directories::UserDirs;
if let Some(user_dirs) = UserDirs::new() {
    user_dirs.audio_dir();
    // Linux:   /home/alice/Music
    // Windows: C:\Users\Alice\Music
    // macOS:   /Users/Alice/Music
}
```
```

--------------------------------

### runtime_dir

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Returns the path to the project's runtime directory, which contains transient, non-essential data. Returns None on platforms where this directory is not defined.

```APIDOC
## runtime_dir

### Description
Returns the path to the project's runtime directory. 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.

### Method
pub fn runtime_dir(&self) -> Option<&Path>

### Parameters
None

### Return Value
Option<&Path> - The path to the project's runtime directory, or None if not available.

### Platform Values
- Linux: $XDG_RUNTIME_DIR/_project_path_ (e.g., /run/user/1001/barapp)
- macOS: - (not available)
- Windows: - (not available)
```

--------------------------------

### UserDirs::audio_dir

Source: https://docs.rs/directories/latest/directories/struct.UserDirs.html

Returns the path to the user's audio directory.

```APIDOC
## UserDirs::audio_dir

### Description
Returns the path to the user's audio directory.

### Method
`pub fn audio_dir(&self) -> Option<&Path>`

### Returns
- `Option<&Path>` - The path to the user's audio directory, or `None` if not available.

### Platform Values
| Platform | Value | Example |
|----------|-------|---------|
| Linux    | `XDG_MUSIC_DIR` | /home/alice/Music |
| macOS    | `$HOME`/Music | /Users/Alice/Music |
| Windows  | `{FOLDERID_Music}` | C:\Users\Alice\Music |
```

--------------------------------

### UserDirs::home_dir

Source: https://docs.rs/directories/latest/directories/struct.UserDirs.html

Returns the path to the user's home directory.

```APIDOC
## UserDirs::home_dir

### Description
Returns the path to the user's home directory.

### Method
`pub fn home_dir(&self) -> &Path`

### Returns
- `&Path` - The path to the user's home directory.

### Platform Values
| Platform | Value | Example |
|----------|-------|---------|
| Linux    | `$HOME` | /home/alice |
| macOS    | `$HOME` | /Users/Alice |
| Windows  | `{FOLDERID_Profile}` | C:\Users\Alice |
```

--------------------------------

### UserDirs::video_dir

Source: https://docs.rs/directories/latest/directories/struct.UserDirs.html

Returns the path to the user's video directory.

```APIDOC
## UserDirs::video_dir

### Description
Returns the path to the user's video directory.

### Method
`pub fn video_dir(&self) -> Option<&Path>`

### Returns
- `Option<&Path>` - The path to the user's video directory, or `None` if not available.

### Platform Values
| Platform | Value | Example |
|----------|-------|---------|
| Linux    | `XDG_VIDEOS_DIR` | /home/alice/Videos |
| macOS    | `$HOME`/Movies | /Users/Alice/Movies |
| Windows  | `{FOLDERID_Videos}` | C:\Users\Alice\Videos |
```

--------------------------------

### BaseDirs::config_dir()

Source: https://docs.rs/directories/latest/directories/struct.BaseDirs.html

Returns the path to the user's config directory. The exact location depends on the operating system: on Linux it is typically ~/.config, on Windows it is %APPDATA%, and on macOS it is ~/Library/Application Support.

```APIDOC
## BaseDirs::config_dir()

### Description
Returns the path to the user's config directory. The exact location depends on the operating system: on Linux it is typically ~/.config, on Windows it is %APPDATA%, and on macOS it is ~/Library/Application Support.

### Method
`config_dir`

### Signature
`pub fn config_dir(&self) -> &Path`

### Returns
- `&Path` - The path to the config directory.

### Example
```rust
use directories::BaseDirs;
if let Some(base_dirs) = BaseDirs::new() {
    base_dirs.config_dir();
    // Linux:   /home/alice/.config
    // Windows: C:\Users\Alice\AppData\Roaming
    // macOS:   /Users/Alice/Library/Application Support
}
```
```

--------------------------------

### Test for user-dirs.dirs file existence

Source: https://docs.rs/directories/latest/src/directories/lin.rs.html

A test case that checks if the user-dirs.dirs configuration file exists in the user's config directory.

```rust
    #[test]
    fn test_file_user_dirs_exists() {
        let base_dirs      = ::BaseDirs::new();
        let user_dirs_file = base_dirs.unwrap().config_dir().join("user-dirs.dirs");
        println!("{:?} exists: {:?}", user_dirs_file, user_dirs_file.exists());
    }
}
```

--------------------------------

### ProjectDirs::config_local_dir

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Returns the path to the project's local config directory. The path is platform-specific and follows operating system standards.

```APIDOC
## ProjectDirs::config_local_dir

### Description
Returns the path to the project's local config directory. The path is platform-specific and follows operating system standards.

### Method
config_local_dir

### Signature
pub fn config_local_dir(&self) -> &Path

### Returns
- **&Path** - The path to the local config directory.

### Platform Values
- **Linux**: $XDG_CONFIG_HOME/_project_path_ or $HOME/.config/_project_path_ - Example: /home/alice/.config/barapp
- **macOS**: $HOME/Library/Application Support/_project_path_ - Example: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
- **Windows**: {FOLDERID_LocalAppData}\_project_path_\config - Example: C:\Users\Alice\AppData\Local\Foo Corp\Bar App\config

```

--------------------------------

### data_dir

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Returns the path to the project's data directory. The path is platform-specific and based on environment variables or standard locations.

```APIDOC
## data_dir

### Description
Returns the path to the project's data directory.

### Method
pub fn data_dir(&self) -> &Path

### Parameters
None

### Return Value
&Path - The path to the project's data directory.

### Platform Values
- Linux: $XDG_DATA_HOME/_project_path_ or $HOME/.local/share/_project_path_ (e.g., /home/alice/.local/share/barapp)
- macOS: $HOME/Library/Application Support/_project_path_ (e.g., /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App)
- Windows: {FOLDERID_RoamingAppData}\_project_path_\data (e.g., C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\data)
```

--------------------------------

### UserDirs::desktop_dir

Source: https://docs.rs/directories/latest/directories/struct.UserDirs.html

Returns the path to the user's desktop directory.

```APIDOC
## UserDirs::desktop_dir

### Description
Returns the path to the user's desktop directory.

### Method
`pub fn desktop_dir(&self) -> Option<&Path>`

### Returns
- `Option<&Path>` - The path to the user's desktop directory, or `None` if not available.

### Platform Values
| Platform | Value | Example |
|----------|-------|---------|
| Linux    | `XDG_DESKTOP_DIR` | /home/alice/Desktop |
| macOS    | `$HOME`/Desktop | /Users/Alice/Desktop |
| Windows  | `{FOLDERID_Desktop}` | C:\Users\Alice\Desktop |
```

--------------------------------

### ProjectDirs::runtime_dir

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the path to the project's runtime directory, which contains transient, non-essential data (like sockets or named pipes) that is expected to be cleared when the user's session ends. Only available on Linux; returns None on macOS and Windows.

```APIDOC
## ProjectDirs::runtime_dir

### Description
Returns the path to the project's runtime directory. 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.

### Method Signature
pub fn runtime_dir(&self) -> Option<&Path>

### Platform Paths
| Platform | Value | Example |
| --- | --- | --- |
| Linux | $XDG_RUNTIME_DIR/_project_path_ | /run/user/1001/barapp |
| macOS | – | – |
| Windows | – | – |

### Returns
- **Option<&Path>** - The path to the runtime directory, or None if not available on the platform.
```

--------------------------------

### BaseDirs::new

Source: https://docs.rs/directories/latest/directories/struct.BaseDirs.html

Creates a new BaseDirs instance containing paths to user-invisible directories. Returns None if no valid home directory can be determined.

```APIDOC
## BaseDirs::new

### Description
Creates a `BaseDirs` struct which holds the paths to user-invisible directories for cache, config, etc. data on the system. The returned value depends on the operating system and is either `Some`, containing a snapshot of the state of the system's paths at the time `new()` was invoked, or `None`, if no valid home directory path could be retrieved from the operating system.

### Method
`pub fn new() -> Option<BaseDirs>`

### Parameters
None.

### Return Value
- `Option<BaseDirs>` - `Some` if a valid home directory is found, otherwise `None`.

### Platform Behavior
- **Linux and macOS**: Uses `$HOME` if set and non-empty; otherwise uses `getpwuid_r` to determine the home directory. Returns `None` if no entry or empty home directory.
- **Windows**: Retrieves the user profile folder using `SHGetKnownFolderPath`. Returns `None` if this fails.

### Notes
This logic differs from `std::env::home_dir`, which works incorrectly on Linux, macOS and Windows.
```

--------------------------------

### ProjectDirs getters

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Getter methods on `ProjectDirs` that return paths to project-specific directories such as config, cache, data, and more.

```APIDOC
## ProjectDirs getters

### Description
Getter methods on `ProjectDirs` that return paths to project-specific directories such as config, cache, data, and more.

### Methods
- `config_dir() -> &Path` - Returns the path to the project's config directory.
- `cache_dir() -> &Path` - Returns the path to the project's cache directory.
- `data_dir() -> &Path` - Returns the path to the project's data directory.
- `data_local_dir() -> &Path` - Returns the path to the project's local data directory.
- `config_local_dir() -> &Path` - Returns the path to the project's local config directory.
- `preference_dir() -> &Path` - Returns the path to the project's preference directory.
- `runtime_dir() -> Option<&Path>` - Returns the path to the project's runtime directory, if available.
- `state_dir() -> Option<&Path>` - Returns the path to the project's state directory, if available.
- `executable_dir() -> Option<&Path>` - Returns the path to the project's executable directory, if available.

### Example
```rust
use directories::ProjectDirs;
if let Some(proj_dirs) = ProjectDirs::from("com", "Foo Corp",  "Bar App") {
    proj_dirs.config_dir();
    // 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
}
```
```

--------------------------------

### picture_dir

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Returns the path to the user's picture directory. Platform-specific values: Linux uses XDG_PICTURES_DIR, macOS uses $HOME/Pictures, Windows uses {FOLDERID_Pictures}.

```APIDOC
## picture_dir

### Description
Returns the path to the user's picture directory.

### Method Signature
pub fn picture_dir(&self) -> Option<&Path>

### Platform Values
| Platform | Value                 | Example                 |
| ------- | --------------------- | ----------------------- |
| Linux   | XDG_PICTURES_DIR      | /home/alice/Pictures    |
| macOS   | $HOME/Pictures        | /Users/Alice/Pictures   |
| Windows | {FOLDERID_Pictures}   | C:\Users\Alice\Pictures |

### Returns
Option<&Path> - The path to the picture directory, or None if not available.
```

--------------------------------

### state_dir

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Returns the path to the project's state directory, which contains data retained between sessions. Returns None on platforms where this directory is not defined.

```APIDOC
## state_dir

### Description
Returns the path to the project's state directory. 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).

### Method
pub fn state_dir(&self) -> Option<&Path>

### Parameters
None

### Return Value
Option<&Path> - The path to the project's state directory, or None if not available.

### Platform Values
- Linux: $XDG_STATE_HOME/_project_path_ or $HOME/.local/state/_project_path_ (e.g., /home/alice/.local/state/barapp)
- macOS: - (not available)
- Windows: - (not available)
```

--------------------------------

### Unit tests for trim_and_lowercase_then_replace_spaces

Source: https://docs.rs/directories/latest/src/directories/lin.rs.html

Tests verifying the behavior of string normalization with various inputs including whitespace and existing separators.

```rust
#[cfg(test)]
mod tests {
    use lin::trim_and_lowercase_then_replace_spaces;

    #[test]
    fn test_trim_and_lowercase_then_replace_spaces() {
        let input1    = "Bar App";
        let actual1   = trim_and_lowercase_then_replace_spaces(input1, "-");
        let expected1 = "bar-app";
        assert_eq!(expected1, actual1);

        let input2    = "BarApp-Foo";
        let actual2   = trim_and_lowercase_then_replace_spaces(input2, "-");
        let expected2 = "barapp-foo";
        assert_eq!(expected2, actual2);

        let input3    = " Bar App ";
        let actual3   = trim_and_lowercase_then_replace_spaces(input3, "-");
        let expected3 = "bar-app";
        assert_eq!(expected3, actual3);

        let input4    = "  Bar  App  ";
        let actual4   = trim_and_lowercase_then_replace_spaces(input4, "-");
        let expected4 = "bar-app";
        assert_eq!(expected4, actual4);
    }
```

--------------------------------

### UserDirs::download_dir

Source: https://docs.rs/directories/latest/directories/struct.UserDirs.html

Returns the path to the user's download directory.

```APIDOC
## UserDirs::download_dir

### Description
Returns the path to the user's download directory.

### Method
`pub fn download_dir(&self) -> Option<&Path>`

### Returns
- `Option<&Path>` - The path to the user's download directory, or `None` if not available.

### Platform Values
| Platform | Value | Example |
|----------|-------|---------|
| Linux    | `XDG_DOWNLOAD_DIR` | /home/alice/Downloads |
| macOS    | `$HOME`/Downloads | /Users/Alice/Downloads |
| Windows  | `{FOLDERID_Downloads}` | C:\Users\Alice\Downloads |
```

--------------------------------

### UserDirs getters

Source: https://docs.rs/directories/latest/src/directories/lib.rs.html

Getter methods on `UserDirs` that return paths to user-facing directories such as audio, desktop, documents, and more.

```APIDOC
## UserDirs getters

### Description
Getter methods on `UserDirs` that return paths to user-facing directories such as audio, desktop, documents, and more.

### Methods
- `home_dir() -> &Path` - Returns the path to the user's home directory.
- `audio_dir() -> Option<&Path>` - Returns the path to the user's audio directory, if available.
- `desktop_dir() -> Option<&Path>` - Returns the path to the user's desktop directory, if available.
- `document_dir() -> Option<&Path>` - Returns the path to the user's document directory, if available.
- `download_dir() -> Option<&Path>` - Returns the path to the user's download directory, if available.
- `font_dir() -> Option<&Path>` - Returns the path to the user's font directory, if available.
- `picture_dir() -> Option<&Path>` - Returns the path to the user's picture directory, if available.
- `public_dir() -> Option<&Path>` - Returns the path to the user's public directory, if available.
- `template_dir() -> Option<&Path>` - Returns the path to the user's template directory, if available.
- `video_dir() -> Option<&Path>` - Returns the path to the user's video directory, if available.

### Example
```rust
use directories::UserDirs;
if let Some(user_dirs) = UserDirs::new() {
    user_dirs.audio_dir();
    // Linux:   /home/alice/Music
    // Windows: C:\Users\Alice\Music
    // macOS:   /Users/Alice/Music
}
```
```

--------------------------------

### BaseDirs::home_dir

Source: https://docs.rs/directories/latest/directories/struct.BaseDirs.html

Returns the path to the user's home directory.

```APIDOC
## BaseDirs::home_dir

### Description
Returns the path to the user's home directory.

### Method
`pub fn home_dir(&self) -> &Path`

### Parameters
None.

### Return Value
- `&Path` - The path to the user's home directory.

### Platform Values
| Platform | Value | Example |
|----------|-------|---------|
| Linux | `$HOME` | /home/alice |
| macOS | `$HOME` | /Users/Alice |
| Windows | `{FOLDERID_Profile}` | C:\Users\Alice |
```

--------------------------------

### BaseDirs::config_dir

Source: https://docs.rs/directories/latest/directories/struct.BaseDirs.html

Returns the path to the user's config directory.

```APIDOC
## BaseDirs::config_dir

### Description
Returns the path to the user's config directory.

### Method
`pub fn config_dir(&self) -> &Path`

### Parameters
None.

### Return Value
- `&Path` - The path to the user's config directory.

### Platform Values
| Platform | Value | Example |
|----------|-------|---------|
| Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config |
| macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
| Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming |
```

--------------------------------

### data_local_dir

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Returns the path to the project's local data directory. The path is platform-specific and based on environment variables or standard locations.

```APIDOC
## data_local_dir

### Description
Returns the path to the project's local data directory.

### Method
pub fn data_local_dir(&self) -> &Path

### Parameters
None

### Return Value
&Path - The path to the project's local data directory.

### Platform Values
- Linux: $XDG_DATA_HOME/_project_path_ or $HOME/.local/share/_project_path_ (e.g., /home/alice/.local/share/barapp)
- macOS: $HOME/Library/Application Support/_project_path_ (e.g., /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App)
- Windows: {FOLDERID_LocalAppData}\_project_path_\data (e.g., C:\Users\Alice\AppData\Local\Foo Corp\Bar App\data)
```

--------------------------------

### base_dirs function

Source: https://docs.rs/directories/latest/src/directories/lin.rs.html

Resolves standard base directories like cache, config, and data paths based on XDG environment variables or default locations.

```rust
pub fn base_dirs() -> Option<BaseDirs> {
    if let Some(home_dir)    = dirs_sys::home_dir() {
        let cache_dir        = env::var_os("XDG_CACHE_HOME") .and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".cache"));
        let config_dir       = env::var_os("XDG_CONFIG_HOME").and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".config"));
        let config_local_dir = config_dir.clone();
        let data_dir         = env::var_os("XDG_DATA_HOME")  .and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".local/share"));
        let data_local_dir   = data_dir.clone();
        let preference_dir   = config_dir.clone();
        let runtime_dir      = env::var_os("XDG_RUNTIME_DIR").and_then(dirs_sys::is_absolute_path);
        let state_dir        = env::var_os("XDG_STATE_HOME") .and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".local/state"));
        let executable_dir   = env::var_os("XDG_BIN_HOME")   .and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".local/bin"));

        let base_dirs = BaseDirs {
            home_dir:         home_dir,
            cache_dir:        cache_dir,
            config_dir:       config_dir,
            config_local_dir: config_local_dir,
            data_dir:         data_dir,
            data_local_dir:   data_local_dir,
            executable_dir:   Some(executable_dir),
            preference_dir:   preference_dir,
            runtime_dir:      runtime_dir,
            state_dir:        Some(state_dir)
        };
        Some(base_dirs)
    } else {
        None
    }
}
```

--------------------------------

### ProjectDirs::cache_dir

Source: https://docs.rs/directories/latest/directories/struct.ProjectDirs.html

Returns the path to the project's cache directory. The path is platform-specific and follows operating system standards.

```APIDOC
## ProjectDirs::cache_dir

### Description
Returns the path to the project's cache directory. The path is platform-specific and follows operating system standards.

### Method
cache_dir

### Signature
pub fn cache_dir(&self) -> &Path

### Returns
- **&Path** - The path to the cache directory.

### Platform Values
- **Linux**: $XDG_CACHE_HOME/_project_path_ or $HOME/.cache/_project_path_ - Example: /home/alice/.cache/barapp
- **macOS**: $HOME/Library/Caches/_project_path_ - Example: /Users/Alice/Library/Caches/com.Foo-Corp.Bar-App
- **Windows**: {FOLDERID_LocalAppData}\_project_path_\cache - Example: C:\Users\Alice\AppData\Local\Foo Corp\Bar App\cache

```

--------------------------------

### UserDirs::template_dir

Source: https://docs.rs/directories/latest/directories/struct.UserDirs.html

Returns the path to the user's template directory.

```APIDOC
## UserDirs::template_dir

### Description
Returns the path to the user's template directory.

### Method
`pub fn template_dir(&self) -> Option<&Path>`

### Returns
- `Option<&Path>` - The path to the user's template directory, or `None` if not available.

### Platform Values
| Platform | Value | Example |
|----------|-------|---------|
| Linux    | `XDG_TEMPLATES_DIR` | /home/alice/Templates |
| macOS    | – | – |
| Windows  | `{FOLDERID_Templates}` | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates |
```
Tokens:
Raw