Struct PathFinder 

pub struct PathFinder { /* private fields */ }

Path finder for discovering configuration directories.

Provides methods to find configuration directories following platform conventions (XDG on Unix, Known Folders on Windows, Application Support on macOS).

Implementations

impl PathFinder

pub fn discover_config(&self) -> ConfigDiscovery

Discover configuration with full diagnostics.

Searches all configuration locations and returns comprehensive information about what was found, including the preferred path for creating new configurations.

Examples

use cfgmatic_paths::PathsBuilder;

let finder = PathsBuilder::new("myapp").build();
let discovery = finder.discover_config();

println!("Preferred path: {}", discovery.preferred_path.display());
if let Some(found) = &discovery.found_path {
    println!("Found config at: {}", found.display());
}

for candidate in discovery.candidates {
    println!("  - {:?}: {} ({:?})",
        candidate.tier,
        candidate.path.display(),
        candidate.status
    );
}

pub fn discover_config_with_options( &self, options: &DiscoveryOptions, ) -> ConfigDiscovery

Discover configuration with custom options.

Allows customization of the discovery process including file patterns, fragment discovery, and legacy path inclusion.

Examples

use cfgmatic_paths::{DiscoveryOptions, FilePattern, PathsBuilder};

let finder = PathsBuilder::new("myapp").build();

let options = DiscoveryOptions::new()
    .with_pattern(FilePattern::extensions("config", &["toml", "yaml"]))
    .with_fragments(true)
    .with_fragment_dir("conf.d");

let discovery = finder.discover_config_with_options(&options);

pub fn find_config_files(&self, pattern: &FilePattern) -> Vec<ConfigCandidate>

Find all configuration files matching a pattern.

Searches all configuration directories for files matching the given pattern and returns them as candidates with status information.

Examples

use cfgmatic_paths::{FilePattern, PathsBuilder};

let finder = PathsBuilder::new("myapp").build();
let pattern = FilePattern::extensions("config", &["toml", "yaml", "json"]);

let configs = finder.find_config_files(&pattern);
for config in configs {
    if config.exists() {
        println!("Found: {}", config.path.display());
    }
}

pub fn find_fragments( &self, pattern: &FilePattern, fragment_dir_name: &str, ) -> Vec<PathBuf>

Find configuration fragments from conf.d-style directories.

Searches for fragment directories (like /etc/myapp/conf.d/) and returns all matching configuration files within them.

Examples

use cfgmatic_paths::{FilePattern, PathsBuilder};

let finder = PathsBuilder::new("myapp").build();
let pattern = FilePattern::glob("*.conf");

let fragments = finder.find_fragments(&pattern, "conf.d");
for frag in &fragments {
    println!("Fragment: {}", frag.display());
}

pub fn config_directories(&self) -> Vec<PathBuf>

Get all config directories where a file could be placed.

Returns all directories in priority order where configuration files could be located, regardless of whether they exist.

Examples

use cfgmatic_paths::PathsBuilder;

let finder = PathsBuilder::new("myapp").build();
let dirs = finder.config_directories();

for dir in dirs {
    println!("Config directory: {}", dir.display());
}

pub fn path_status(&self, path: &Path) -> PathStatus

Get the path status of a specific configuration path.

Examples

use cfgmatic_paths::PathsBuilder;

let finder = PathsBuilder::new("myapp").build();
let path = finder.preferred_config_file("config.toml");

let status = finder.path_status(&path);
println!("Path status: {:?}", status);

impl PathFinder

pub fn discover_with_rules(&self, rules: &ConfigRuleSet) -> RuleBasedDiscovery

Discover configuration files using a rule set.

Uses the provided rule set to discover all configuration files, including main files and fragments. Returns a detailed result with all matched files grouped by rule.

Examples

use cfgmatic_paths::{ConfigFileRule, ConfigRuleSet, FragmentRule, PathsBuilder};

let finder = PathsBuilder::new("myapp").build();

let rules = ConfigRuleSet::builder()
    .main_file(ConfigFileRule::toml("config").required(true))
    .main_file(ConfigFileRule::extensions("config", &["yaml"]))
    .fragments(FragmentRule::new("conf.d", "*.conf"))
    .build();

let discovery = finder.discover_with_rules(&rules);

for result in &discovery.main_files {
    println!("Rule: {:?}", result.rule.pattern);
    for found in &result.matches {
        println!("  Found: {:?}", found.path);
    }
}

impl PathFinder

pub fn user_dirs(&self) -> Vec<PathBuf>

Get all user directories.

pub fn local_dirs(&self) -> Vec<PathBuf>

Get all local directories.

pub fn system_dirs(&self) -> Vec<PathBuf>

Get all system directories.

pub fn all_dirs(&self) -> Vec<DirectoryInfo>

Get all directories with their tiers.

pub fn user_config_dir(&self) -> Option<PathBuf>

Get the primary user config directory (first user directory).

pub fn ensure_user_config_dir(&self) -> Result<PathBuf>

Ensure the user config directory exists, creating it if necessary.

Returns the path to the directory, or an error if creation fails.

Errors

Returns an error if no user config directory is found or if creation fails.

pub fn preferred_config_path(&self) -> PathBuf

Get the preferred user config path (without checking existence).

Returns the first user config directory path, regardless of whether it exists. This is useful for determining where to create a new configuration file.

Examples

use cfgmatic_paths::PathsBuilder;

let finder = PathsBuilder::new("myapp").build();
let path = finder.preferred_config_path();
println!("Config would be at: {}", path.display());

pub fn preferred_config_file(&self, filename: impl AsRef<Path>) -> PathBuf

Get the preferred config path with a filename appended.

Examples

use cfgmatic_paths::PathsBuilder;

let finder = PathsBuilder::new("myapp").build();
let path = finder.preferred_config_file("config.toml");
println!("Config file would be at: {}", path.display());

Trait Implementations

impl Debug for PathFinder

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

Formats the value using the given formatter.