Envconfig

https://docs.rs/envconfig/0.11.1/
Admin
Envconfig is a Rust library that helps to initialize configuration structure from environment...
Tokens:6,344
Snippets:68
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Basic Configuration Initialization with envconfig

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/lib.rs.html

Demonstrates how to define a configuration struct with fields that map to environment variables, including optional fields and fields with default values. Shows how to initialize the configuration from the environment.

```rust
use std::env;
use envconfig::Envconfig;

#[derive(Envconfig)]
struct Config {
    #[envconfig(from = "DB_HOST")]
    pub db_host: String,

    #[envconfig(from = "DB_PORT")]
    pub db_port: Option<u16>,

    #[envconfig(from = "HTTP_PORT", default = "8080")]
    pub http_port: u16,
}

// We assume that those environment variables are set somewhere outside
env::set_var("DB_HOST", "localhost");
env::set_var("DB_PORT", "5432");

// Initialize config from environment variables
let config = Config::init_from_env().unwrap();

assert_eq!(config.db_host, "localhost");
assert_eq!(config.db_port, Some(5432));
assert_eq!(config.http_port, 8080);

```

--------------------------------

### Initialize Configuration from Environment Variables

Source: https://docs.rs/envconfig/0.11.1/envconfig

Demonstrates how to define a configuration struct with environment variable mappings and initialize it. Assumes environment variables are set externally. Requires the `Envconfig` derive macro.

```rust
use std::env;
use envconfig::Envconfig;

#[derive(Envconfig)]
struct Config {
    #[envconfig(from = "DB_HOST")]
    pub db_host: String,

    #[envconfig(from = "DB_PORT")]
    pub db_port: Option<u16>,

    #[envconfig(from = "HTTP_PORT", default = "8080")]
    pub http_port: u16,
}

// We assume that those environment variables are set somewhere outside
env::set_var("DB_HOST", "localhost");
env::set_var("DB_PORT", "5432");

// Initialize config from environment variables
let config = Config::init_from_env().unwrap();

assert_eq!(config.db_host, "localhost");
assert_eq!(config.db_port, Some(5432));
assert_eq!(config.http_port, 8080);
```

--------------------------------

### init()

Source: https://docs.rs/envconfig/0.11.1/envconfig/trait.Envconfig.html

Initializes a structure from environment variables. This method is deprecated and `init_from_env()` should be used instead. It can return an error if an environment variable is missing or fails to parse.

```APIDOC
## fn init()

### Description
Initializes structure from environment variables. Deprecated in favor of [`::init_from_env()`].

### Method
`init()`

### Parameters
None

### Errors
* Environment variable is missing.
* Failed to parse environment variable.

### Deprecation Warning
Deprecated since 0.9.0: Please use `init_from_env()` instead.
```

--------------------------------

### Initialize from Environment Variables (Deprecated)

Source: https://docs.rs/envconfig/0.11.1/envconfig/trait.Envconfig.html

Initializes a structure from environment variables. This method is deprecated and `init_from_env()` should be used instead. Errors can occur if environment variables are missing or cannot be parsed.

```rust
fn init() -> Result<Self, Error>
   where Self: Sized;
```

--------------------------------

### Envconfig Trait Documentation

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/traits.rs.html

This section details the methods available within the Envconfig trait for initializing structures from environment variables.

```APIDOC
## Trait: Envconfig

Indicates that a structure can be initialized from environment variables.

### Methods

#### `init()`

* **Description**: Initialize structure from environment variables. This method is deprecated in favor of `init_from_env()`.
* **Deprecated**: since="0.9.0", note="Function init() is deprecated. Please use init_from_env() instead."
* **Returns**: `Result<Self, Error>` - A Result containing the initialized structure or an Error.
* **Errors**: 
  - Environment variable is missing.
  - Failed to parse environment variable.

#### `init_from_env()`

* **Description**: Initialize structure from environment variables.
* **Returns**: `Result<Self, Error>` - A Result containing the initialized structure or an Error.
* **Errors**: 
  - Environment variable is missing.
  - Failed to parse environment variable.

#### `init_from_hashmap(hashmap: &HashMap<String, String>)`

* **Description**: Initialize structure from a hashmap.
* **Parameters**:
  - `hashmap` (*&HashMap<String, String>*) - Required - A HashMap containing environment variable key-value pairs.
* **Returns**: `Result<Self, Error>` - A Result containing the initialized structure or an Error.
* **Errors**: 
  - Environment variable is missing.
  - Failed to parse environment variable.
```

--------------------------------

### Initialize from Environment Variables

Source: https://docs.rs/envconfig/0.11.1/envconfig/trait.Envconfig.html

Initializes a structure directly from environment variables. This is the recommended method for environment-based initialization. Errors can occur if environment variables are missing or cannot be parsed.

```rust
fn init_from_env() -> Result<Self, Error>
   where Self: Sized;
```

--------------------------------

### init_from_hashmap()

Source: https://docs.rs/envconfig/0.11.1/envconfig/trait.Envconfig.html

Initializes a structure from a HashMap. It can return an error if an environment variable is missing or fails to parse.

```APIDOC
## fn init_from_hashmap(hashmap: &HashMap<String, String>)

### Description
Initialize structure from a hashmap.

### Method
`init_from_hashmap(hashmap: &HashMap<String, String>)`

### Parameters
#### Path Parameters
* **hashmap** (HashMap<String, String>) - Required - A HashMap containing string key-value pairs to initialize the structure.

### Errors
* Environment variable is missing.
* Failed to parse environment variable.
```

--------------------------------

### init_from_env()

Source: https://docs.rs/envconfig/0.11.1/envconfig/trait.Envconfig.html

Initializes a structure from environment variables. It can return an error if an environment variable is missing or fails to parse.

```APIDOC
## fn init_from_env()

### Description
Initialize structure from environment variables.

### Method
`init_from_env()`

### Parameters
None

### Errors
* Environment variable is missing.
* Failed to parse environment variable.
```

--------------------------------

### Initialize from HashMap

Source: https://docs.rs/envconfig/0.11.1/envconfig/trait.Envconfig.html

Initializes a structure from a provided hashmap. This is useful for testing or when configuration is managed in a map-like structure. Errors can occur if expected keys are missing or values cannot be parsed.

```rust
fn init_from_hashmap(
    hashmap: &HashMap<String, String>,
) -> Result<Self, Error>
   where Self: Sized;
```

--------------------------------

### Load Optional Environment Variable

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/utils.rs.html

Tries to load an environment variable, returning None if it's not present. Errors only if parsing fails.

```rust
use std::env;
use std::str::FromStr;

use crate::error::Error;
use std::collections::HashMap;

/// Tries to load an environment variable by name and parse it into type `T`.
/// If the environment variable is not present, it returns `None`.
///
/// This function can also use a hashmap as a fallback or for testing purposes.
///
/// # Errors
/// - Parsing failed
pub fn load_optional_var<T: FromStr, S: ::std::hash::BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
) -> Result<Option<T>, Error> {
    let opt_var = match hashmap {
        None => env::var(var_name).ok(),
        Some(hashmap) => hashmap.get(var_name).map(std::string::ToString::to_string),
    };

    match opt_var {
        None => Ok(None),
        Some(string_value) => string_value
            .parse::<T>()
            .map(Some)
            .map_err(|_| Error::ParseError { name: var_name }),
    }
}
```

--------------------------------

### Load Environment Variable with Default

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/utils.rs.html

Tries to load an environment variable, returning a default value if it's not present. Errors only if parsing fails.

```rust
use std::env;
use std::str::FromStr;

use crate::error::Error;
use std::collections::HashMap;

/// Tries to load an environment variable by name and parse it into type `T`.
/// If the environment variable is not present, it returns a default value.
///
/// This function can also use a hashmap as a fallback or for testing purposes.
///
/// # Errors
/// - Parsing failed
pub fn load_var_with_default<T: FromStr, S: ::std::hash::BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
    default: &'static str,
) -> Result<T, Error> {
    let opt_var = match hashmap {
        None => env::var(var_name).ok(),
        Some(hashmap) => hashmap.get(var_name).map(std::string::ToString::to_string),
    };

    let string_value = match opt_var {
        None => default,
        Some(ref value) => value,
    };

    string_value
        .parse::<T>()
        .map_err(|_| Error::ParseError { name: var_name })
}
```

--------------------------------

### Basic Envconfig Derive Macro Usage

Source: https://docs.rs/envconfig/0.11.1/envconfig/derive.Envconfig.html

Use the `#[derive(Envconfig)]` attribute on a struct to automatically implement the `Envconfig` trait. This allows configuration to be loaded from environment variables.

```rust
#[derive(Envconfig)]
{
    // Attributes available to this derive:
    #[envconfig]
}
```

--------------------------------

### load_var

Source: https://docs.rs/envconfig/0.11.1/envconfig/fn.load_var.html

Loads an environment variable by name and parses it into type T. It can optionally use a hashmap as a fallback or for testing purposes. Errors can occur if the environment variable is not present or if parsing fails.

```APIDOC
## load_var

### Description
Loads an environment variable by name and parses it into type `T`. This function can also use a hashmap as a fallback or for testing purposes.

### Signature
```rust
pub fn load_var<T: FromStr, S: BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
) -> Result<T, Error>
```

### Parameters
* `var_name` (&'static str): The name of the environment variable to load.
* `hashmap` (Option<&HashMap<String, String, S>>): An optional hashmap to use as a fallback or for testing.

### Returns
* `Result<T, Error>`: A `Result` containing the parsed value of type `T` on success, or an `Error` on failure.

### Errors
* Environment variable is not present
* Parsing failed
```

--------------------------------

### load_var_with_default

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/utils.rs.html

Tries to load an environment variable by name and parse it into type T. If the variable is not present, it returns a provided default value. Errors only if parsing fails.

```APIDOC
## load_var_with_default

### Description
Tries to load an environment variable by name and parse it into type `T`. If the environment variable is not present, it returns a default value. This function can also use a hashmap as a fallback or for testing purposes.

### Signature
```rust
pub fn load_var_with_default<T: FromStr, S: ::std::hash::BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
    default: &'static str,
) -> Result<T, Error>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `var_name` (&'static str): The name of the environment variable to load.
* `hashmap` (Option<&HashMap<String, String, S>>): An optional HashMap to use as a fallback for environment variable values.
* `default` (&'static str): The default string value to use if the environment variable is not found.

### Returns
* `Result<T, Error>`: A `Result` containing the parsed value of type `T` if successful, or an `Error` if parsing fails.

### Errors
* `Error::ParseError`: If the environment variable's value (or the default value) cannot be parsed into type `T`.
```

--------------------------------

### load_optional_var

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/utils.rs.html

Tries to load an environment variable by name and parse it into type T. If the variable is not present, it returns None. Errors only if parsing fails.

```APIDOC
## load_optional_var

### Description
Tries to load an environment variable by name and parse it into type `T`. If the environment variable is not present, it returns `None`. This function can also use a hashmap as a fallback or for testing purposes.

### Signature
```rust
pub fn load_optional_var<T: FromStr, S: ::std::hash::BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
) -> Result<Option<T>, Error>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `var_name` (&'static str): The name of the environment variable to load.
* `hashmap` (Option<&HashMap<String, String, S>>): An optional HashMap to use as a fallback for environment variable values.

### Returns
* `Result<Option<T>, Error>`: A `Result` containing `Some(T)` if the variable was found and parsed successfully, `None` if the variable was not found, or an `Error` if parsing fails.
```

--------------------------------

### Load Environment Variable

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/utils.rs.html

Loads an environment variable by name and parses it into type T. Can use a HashMap as a fallback. Errors if the variable is missing or parsing fails.

```rust
use std::env;
use std::str::FromStr;

use crate::error::Error;
use std::collections::HashMap;

/// Load an environment variable by name and parse it into type `T`.
///
/// This function can also use a hashmap as a fallback or for testing purposes.
///
/// # Errors
/// - Environment variable is not present
/// - Parsing failed
pub fn load_var<T: FromStr, S: ::std::hash::BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
) -> Result<T, Error> {
    match hashmap {
        None => env::var(var_name).ok(),
        Some(hashmap) => hashmap.get(var_name).map(std::string::ToString::to_string),
    }
    .ok_or(Error::EnvVarMissing { name: var_name })
    .and_then(|string_value| {
        string_value
            .parse::<T>()
            .map_err(|_| Error::ParseError { name: var_name })
    })
}
```

--------------------------------

### load_var_with_default

Source: https://docs.rs/envconfig/0.11.1/envconfig/fn.load_var_with_default.html

Tries to load an environment variable by name and parse it into type `T`. If the environment variable is not present, it returns a default value. This function can also use a hashmap as a fallback or for testing purposes.

```APIDOC
## load_var_with_default

### Description
Tries to load an environment variable by name and parse it into type `T`. If the environment variable is not present, it returns a default value. This function can also use a hashmap as a fallback or for testing purposes.

### Signature
```rust
pub fn load_var_with_default<T: FromStr, S: BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
    default: &'static str,
) -> Result<T, Error>
```

### Parameters

*   `var_name`: The name of the environment variable to load.
*   `hashmap`: An optional `HashMap` to use as a fallback or for testing.
*   `default`: The default value to return if the environment variable is not found.

### Returns

A `Result` containing the parsed environment variable value of type `T` or a default value if the variable is not found. Returns an `Error` if parsing fails.
```

--------------------------------

### load_optional_var

Source: https://docs.rs/envconfig/0.11.1/envconfig/fn.load_optional_var.html

Tries to load an environment variable by name and parse it into type `T`. If the environment variable is not present, it returns `None`. This function can also use a hashmap as a fallback or for testing purposes.

```APIDOC
## load_optional_var

### Description
Tries to load an environment variable by name and parse it into type `T`. If the environment variable is not present, it returns `None`. This function can also use a hashmap as a fallback or for testing purposes.

### Signature
```rust
pub fn load_optional_var<T: FromStr, S: BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
) -> Result<Option<T>, Error>
```

### Parameters

*   `var_name`: &'static str - The name of the environment variable to load.
*   `hashmap`: Option<&HashMap<String, String, S>> - An optional `HashMap` to use as a fallback or for testing.

### Returns

*   `Result<Option<T>, Error>` - Returns `Ok(Some(T))` if the variable is found and parsed successfully, `Ok(None)` if the variable is not found, or `Err(Error)` if parsing fails.
```

--------------------------------

### load_var_with_default Function Signature

Source: https://docs.rs/envconfig/0.11.1/envconfig/fn.load_var_with_default.html

This is the function signature for load_var_with_default. It specifies the generic types, parameters, and return type.

```rust
pub fn load_var_with_default<T: FromStr, S: BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
    default: &'static str,
) -> Result<T, Error>
```

--------------------------------

### Function Signature: load_optional_var

Source: https://docs.rs/envconfig/0.11.1/envconfig/fn.load_optional_var.html

Signature for the load_optional_var function. It takes the environment variable name, an optional HashMap for fallback, and returns a Result containing an Option of the parsed type or an Error.

```rust
pub fn load_optional_var<T: FromStr, S: BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
) -> Result<Option<T>, Error>
```

--------------------------------

### Envconfig Trait Definition

Source: https://docs.rs/envconfig/0.11.1/envconfig/trait.Envconfig.html

Defines the core methods for initializing a structure from environment variables or a hashmap. This trait is intended for types that can be configured via environment settings.

```rust
pub trait Envconfig {
    // Required methods
    fn init() -> Result<Self, Error>
       where Self: Sized;
    fn init_from_env() -> Result<Self, Error>
       where Self: Sized;
    fn init_from_hashmap(
        hashmap: &HashMap<String, String>,
    ) -> Result<Self, Error>
       where Self: Sized;
}
```

--------------------------------

### Rust envconfig load_var Function Signature

Source: https://docs.rs/envconfig/0.11.1/envconfig/fn.load_var.html

This is the function signature for load_var. It takes the environment variable name and an optional HashMap for fallback. It returns a Result containing the parsed type T or an Error.

```rust
pub fn load_var<T: FromStr, S: BuildHasher>(
    var_name: &'static str,
    hashmap: Option<&HashMap<String, String, S>>,
) -> Result<T, Error>
```

--------------------------------

### Envconfig Trait Definition

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/traits.rs.html

Defines the `Envconfig` trait with methods for initializing structures from environment variables and HashMaps. Includes deprecated `init()` and the recommended `init_from_env()`.

```rust
use crate::error::Error;
use std::collections::HashMap;

/// Indicates that structure can be initialize from environment variables.
pub trait Envconfig {
    /// Initialize structure from environment variables.
    /// Deprecated in favor of [`::init_from_env()`].
    ///
    /// # Errors
    /// - Environment variable is missing.
    /// - Failed to parse environment variable.
    #[deprecated(
        since = "0.9.0",
        note = "Function init() is deprecated. Please use init_from_env() instead."
    )]
    fn init() -> Result<Self, Error>
    where
        Self: Sized;

    /// Initialize structure from environment variables.
    ///
    /// # Errors
    /// - Environment variable is missing.
    /// - Failed to parse environment variable.
    fn init_from_env() -> Result<Self, Error>
    where
        Self: Sized;

    /// Initialize structure from a hashmap.
    ///
    /// # Errors
    /// - Environment variable is missing.
    /// - Failed to parse environment variable.
    fn init_from_hashmap(hashmap: &HashMap<String, String>) -> Result<Self, Error>
    where
        Self: Sized;
}
```

--------------------------------

### Error Enum

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/error.rs.html

The `Error` enum represents potential failures when initializing configuration from environment variables. It includes variants for missing environment variables and parsing failures.

```APIDOC
## Error Enum

### Description
Represents an error that may be returned by `fn init_from_env()` of trait `Envconfig`.

### Variants

- **EnvVarMissing** `{ name: &'static str }`
  Indicates that a required environment variable was not found.

- **ParseError** `{ name: &'static str }`
  Indicates that an environment variable was found but could not be parsed into the expected type.

### Display Implementation

Provides a user-friendly string representation for each error variant.

- `Error::EnvVarMissing { name }`: "Environment variable {name} is missing"
- `Error::ParseError { name }`: "Failed to parse environment variable {name}"

### Standard Error Implementation

Implements `std::error::Error` for the `Error` enum, returning `None` for the source of the error.
```

--------------------------------

### Error Enum Definition

Source: https://docs.rs/envconfig/0.11.1/envconfig/enum.Error.html

Defines the possible errors that can occur during environment variable initialization. Use this enum to handle specific error conditions like missing environment variables or failures during value parsing.

```rust
pub enum Error {
    EnvVarMissing {
        name: &'static str,
    },
    ParseError {
        name: &'static str,
    },
}
```

--------------------------------

### Error Enum Definition and Implementations

Source: https://docs.rs/envconfig/0.11.1/src/envconfig/error.rs.html

Defines the `Error` enum for missing environment variables and parsing failures. Implements `Display` for user-friendly error messages and `StdError` for compatibility with Rust's standard error handling.

```rust
//! Errors resulting from calling functions in this crate

use std::{error::Error as StdError, fmt};

/// Represents an error, that may be returned by `fn init_from_env()` of trait `Envconfig`.
#[derive(Debug, PartialEq)]
pub enum Error {
    EnvVarMissing { name: &'static str },
    ParseError { name: &'static str },
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            Error::EnvVarMissing { name } => {
                write!(f, "Environment variable {name} is missing")
            }
            Error::ParseError { name } => {
                write!(f, "Failed to parse environment variable {name}")
            }
        }
    }
}

impl StdError for Error {
    fn source(&self) -> Option<&(dyn StdError + 'static)> {
        None
    }
}
```
Tokens:
Raw