Crate options 

More Options  

More Options is a library for defining configuration options in Rust. Options can be initialized in code, bound from configuration, and/or composed through dependency injection (DI).

You may be looking for:

• User Guide
• API Documentation
• Release Notes

Features

This crate provides the following features:

• default - Abstractions for options
• async - Enable options in asynchronous contexts
• di - Dependency injection extensions
• cfg - Dependency injection extensions to bind configurations to options

Options Pattern

The options pattern uses structures to provide strongly typed access to groups of related settings without having to know how the settings were configured. The settings can be set explicitly in code or they can come from an external configuration source such as a file.

Consider the following options:

pub struct EndpointOptions {
    pub url: String,
    pub retries: usize,
}

These might be used by a HTTP client as follows:

use options::Options;
use std::rc::Rc;

pub struct HttpClient {
    options: Rc<EndpointOptions>,
}

impl HttpClient {
    pub fn new(options: Rc<EndpointOptions>) -> Self {
        Self { options }
    }

    pub fn retries(&self) -> usize {
        self.options.value().retries
    }
}

Options in Action

The defined options can be used in any number of ways, including just explicitly specifying the settings.

use crate::{EndpointOptions, HttpClient};
use std::rc::Rc;

fn main() {
    let options = Rc::new(EndpointOptions {
        url: "https://tempuri.org",
        retries: 2,
    });
    let client = HttpClient::new(options);
    
    // TODO: use the client
}

If you expect to process your options from an external data source, then you’ll almost certainly require supporting deserialization using serde as follows:

use serde::Deserialize;

#[derive(Deserialize)]
pub struct EndpointOptions {
    pub url: String,
    pub retries: usize,
}

Suppose you had the following appSettings.json file:

{
  "url": "https://tempuri.org",
  "retries": 3
}

You can construct the options from the settings by including the more-config crate as follows:

use crate::{EndpointOptions, HttpClient};
use config::prelude::*;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error + 'static>> {
    let config = config::builder().add_json_file("appsettings.json").build()?;
    let options: EndpointOptions = config.reify()?;
    let client = HttpClient::new(options);

    // TODO: use the client

    Ok(())
}

You can go one step further and combine that configuration with the more-di crate to assemble all of the pieces for you:

use crate::{EndpointOptions, HttpClient};
use config::prelude::*;
use di::ServiceCollection;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error + 'static>> {
    let config = config::builder().add_json_file("appsettings.json").build()?;
    let provider = ServiceCollection::new()
        .add(transient_as_self::<HttpClient>())
        .apply_config::<EndpointOptions>(config)
        .build_provider()?;
    let client = provider.get_required::<HttpClient>();

    // TODO: use the client

    Ok(())
}

Examples

Basic

A basic demonstration application is provided that combines in-memory settings resolves them as a set of options. Run it with:

cargo run --example basic

Dependency Injection

A variant of the demonstration application is provided that illustrates how to provide composition, which removes the setup ceremony, using dependency injection (DI). Run it with:

cargo run --example di

Minimum Supported Rust Version

When increasing the minimum supported Rust version (MSRV), the new version must have been released at least six months ago. The current MSRV is 1.79.

License

This project is licensed under the MIT license.

Modules

preludedi or cfg

Contains the library prelude.

validation

Provides options validation.

Structs

Cache

Represents a monitored cache of configured options.

DefaultFactory

Represents the default factory used to create configuration options.

DefaultMonitor

Represents the default implementation for notifications when option instances change.

Manager

Represents an object that manages options and option snapshots.

Subscription

Represents a change subscription.

Traits

ChangeTokenSource

Used to fetch a change token to track options changes.

Configure

Configures options.

Factory

Defines the behavior of a configuration options factory.

Monitor

Defines the behavior for notifications when options instances change.

PostConfigure

Configures options.

Snapshot

Defines the behavior for a snapshot of configuration options.

ValueNon-async

Type Aliases

Refdi

Represents the type alias for an options reference.