Struct ConfigDirs 

pub struct ConfigDirs { /* private fields */ }

Common ground for the three way to look for configuration paths.

Implementations

impl ConfigDirs

pub const fn empty() -> Self

Empty list of paths to search configs in.

use config_finder::ConfigDirs;

assert!(ConfigDirs::empty().paths().is_empty());

pub fn search( &self, app: impl AsRef<Path>, base: impl AsRef<OsStr>, ext: impl AsRef<OsStr>, ) -> ConfigCandidates<'_>

Iterator yielding possible config files or directories.

Behaviour

Will search for app/base.ext and app/base.local.ext. If the extension is empty, it will search for app/base and app/base.local instead.

Giving an empty app or extension is valid, see examples below.

Example

use std::path::Path;

use config_finder::ConfigDirs;

let mut cd = ConfigDirs::empty();
let mut app_files = cd.add_path("start")
                      .add_path("second")
                      .add_path("end")
                      .search("my-app", "main", "kdl");

let wl = app_files.next()?;
assert_eq!(wl.path(), Path::new("start/.config/my-app/main.kdl"));
assert_eq!(wl.local_path(), Path::new("start/.config/my-app/main.local.kdl"));

let wl = app_files.next_back()?;
assert_eq!(wl.path(), Path::new("end/.config/my-app/main.kdl"));
assert_eq!(wl.local_path(), Path::new("end/.config/my-app/main.local.kdl"));

let wl = app_files.next()?;
assert_eq!(wl.path(), Path::new("second/.config/my-app/main.kdl"));
assert_eq!(wl.local_path(), Path::new("second/.config/my-app/main.local.kdl"));

assert_eq!(app_files.next(), None);

Without an app subdirectory:

use std::path::Path;

use config_finder::ConfigDirs;

let mut cd = ConfigDirs::empty();
cd.add_path("start");
let mut app_files =
    cd.add_path("start").search("", "my-app", "kdl");

let wl = app_files.next()?;
assert_eq!(wl.path(), Path::new("start/.config/my-app.kdl"));
assert_eq!(wl.local_path(), Path::new("start/.config/my-app.local.kdl"));

assert_eq!(app_files.next(), None);

Without an extension:

use std::path::Path;

use config_finder::ConfigDirs;

let mut cd = ConfigDirs::empty();
let mut app_files =
    cd.add_path("start").search("my-app", "main", "");

let wl = app_files.next()?;
assert_eq!(wl.path(), Path::new("start/.config/my-app/main"));
assert_eq!(wl.local_path(), Path::new("start/.config/my-app/main.local"));

assert_eq!(app_files.next(), None);

impl ConfigDirs

Accessors

pub fn paths(&self) -> &[PathBuf]

Look at the config paths already added.

use std::path::PathBuf;

use config_finder::ConfigDirs;

let mut cd = ConfigDirs::empty();
assert!(cd.paths().is_empty());
cd.add_path("my/config/path");
assert_eq!(cd.paths(), &[PathBuf::from("my/config/path/.config")]);

impl ConfigDirs

Adding paths to the list

pub fn add_path<P: AsRef<Path>>(&mut self, path: P) -> &mut Self

Adds path to the list of directories to check, if not previously added.

This path should not contain the config directory (or file) passed during construction.

Behaviour

This function will add .config to the given path if it does not end with that already. This means you can just pass the workspace for your application (e.g. the root of a git repository) and this type will look for workspace/.config/<app>.

Examples

use std::path::PathBuf;

use config_finder::ConfigDirs;

let mut cd = ConfigDirs::empty();
assert!(cd.paths().is_empty());
cd.add_path("my/config/path")
  .add_path("my/other/path/.config"); // .config already present at the end
assert_eq!(cd.paths(), &[
    PathBuf::from("my/config/path/.config"),
    PathBuf::from("my/other/path/.config"), // it has not been added again
]);

pub fn add_all_paths_until<P1: AsRef<Path>, P2: AsRef<Path>>( &mut self, start: P1, container: P2, ) -> &mut Self

Adds all the paths starting from start and going up until a parent is out of container.

This includes container.

If start does not starts with container, this will do nothing since start is already out of the containing path.

Behaviour

See Self::add_path(). This behaviour will be applied to each path added by this method.

Examples

use std::path::PathBuf;

use config_finder::ConfigDirs;

let mut cd = ConfigDirs::empty();
assert!(cd.paths().is_empty());
cd.add_all_paths_until("look/my/config/path", "look/my");
assert_eq!(cd.paths(), &[
    PathBuf::from("look/my/config/path/.config"),
    PathBuf::from("look/my/config/.config"),
    PathBuf::from("look/my/.config"),
]);

"other" is not a root of "my/config/path":

use config_finder::ConfigDirs;

let mut cd = ConfigDirs::empty();
assert!(cd.paths().is_empty());
cd.add_all_paths_until("my/config/path", "other");
assert!(cd.paths().is_empty());

pub fn add_platform_config_dir(&mut self) -> &mut Self

Adds the platform’s config directory to the list of paths to check.

Platform	Value	Example
Unix(1)	$XDG_CONFIG_HOME or $HOME/.config	/home/alice/.config
Windows	{FOLDERID_RoamingAppData}	C:\Users\Alice\AppData\Roaming

(1): Unix stand for both Linux and macOS here. Since this crate is primarily intended for CLI applications & tools, having the macOS files hidden in $HOME/Library/Application Support is not practical.

Behaviour

This method will not add .config, unlike Self::add_path().

Examples

use std::path::PathBuf;

use config_finder::ConfigDirs;

if cfg!(windows) {
    let mut cd = ConfigDirs::empty();
    cd.add_platform_config_dir()
      .add_platform_config_dir(); // Adding twice does not affect the final list
    assert_eq!(cd.paths().len(), 1);
    assert!(cd.paths()[0].ends_with("AppData/Roaming"));
} else {
    std::env::set_var("HOME", "/home/testuser");

    // With `XDG_CONFIG_HOME` unset
    std::env::remove_var("XDG_CONFIG_HOME");
    let mut cd = ConfigDirs::empty();
    cd.add_platform_config_dir();
    assert_eq!(cd.paths(), &[PathBuf::from("/home/testuser/.config")]);

    // With `XDG_CONFIG_HOME` set
    std::env::set_var("XDG_CONFIG_HOME", "/home/.shared_configs");
    let mut cd = ConfigDirs::empty();
    cd.add_platform_config_dir();
    assert_eq!(cd.paths(), &[PathBuf::from("/home/.shared_configs")]); // No `.config` added
}

pub fn add_current_dir(&mut self) -> Result<&mut Self>

Adds the current directory to the list of paths to search in.

Errors

Returns an error if std::env::current_dir() fails.

Behaviour

See Self::add_path().

Examples

use config_finder::ConfigDirs;

let current_dir = std::env::current_dir().unwrap().join(".config");

let mut cd = ConfigDirs::empty();
cd.add_current_dir();
assert_eq!(cd.paths(), &[current_dir]);

impl ConfigDirs

Unix-only methods

pub fn add_root_etc(&mut self) -> &mut Self

Adds /etc to the list of paths to checks if not previously added.

Behaviour

This method will not add .config, unlike Self::add_path().

Examples

use std::path::PathBuf;

use config_finder::ConfigDirs;

let mut cd = ConfigDirs::empty();
cd.add_root_etc();
assert_eq!(cd.paths(), &[PathBuf::from("/etc")]);

Trait Implementations

impl Clone for ConfigDirs

fn clone(&self) -> ConfigDirs

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ConfigDirs

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ConfigDirs

fn default() -> ConfigDirs

Returns the “default value” for a type.