Etcetera

The library provides two helper functions to select a strategy based on whether you are building a GUI or a CLI application. This ensures your application follows the correct OS conventions.

For GUI Applications

Use choose_native_strategy() to get the OS-specific strategy:

• Windows: Uses Windows strategy.
• macOS & iOS: Uses Apple strategy.
• Other (Linux/Unix): Uses Xdg strategy.

For CLI Applications

Use choose_base_strategy() to get the default strategy for CLI tools:

• Windows: Uses Windows strategy.
• Other (macOS, iOS, Linux/Unix): Uses Xdg strategy.

use etcetera::{choose_native_strategy, choose_base_strategy};

// For a GUI app
let strategy = choose_native_strategy().expect("Failed to resolve strategy");
let config = strategy.config_dir();

// For a CLI app
let strategy = choose_base_strategy().expect("Failed to resolve strategy");
let data = strategy.data_dir();

Depending on whether you are building a GUI application or a CLI application, you should choose a different strategy to ensure your application follows OS-specific conventions.

For GUI Applications

Use choose_native_strategy(args) to select the strategy most appropriate for the current operating system:

• Windows: Uses the Windows strategy.
• macOS/iOS: Uses the Apple strategy.
• Linux/Other: Uses the Xdg strategy.

For CLI Applications

Use choose_app_strategy(args) to select a more standard strategy for command-line tools:

• Windows: Uses the Windows strategy.
• macOS/iOS/Linux/Other: Uses the Xdg strategy.

Both functions return a Result<T, HomeDirError>.

use etcetera::app_strategy::{AppStrategyArgs, choose_native_strategy};

let args = AppStrategyArgs {
    top_level_domain: "com".to_string(),
    author: "Example".to_string(),
    app_name: "MyApp".to_string(),
};

// For a GUI app
let strategy = choose_native_strategy(args).expect("Failed to resolve strategy");
let config = strategy.config_dir();

To use an AppStrategy, you must first define your application's identity using AppStrategyArgs. This struct provides the metadata used to resolve platform-specific paths for configuration, data, and cache.

Key fields:

• top_level_domain: The TLD of your application (e.g., com, org, or io.github).
• author: The name of the application's author.
• app_name: The name of the application.

AppStrategyArgs provides two helper methods for generating identifiers:

1. bundle_id(): Returns a reverse-DNS style string (e.g., org.acme-corp.Frobnicator-Plus). It converts the author to lowercase and replaces spaces with hyphens, and replaces spaces in the app name with hyphens.
2. unixy_name(): Returns a lowercase, hyphenated version of the app name, suitable for binary names (e.g., frobnicator-plus).

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(),
};

// bundle_id() -> "org.acme-corp.Frobnicator-Plus"
// unixy_name() -> "frobnicator-plus"

The AppStrategy trait allows your application to retrieve standard platform-specific directories. This ensures your app follows the correct conventions for where to store configuration, data, and cache files.

Core Directory Methods

• home_dir(): Returns the current user's home directory.
• config_dir(): Returns the directory for application configuration.
• data_dir(): Returns the directory for application data.
• cache_dir(): Returns the directory for application cache.
• state_dir(): Returns an Option<PathBuf> for the state directory. Supported by Xdg and Unix strategies.
• runtime_dir(): Returns an Option<PathBuf> for the runtime directory. Supported by Xdg and Unix strategies.

Path Helper Methods

Instead of manually joining paths, use these helpers to construct paths inside specific directories:

• in_config_dir(path)
• in_data_dir(path)
• in_cache_dir(path)
• in_state_dir(path) (Returns Option)
• in_runtime_dir(path) (Returns Option)

Note: For runtime_dir, this library does not enforce the ownership or persistence requirements specified by the XDG Base Directory Specification.

The Windows strategy implements path resolution following Windows conventions (based on the SHGetKnownFolderPath API). It organizes application files under an author/app_name hierarchy within standard Windows directories.

Directory Mapping

When initialized with AppStrategyArgs, the following paths are resolved:

• Config Directory: {APPDATA}/{author}/{app_name}/config
• Data Directory: {APPDATA}/{author}/{app_name}/data
• Cache Directory: {LOCALAPPDATA}/{author}/{app_name}/cache
• Home Directory: Resolved via Windows system APIs (e.g., USERPROFILE).

Note that state_dir() and runtime_dir() currently return None for this strategy.

Implementation Details

On Windows, this strategy uses the SHGetKnownFolderPath API. On non-Windows platforms, it falls back to Windows default directory patterns. The strategy reads from the following environment variables:

• USERPROFILE
• APPDATA
• LOCALAPPDATA

use etcetera::app_strategy::{AppStrategy, AppStrategyArgs, Windows};

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 config = app_strategy.config_dir(); // e.g., AppData/Roaming/Acme Corp/Frobnicator Plus/config
let cache = app_strategy.cache_dir();    // e.g., AppData/Local/Acme Corp/Frobnicator Plus/cache

The Windows strategy implements directory resolution following Windows conventions. It prioritizes environment variables (USERPROFILE, APPDATA, LOCALAPPDATA) and falls back to the Windows SHGetKnownFolderPath API. If environment variables are missing, it uses default Windows directory paths.

Key directory mappings:

• home_dir(): Returns the user profile directory.
• config_dir(): Maps to data_dir() (typically APPDATA).
• data_dir(): Uses APPDATA environment variable or falls back to AppData/Roaming within the home directory.
• cache_dir(): Uses LOCALAPPDATA environment variable or falls back to AppData/Local within the home directory.
• state_dir(): Always returns None.
• runtime_dir(): Always returns None.

use etcetera::base_strategy::BaseStrategy;
use etcetera::base_strategy::Windows;

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

let home = base_strategy.home_dir();
let config = base_strategy.config_dir();
let cache = base_strategy.cache_dir();