Struct SearchDirectoriesForFileName

pub struct SearchDirectoriesForFileName<'a, TFileName> { /* private fields */ }

A list of search directories that the config files will be searched under, scoped to a particular config file name.

Implementations

impl<'a, TFileName> SearchDirectoriesForFileName<'a, TFileName>

pub fn with_project<TProject>( self, project: TProject, ) -> SearchDirectoriesForProjectAndFileName<'a, TProject, TFileName>

Search for configuration files for the given project name and with this config file name.

The project name is usually the name of your application.

pub fn find_files<TDropinSuffix>( self, dropin_suffix: Option<TDropinSuffix>, ) -> Result<Files>

where TFileName: AsRef<OsStr>, TDropinSuffix: AsRef<OsStr>,

Returns an Iterator of (PathBuf, File)s for all the files found in the specified search directories. Only files named file_name under the search directories will be considered.

If dropin_suffix is provided, then directories named format!("{file_name}.d") under the search directories are treated as dropin directories. Only dropin files whose name ends with dropin_suffix will be considered. Note that if you intend to use a file extension as a suffix, then dropin_suffix must include the ., such as ".conf".

You will likely want to parse each file returned by this function according to whatever format they’re supposed to contain and merge them into a unified config object, with settings from later files overriding settings from earlier files. This function does not guarantee that the files are well-formed, only that they exist and could be opened for reading.

Errors

Any errors from reading non-existing directories and non-existing files are ignored. Apart from that, any I/O errors from walking the directories and from opening the files found within are propagated.

Examples

Get all config files for the system service foobar

… taking into account OS vendor configs, ephemeral overrides and sysadmin overrides.

let files =
    uapi_config::SearchDirectories::modern_system()
    .with_file_name("foobar.conf")
    .find_files(Some(".conf"))
    .unwrap();

This will locate /usr/etc/foobar.conf /run/foobar.conf, /etc/foobar.conf in that order and return the last one, then all dropins /usr/etc/foobar.d/*.conf, /run/foobar.d/*.conf, /etc/foobar.d/*.conf in lexicographical order.

Get the config files for the “foo.service” systemd system unit like systemd would do

let search_directories: uapi_config::SearchDirectories =
    // From `man systemd.unit`
    [
        "/run/systemd/generator.late",
        "/usr/lib/systemd/system",
        "/usr/local/lib/systemd/system",
        "/run/systemd/generator",
        "/run/systemd/system",
        "/etc/systemd/system",
        "/run/systemd/generator.early",
        "/run/systemd/transient",
        "/run/systemd/system.control",
        "/etc/systemd/system.control",
    ].into_iter()
    .map(|path| std::path::Path::new(path).into())
    .collect();
let files =
    search_directories
    .with_file_name("foo.service")
    .find_files(Some(".conf"))
    .unwrap();

This will locate /run/systemd/generator.late/foobar.service /usr/lib/systemd/system/foo.service, … in that order and return the last one, then all dropins /run/systemd/generator.late/foo.service.d/*.conf, /usr/lib/systemd/system/foo.service.d/*.conf, … in lexicographical order.

Trait Implementations

impl<'a, TFileName: Clone> Clone for SearchDirectoriesForFileName<'a, TFileName>

fn clone(&self) -> SearchDirectoriesForFileName<'a, TFileName>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, TFileName: Debug> Debug for SearchDirectoriesForFileName<'a, TFileName>

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

Formats the value using the given formatter.