Etcetera

https://docs.rs/etcetera/latest/etcetera/
Admin
Etcetera is a Rust library that allows you to determine the locations of configuration, data, cache,...
Tokens:8,508
Snippets:92
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Using the Apple strategy

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Apple.html

Example demonstrating how to initialize the Apple strategy and retrieve standard directory paths.

```rust
use etcetera::base_strategy::Apple;
use etcetera::base_strategy::BaseStrategy;
use std::path::Path;

let base_strategy = Apple::new().unwrap();

let home_dir = etcetera::home_dir().unwrap();

assert_eq!(
    base_strategy.home_dir(),
    &home_dir
);
assert_eq!(
    base_strategy.config_dir().strip_prefix(&home_dir),
    Ok(Path::new("Library/Preferences/"))
);
assert_eq!(
    base_strategy.data_dir().strip_prefix(&home_dir),
    Ok(Path::new("Library/Application Support/"))
);
assert_eq!(
    base_strategy.cache_dir().strip_prefix(&home_dir),
    Ok(Path::new("Library/Caches/"))
);
assert_eq!(
    base_strategy.state_dir(),
    None
);
assert_eq!(
    base_strategy.runtime_dir(),
    None
);
```

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

### Get native base strategy

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/fn.choose_native_strategy.html

Returns the current OS’s native BaseStrategy, following standard GUI application conventions.

```rust
pub fn choose_native_strategy() -> Result<Xdg, HomeDirError>
```

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

### Initialize and Use Unix App Strategy

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Unix.html

Demonstrates initializing the Unix strategy with AppStrategyArgs and verifying the resulting directory paths.

```rust
use etcetera::app_strategy::AppStrategy;
use etcetera::app_strategy::AppStrategyArgs;
use etcetera::app_strategy::Unix;
use std::path::Path;

let app_strategy = Unix::new(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
}).unwrap();

let home_dir = etcetera::home_dir().unwrap();

assert_eq!(
    app_strategy.home_dir(),
    &home_dir
);
assert_eq!(
    app_strategy.config_dir().strip_prefix(&home_dir),
    Ok(Path::new(".frobnicator-plus/"))
);
assert_eq!(
    app_strategy.data_dir().strip_prefix(&home_dir),
    Ok(Path::new(".frobnicator-plus/data/"))
);
assert_eq!(
    app_strategy.cache_dir().strip_prefix(&home_dir),
    Ok(Path::new(".frobnicator-plus/cache/"))
);
assert_eq!(
    app_strategy.state_dir().unwrap().strip_prefix(&home_dir),
    Ok(Path::new(".frobnicator-plus/state/"))
);
assert_eq!(
    app_strategy.runtime_dir().unwrap().strip_prefix(&home_dir),
    Ok(Path::new(".frobnicator-plus/runtime/"))
);
```

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

### Initialize Windows AppStrategy with custom environment variables

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Windows.html

Demonstrates configuring the Windows strategy by explicitly setting environment variables for home, data, and cache locations.

```rust
use etcetera::app_strategy::AppStrategy;
use etcetera::app_strategy::AppStrategyArgs;
use etcetera::app_strategy::Windows;
use std::path::Path;

let home_path = if cfg!(windows) {
    "C:\\my_home_location\\".to_string()
} else {
    etcetera::home_dir().unwrap().to_string_lossy().to_string()
};
let data_path = if cfg!(windows) {
    "C:\\my_data_location\\"
} else {
    "/my_data_location/"
};
let cache_path = if cfg!(windows) {
    "C:\\my_cache_location\\"
} else {
    "/my_cache_location/"
};

unsafe {
std::env::set_var("USERPROFILE", &home_path);
std::env::set_var("APPDATA", data_path);
std::env::set_var("LOCALAPPDATA", cache_path);
}

let app_strategy = Windows::new(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
}).unwrap();

assert_eq!(
    app_strategy.home_dir(),
    Path::new(&home_path)
);
assert_eq!(
    app_strategy.config_dir(),
    Path::new(&format!("{}/Acme Corp/Frobnicator Plus/config", data_path))
);
assert_eq!(
    app_strategy.data_dir(),
    Path::new(&format!("{}/Acme Corp/Frobnicator Plus/data", data_path))
);
assert_eq!(
    app_strategy.cache_dir(),
    Path::new(&format!("{}/Acme Corp/Frobnicator Plus/cache", cache_path))
);
assert_eq!(
    app_strategy.state_dir(),
    None
);
assert_eq!(
    app_strategy.runtime_dir(),
    None
);
```

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

### Initialize Windows AppStrategy with default environment

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Windows.html

Demonstrates using the Windows strategy after removing relevant environment variables to rely on system defaults.

```rust
use etcetera::app_strategy::AppStrategy;
use etcetera::app_strategy::AppStrategyArgs;
use etcetera::app_strategy::Windows;
use std::path::Path;

// Remove the environment variables that the strategy reads from.
unsafe {
std::env::remove_var("USERPROFILE");
std::env::remove_var("APPDATA");
std::env::remove_var("LOCALAPPDATA");
}

let app_strategy = Windows::new(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
}).unwrap();

let home_dir = etcetera::home_dir().unwrap();

assert_eq!(
    app_strategy.home_dir(),
    &home_dir
);
assert_eq!(
    app_strategy.config_dir().strip_prefix(&home_dir),
    Ok(Path::new("AppData/Roaming/Acme Corp/Frobnicator Plus/config"))
);
assert_eq!(
    app_strategy.data_dir().strip_prefix(&home_dir),
    Ok(Path::new("AppData/Roaming/Acme Corp/Frobnicator Plus/data"))
);
assert_eq!(
    app_strategy.cache_dir().strip_prefix(&home_dir),
    Ok(Path::new("AppData/Local/Acme Corp/Frobnicator Plus/cache"))
);
assert_eq!(
    app_strategy.state_dir(),
    None
);
assert_eq!(
    app_strategy.runtime_dir(),
    None
);
```

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

### Use Windows strategy with environment variables

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Windows.html

Demonstrates how the Windows strategy respects specific environment variables when they are set.

```rust
use etcetera::base_strategy::BaseStrategy;
use etcetera::base_strategy::Windows;
use std::path::Path;

let home_path = if cfg!(windows) {
    "C:\\foo\\".to_string()
} else {
    etcetera::home_dir().unwrap().to_string_lossy().to_string()
};
let data_path = if cfg!(windows) {
    "C:\\bar\\"
} else {
    "/bar/"
};
let cache_path = if cfg!(windows) {
    "C:\\baz\\"
} else {
    "/baz/"
};

unsafe {
std::env::set_var("USERPROFILE", &home_path);
std::env::set_var("APPDATA", data_path);
std::env::set_var("LOCALAPPDATA", cache_path);
}

let base_strategy = Windows::new().unwrap();

assert_eq!(
    base_strategy.home_dir(),
    Path::new(&home_path)
);
assert_eq!(
    base_strategy.config_dir(),
    Path::new(data_path)
);
assert_eq!(
    base_strategy.data_dir(),
    Path::new(data_path)
);
assert_eq!(
    base_strategy.cache_dir(),
    Path::new(cache_path)
);
assert_eq!(
    base_strategy.state_dir(),
    None
);
assert_eq!(
    base_strategy.runtime_dir(),
    None
);
```

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

### Apple::new

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Apple.html

Creates a new instance of the Apple BaseStrategy.

```APIDOC
## pub fn new() -> Result<Self, HomeDirError>

### Description
Creates a new Apple BaseStrategy instance. This is the entry point for using the Apple-specific directory resolution strategy.

### Returns
- **Result<Self, HomeDirError>** - Returns the Apple strategy instance or an error if the home directory cannot be determined.
```

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

### Initialize Unix Strategy

Source: https://docs.rs/etcetera/latest/etcetera/index.html

Manually instantiate the Unix strategy to define specific folder structures, bypassing default XDG behavior.

```rust
use etcetera::{app_strategy, AppStrategy, AppStrategyArgs};

let strategy = app_strategy::Unix::new(AppStrategyArgs {
    top_level_domain: "com".to_string(),
    author: "Hardened Unix Veteran Who Likes Short Command Names".to_string(),
    app_name: "wry".to_string(),
}).unwrap();

let config_dir = strategy.config_dir(); // produces ~/.wry/
// et cetera.
```

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

### Use Windows strategy without environment variables

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Windows.html

Demonstrates the Windows strategy behavior when relevant environment variables are removed, relying on default system paths.

```rust
use etcetera::base_strategy::BaseStrategy;
use etcetera::base_strategy::Windows;
use std::path::Path;

// Remove the environment variables that the strategy reads from.
unsafe {
std::env::remove_var("USERPROFILE");
std::env::remove_var("APPDATA");
std::env::remove_var("LOCALAPPDATA");
}

let base_strategy = Windows::new().unwrap();

let home_dir = etcetera::home_dir().unwrap();

assert_eq!(
    base_strategy.home_dir(),
    &home_dir
);
assert_eq!(
    base_strategy.config_dir().strip_prefix(&home_dir),
    Ok(Path::new("AppData/Roaming/"))
);
assert_eq!(
    base_strategy.data_dir().strip_prefix(&home_dir),
    Ok(Path::new("AppData/Roaming/"))
);
assert_eq!(
    base_strategy.cache_dir().strip_prefix(&home_dir),
    Ok(Path::new("AppData/Local/"))
);
assert_eq!(
    base_strategy.state_dir(),
    None
);
assert_eq!(
    base_strategy.runtime_dir(),
    None
);
```

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

### Use Xdg with default directories

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Xdg.html

Demonstrates the use of Xdg with default directories by clearing relevant environment variables.

```rust
use etcetera::base_strategy::BaseStrategy;
use etcetera::base_strategy::Xdg;
use std::path::Path;

// Remove the environment variables that the strategy reads from.
unsafe {
std::env::remove_var("XDG_CONFIG_HOME");
std::env::remove_var("XDG_DATA_HOME");
std::env::remove_var("XDG_CACHE_HOME");
std::env::remove_var("XDG_STATE_HOME");
std::env::remove_var("XDG_RUNTIME_DIR");
}

let base_strategy = Xdg::new().unwrap();

let home_dir = etcetera::home_dir().unwrap();

assert_eq!(
    base_strategy.home_dir(),
    &home_dir
);
assert_eq!(
    base_strategy.config_dir().strip_prefix(&home_dir),
    Ok(Path::new(".config/"))
);
assert_eq!(
    base_strategy.data_dir().strip_prefix(&home_dir),
    Ok(Path::new(".local/share/"))
);
assert_eq!(
    base_strategy.cache_dir().strip_prefix(&home_dir),
    Ok(Path::new(".cache/"))
);
assert_eq!(
    base_strategy.state_dir().unwrap().strip_prefix(&home_dir),
    Ok(Path::new(".local/state"))
);
assert_eq!(
    base_strategy.runtime_dir(),
    None
);
```

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

### Generate Paths with Convenience Methods

Source: https://docs.rs/etcetera/latest/etcetera/index.html

Use AppStrategy convenience methods to construct paths relative to configuration, data, or cache directories.

```rust
use etcetera::{choose_app_strategy, AppStrategy, AppStrategyArgs};

let strategy = choose_app_strategy(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator".to_string(),
}).unwrap();

// Path to configuration directory.
let config_dir = strategy.config_dir();

// Path to config.toml inside the configuration directory.
let config_file = strategy.in_config_dir("config.toml");

assert_eq!(config_dir.join("config.toml"), config_file);
```

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

### choose_base_strategy()

Source: https://docs.rs/etcetera/latest/etcetera/index.html

Retrieves a base strategy to determine standard directory paths for configuration, data, cache, state, and runtime files based on the host operating system.

```APIDOC
## choose_base_strategy()

### Description
Returns a strategy object that provides methods to access standard system directories. This function automatically selects the appropriate strategy based on the platform.

### Usage
```rust
use etcetera::{choose_base_strategy, BaseStrategy};

let strategy = choose_base_strategy().unwrap();

let config_dir = strategy.config_dir();
let data_dir = strategy.data_dir();
let cache_dir = strategy.cache_dir();
let state_dir = strategy.state_dir();
let runtime_dir = strategy.runtime_dir();
```
```

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

### choose_native_strategy()

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/fn.choose_native_strategy.html

Returns the current OS’s native BaseStrategy. This uses the Windows strategy on Windows, Apple on macOS & iOS, and Xdg everywhere else.

```APIDOC
## fn choose_native_strategy

### Description
Returns the current OS’s native `BaseStrategy`. This uses the `Windows` strategy on Windows, `Apple` on macOS & iOS, and `Xdg` everywhere else. This is the convention used by most GUI applications.

### Signature
`pub fn choose_native_strategy() -> Result<Xdg, HomeDirError>`

### Returns
- **Result<Xdg, HomeDirError>** - Returns an `Xdg` strategy on success, or a `HomeDirError` if the operation fails.
```

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

### choose_native_strategy

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/index.html

Returns the current OS’s native BaseStrategy, typically used by GUI applications. It selects Windows on Windows, Apple on macOS/iOS, and Xdg elsewhere.

```APIDOC
## choose_native_strategy

### Description
Returns the current OS’s native `BaseStrategy`. This uses the `Windows` strategy on Windows, `Apple` on macOS & iOS, and `Xdg` everywhere else. This is the convention used by most GUI applications.
```

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

### Configure Xdg with environment variables

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Xdg.html

Shows how Xdg respects absolute paths provided via environment variables.

```rust
use etcetera::base_strategy::BaseStrategy;
use etcetera::base_strategy::Xdg;
use std::path::Path;

// We need to conditionally set these to ensure that they are absolute paths both on Windows and other systems.
let config_path = if cfg!(windows) {
    "C:\\foo\\"
} else {
    "/foo/"
};
let data_path = if cfg!(windows) {
    "C:\\bar\\"
} else {
    "/bar/"
};
let cache_path = if cfg!(windows) {
    "C:\\baz\\"
} else {
    "/baz/"
};
let state_path = if cfg!(windows) {
    "C:\\foobar\\"
} else {
    "/foobar/"
};
let runtime_path = if cfg!(windows) {
    "C:\\qux\\"
} else {
    "/qux/"
};

unsafe {
std::env::set_var("XDG_CONFIG_HOME", config_path);
std::env::set_var("XDG_DATA_HOME", data_path);
std::env::set_var("XDG_CACHE_HOME", cache_path);
std::env::set_var("XDG_STATE_HOME", state_path);
std::env::set_var("XDG_RUNTIME_DIR", runtime_path);
}

let base_strategy = Xdg::new().unwrap();

assert_eq!(
    base_strategy.config_dir(),
    Path::new(config_path)
);
assert_eq!(
    base_strategy.data_dir(),
    Path::new(data_path)
);
assert_eq!(
    base_strategy.cache_dir(),
    Path::new(cache_path)
);
assert_eq!(
    base_strategy.state_dir().unwrap(),
    Path::new(state_path)
);
assert_eq!(
    base_strategy.runtime_dir().unwrap(),
    Path::new(runtime_path)
);
```

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

### choose_base_strategy

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/index.html

Returns the current OS’s default BaseStrategy, typically used by CLI applications. It defaults to the Windows strategy on Windows and Xdg elsewhere.

```APIDOC
## choose_base_strategy

### Description
Returns the current OS’s default `BaseStrategy`. This uses the `Windows` strategy on Windows, and `Xdg` everywhere else. This is the convention used by most CLI applications.
```

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

### Retrieve base directory paths with BaseStrategy

Source: https://docs.rs/etcetera/latest/etcetera/index.html

Use choose_base_strategy to obtain a strategy object for accessing standard system directories like config, data, and cache.

```rust
use etcetera::{choose_base_strategy, BaseStrategy};

let strategy = choose_base_strategy().unwrap();

let config_dir = strategy.config_dir();
let data_dir = strategy.data_dir();
let cache_dir = strategy.cache_dir();
let state_dir = strategy.state_dir();
let runtime_dir = strategy.runtime_dir();
```

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

### choose_app_strategy

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/index.html

Returns the current OS’s default AppStrategy, typically used by CLI applications. It defaults to the Windows strategy on Windows and Xdg elsewhere.

```APIDOC
## choose_app_strategy

### Description
Returns the current OS’s default `AppStrategy`. This uses the `Windows` strategy on Windows, and `Xdg` everywhere else. This is the convention used by most CLI applications.
```

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

### choose_app_strategy(args: AppStrategyArgs)

Source: https://docs.rs/etcetera/latest/etcetera/index.html

Retrieves an application-specific strategy that determines directory paths based on provided application metadata, following platform-specific naming conventions.

```APIDOC
## choose_app_strategy(args: AppStrategyArgs)

### Description
Returns a strategy object configured for a specific application. It uses the provided author, app name, and top-level domain to resolve paths according to the conventions of the host OS.

### Parameters
- **args** (AppStrategyArgs) - Required - A struct containing `top_level_domain`, `author`, and `app_name`.

### Usage
```rust
use etcetera::{choose_app_strategy, AppStrategy, AppStrategyArgs};

let strategy = choose_app_strategy(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
}).unwrap();

let config_dir = strategy.config_dir();
let data_dir = strategy.data_dir();
let cache_dir = strategy.cache_dir();
let state_dir = strategy.state_dir();
let runtime_dir = strategy.runtime_dir();
```
```

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

### choose_app_strategy function signature

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/fn.choose_app_strategy.html

The function signature for choosing the default application strategy based on the operating system.

```rust
pub fn choose_app_strategy(args: AppStrategyArgs) -> Result<Xdg, HomeDirError>
```

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

### Define Windows strategy structure

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Windows.html

The definition of the Windows struct within the base_strategy module.

```rust
pub struct Windows { /* private fields */ }
```

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

### choose_native_strategy

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/index.html

Returns the current OS’s native AppStrategy, typically used by GUI applications. It selects Windows, Apple, or Xdg strategies based on the platform.

```APIDOC
## choose_native_strategy

### Description
Returns the current OS’s native `AppStrategy`. This uses the `Windows` strategy on Windows, `Apple` on macOS & iOS, and `Xdg` everywhere else. This is the convention used by most GUI applications.
```

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

### Generate unixy name

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.AppStrategyArgs.html

Converts the application name into a unix-style format suitable for binary naming.

```rust
use etcetera::app_strategy::AppStrategyArgs;

let strategy_args = AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
};

assert_eq!(strategy_args.unixy_name(), "frobnicator-plus".to_string());
```

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

### Retrieve application-specific paths with AppStrategy

Source: https://docs.rs/etcetera/latest/etcetera/index.html

Use choose_app_strategy with AppStrategyArgs to resolve directory paths based on specific application naming conventions and vendor information.

```rust
use etcetera::{choose_app_strategy, AppStrategy, AppStrategyArgs};

let strategy = choose_app_strategy(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
}).unwrap();

let config_dir = strategy.config_dir();
let data_dir = strategy.data_dir();
let cache_dir = strategy.cache_dir();
let state_dir = strategy.state_dir();
let runtime_dir = strategy.runtime_dir();
```

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

### choose_base_strategy function signature

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/fn.choose_base_strategy.html

The function signature for choosing the default base strategy.

```rust
pub fn choose_base_strategy() -> Result<Xdg, HomeDirError>
```

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

### CloneToUninit Trait Implementation

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Apple.html

Experimental nightly API for performing copy-assignment to uninitialized memory.

```rust
impl<T> CloneToUninit for T
where T: Clone,
```

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

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

### pub fn home_dir() -> Result<PathBuf, HomeDirError>

Source: https://docs.rs/etcetera/latest/etcetera/fn.home_dir.html

A convenience function that wraps the home_dir function from the standard library to retrieve the user's home directory.

```APIDOC
## home_dir

### Description
A convenience function that wraps the `home_dir` function from the standard library to resolve the current user's home directory.

### Signature
`pub fn home_dir() -> Result<PathBuf, HomeDirError>`

### Returns
- **Result<PathBuf, HomeDirError>** - Returns the path to the home directory on success, or a HomeDirError if the directory cannot be determined.
```

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

### choose_native_strategy function signature

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/fn.choose_native_strategy.html

The function signature for choosing the native application strategy based on the host OS.

```rust
pub fn choose_native_strategy(
    args: AppStrategyArgs,
) -> Result<Xdg, HomeDirError>
```

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

### home_dir function signature

Source: https://docs.rs/etcetera/latest/etcetera/fn.home_dir.html

Displays the function signature for home_dir, which returns a Result containing a PathBuf or a HomeDirError.

```rust
pub fn home_dir() -> Result<PathBuf, HomeDirError>
```

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

### From Trait Implementation

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Apple.html

Returns the argument unchanged.

```rust
impl<T> From<T> for T
```

```rust
fn from(t: T) -> T
```

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

### Handle non-absolute environment variables

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Xdg.html

Demonstrates that Xdg ignores non-absolute paths provided in environment variables, falling back to defaults.

```rust
use etcetera::base_strategy::BaseStrategy;
use etcetera::base_strategy::Xdg;
use std::path::Path;

// Remove the environment variables that the strategy reads from.
unsafe {
std::env::set_var("XDG_CONFIG_HOME", "foo/");
std::env::set_var("XDG_DATA_HOME", "bar/");
std::env::set_var("XDG_CACHE_HOME", "baz/");
std::env::set_var("XDG_STATE_HOME", "foobar/");
std::env::set_var("XDG_RUNTIME_DIR", "qux/");
}

let base_strategy = Xdg::new().unwrap();

let home_dir = etcetera::home_dir().unwrap();

// We still get the default values.
assert_eq!(
    base_strategy.config_dir().strip_prefix(&home_dir),
    Ok(Path::new(".config/"))
);
assert_eq!(
    base_strategy.data_dir().strip_prefix(&home_dir),
    Ok(Path::new(".local/share/"))
);
assert_eq!(
    base_strategy.cache_dir().strip_prefix(&home_dir),
    Ok(Path::new(".cache/"))
);
assert_eq!(
    base_strategy.state_dir().unwrap().strip_prefix(&home_dir),
    Ok(Path::new(".local/state/"))
);
assert_eq!(
    base_strategy.runtime_dir(),
    None
);
```

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

### home_dir

Source: https://docs.rs/etcetera/latest/etcetera/index.html

A convenience function that wraps the home_dir function from the standard library to locate the user's home directory.

```APIDOC
## home_dir

### Description
A convenience function that wraps the `home_dir` function from the standard library to locate the user's home directory.

### Returns
- **Option<PathBuf>** - Returns the path to the user's home directory if it can be located, otherwise returns None.
```

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

### Apple struct definition

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Apple.html

The internal structure of the Apple strategy.

```rust
pub struct Apple { /* private fields */ }
```

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

### Construct bundle identifier

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.AppStrategyArgs.html

Generates a bundle identifier string from the provided AppStrategyArgs fields.

```rust
use etcetera::app_strategy::AppStrategyArgs;

let strategy_args = AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
};

assert_eq!(strategy_args.bundle_id(), "org.acme-corp.Frobnicator-Plus".to_string());
```

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

### Unix Struct Definition

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Unix.html

The internal structure definition for the Unix strategy.

```rust
pub struct Unix { /* private fields */ }
```

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

### AppStrategyArgs::bundle_id

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.AppStrategyArgs.html

Constructs a bundle identifier string based on the provided top-level domain, author, and application name.

```APIDOC
## pub fn bundle_id(&self) -> String

### Description
Constructs a bundle identifier from an `AppStrategyArgs` instance.

### Signature
`pub fn bundle_id(&self) -> String`

### Example
```rust
use etcetera::app_strategy::AppStrategyArgs;

let strategy_args = AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
};

assert_eq!(strategy_args.bundle_id(), "org.acme-corp.Frobnicator-Plus".to_string());
```
```

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

### Define AppStrategyArgs struct

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.AppStrategyArgs.html

The structure definition for AppStrategyArgs.

```rust
pub struct AppStrategyArgs {
    pub top_level_domain: String,
    pub author: String,
    pub app_name: String,
}
```

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

### Into Trait Implementation

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Apple.html

Converts a type into another using the From implementation.

```rust
impl<T, U> Into<U> for T
where U: From<T>,
```

```rust
fn into(self) -> U
```

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

### AppStrategyArgs::unixy_name

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.AppStrategyArgs.html

Returns a 'unixy' version of the application name, suitable for use as a binary name.

```APIDOC
## pub fn unixy_name(&self) -> String

### Description
Returns a ‘unixy’ version of the application’s name, akin to what would usually be used as a binary name.

### Signature
`pub fn unixy_name(&self) -> String`

### Example
```rust
use etcetera::app_strategy::AppStrategyArgs;

let strategy_args = AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
};

assert_eq!(strategy_args.unixy_name(), "frobnicator-plus".to_string());
```
```

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

### Handle invalid relative environment variables

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Xdg.html

Shows that Xdg ignores relative paths provided in environment variables, reverting to default locations.

```rust
use etcetera::app_strategy::AppStrategy;
use etcetera::app_strategy::AppStrategyArgs;
use etcetera::app_strategy::Xdg;
use std::path::Path;

// Remove the environment variables that the strategy reads from.
unsafe {
std::env::set_var("XDG_CONFIG_HOME", "relative_path/");
std::env::set_var("XDG_DATA_HOME", "./another_one/");
std::env::set_var("XDG_CACHE_HOME", "yet_another/");
std::env::set_var("XDG_STATE_HOME", "./and_another");
std::env::set_var("XDG_RUNTIME_DIR", "relative_path/");
}

let app_strategy = Xdg::new(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
}).unwrap();

let home_dir = etcetera::home_dir().unwrap();

// We still get the default values.
assert_eq!(
    app_strategy.config_dir().strip_prefix(&home_dir),
    Ok(Path::new(".config/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.data_dir().strip_prefix(&home_dir),
    Ok(Path::new(".local/share/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.cache_dir().strip_prefix(&home_dir),
    Ok(Path::new(".cache/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.state_dir().unwrap().strip_prefix(&home_dir),
    Ok(Path::new(".local/state/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.runtime_dir(),
    None
);
```

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

### AppStrategy Trait Definition

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/trait.AppStrategy.html

The core trait definition outlining required and provided methods for directory path management.

```rust
pub trait AppStrategy {
    // Required methods
    fn home_dir(&self) -> &Path;
    fn config_dir(&self) -> PathBuf;
    fn data_dir(&self) -> PathBuf;
    fn cache_dir(&self) -> PathBuf;
    fn state_dir(&self) -> Option<PathBuf>;
    fn runtime_dir(&self) -> Option<PathBuf>;

    // Provided methods
    fn in_config_dir<P: AsRef<OsStr>>(&self, path: P) -> PathBuf { ... }
    fn in_data_dir<P: AsRef<OsStr>>(&self, path: P) -> PathBuf { ... }
    fn in_cache_dir<P: AsRef<OsStr>>(&self, path: P) -> PathBuf { ... }
    fn in_state_dir<P: AsRef<OsStr>>(&self, path: P) -> Option<PathBuf> { ... }
    fn in_runtime_dir<P: AsRef<OsStr>>(&self, path: P) -> Option<PathBuf> { ... }
}
```

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

### Define Xdg struct

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/struct.Xdg.html

The definition of the Xdg struct.

```rust
pub struct Xdg { /* private fields */ }
```

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

### Any Trait Implementation

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Apple.html

Provides the type_id method for any type T that satisfies the 'static and ?Sized bounds.

```rust
impl<T> Any for T
where T: 'static + ?Sized,
```

```rust
fn type_id(&self) -> TypeId
```

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

### Define HomeDirError struct

Source: https://docs.rs/etcetera/latest/etcetera/struct.HomeDirError.html

The definition of the HomeDirError unit struct.

```rust
pub struct HomeDirError;
```

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

### TryFrom Trait Implementation

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Apple.html

Performs a fallible conversion from one type to another.

```rust
impl<T, U> TryFrom<U> for T
where U: Into<T>,
```

```rust
type Error = Infallible
```

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

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

### BaseStrategy Trait Definition

Source: https://docs.rs/etcetera/latest/etcetera/base_strategy/trait.BaseStrategy.html

Defines the required methods for platform-specific directory resolution.

```rust
pub trait BaseStrategy {
    // Required methods
    fn home_dir(&self) -> &Path;
    fn config_dir(&self) -> PathBuf;
    fn data_dir(&self) -> PathBuf;
    fn cache_dir(&self) -> PathBuf;
    fn state_dir(&self) -> Option<PathBuf>;
    fn runtime_dir(&self) -> Option<PathBuf>;
}
```

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

### TryInto Trait Implementation

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Apple.html

Performs a fallible conversion into another type.

```rust
impl<T, U> TryInto<U> for T
where U: TryFrom<T>,
```

```rust
type Error = <U as TryFrom<T>>::Error
```

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

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

### Borrow Trait Implementation

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Apple.html

Allows immutable borrowing from an owned value.

```rust
impl<T> Borrow<T> for T
where T: ?Sized,
```

```rust
fn borrow(&self) -> &T
```

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

### BorrowMut Trait Implementation

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Apple.html

Allows mutable borrowing from an owned value.

```rust
impl<T> BorrowMut<T> for T
where T: ?Sized,
```

```rust
fn borrow_mut(&mut self) -> &mut T
```

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

### ToOwned Trait Implementation

Source: https://docs.rs/etcetera/latest/etcetera/app_strategy/struct.Apple.html

Provides methods to create owned data from borrowed data.

```rust
impl<T> ToOwned for T
where T: Clone,
```

```rust
type Owned = T
```

```rust
fn to_owned(&self) -> T
```

```rust
fn clone_into(&self, target: &mut T)
```
Tokens:
Raw