libenvpp

The library is designed around the concept of a prefix. This allows you to group related environment variables (e.g., MYPROG_LOG_FILE_PATH, MYPROG_NUM_THREADS) under a single namespace.

1. Create a prefix using env::prefix("PREFIX").
2. Register variables using register_variable<T>(name) (optional) or register_required_variable<T>(name) (required).
3. Call parse_and_validate() on the prefix object. This consumes the prefix object; do not use the prefix after this call.
4. Check the result using .ok(). If successful, retrieve values using .get(id) for required variables or .get_or(id, default_value) for optional ones.

#include <libenvpp/env.hpp>

int main() {
    auto pre = env::prefix("MYPROG");

    // Register an optional variable
    const auto log_path_id = pre.register_variable<std::filesystem::path>("LOG_FILE_PATH");
    // Register a required variable
    const auto num_threads_id = pre.register_required_variable<unsigned int>("NUM_THREADS");

    // Parse and validate (consumes 'pre')
    const auto parsed_and_validated_pre = pre.parse_and_validate();

    if (parsed_and_validated_pre.ok()) {
        const auto log_path = parsed_and_validated_pre.get_or(log_path_id, "/default/log/path");
        const auto num_threads = parsed_and_validated_pre.get(num_threads_id);
    } else {
        std::cout << parsed_and_validated_pre.warning_message();
        std::cout << parsed_and_validated_pre.error_message();
    }
}

If you need logic that applies only to a specific environment variable (rather than all variables of a certain type), you can pass a callable (function, lambda, or functor) directly to register_variable or register_required_variable.

This callable acts as both the parser and the validator. If you use this method, the default_parser and default_validator for that type are not automatically invoked. You must manually delegate to them if needed. Errors should be reported by throwing env::parser_error or env::validation_error.

std::filesystem::path path_parser_and_validator(const std::string_view str)
{
    const auto log_path = std::filesystem::path(str);
    if (!std::filesystem::exists(log_path)) {
        if (!std::filesystem::create_directory(log_path)) {
            throw env::validation_error{"Unable to create log directory"};
        }
    } else if (!std::filesystem::is_directory(log_path)) {
        throw env::validation_error{"Log path is not a directory"};
    }
    return log_path;
}

// Usage
auto pre = env::prefix("CUSTOM_PARSER_AND_VALIDATOR");
const auto path_id = pre.register_required_variable<std::filesystem::path>("LOG_PATH", path_parser_and_validator);

To support parsing of user-defined types, specialize the env::default_parser<T> template. The specialization must implement a call operator that accepts a std::string_view and returns the parsed type.

To avoid reinventing the wheel, you should delegate the parsing of primitive members to the existing env::default_parser implementations.

struct program_data {
    int number;
    float percent;
};

namespace env {
template <>
struct default_parser<program_data> {
    program_data operator()(const std::string_view str) const
    {
        const auto split_str = split(str, ',');
        if (split_str.size() != 2) {
            throw parser_error{"Expected 2 comma delimited values"};
        }

        auto parsed_data = program_data{};
        // Delegate to existing primitive parsers
        parsed_data.number = default_parser<int>{}(split_str[0]);
        parsed_data.percent = default_parser<float>{}(split_str[1]);

        return parsed_data;
    }
};
}

To ensure an environment variable falls within a specific inclusive range, use register_range<T>(name, min, max).

• The min and max values are inclusive.
• Range variables can be either optional or required.
• They use the default_parser and default_validator for the type.
• Note: You cannot provide a custom parser/validator function for a range variable; use a normal variable for that.
• Note: When using get_or to provide a default value for an optional range variable, the range requirement is not enforced on the default value.

auto pre = env::prefix("RANGE");
const auto num_threads_id = pre.register_range<unsigned int>("NUM_THREADS", 1, std::thread::hardware_concurrency());
const auto parsed_and_validated_pre = pre.parse_and_validate();

if (parsed_and_validated_pre.ok()) {
    const auto num_threads = parsed_and_validated_pre.get_or(num_threads_id, std::thread::hardware_concurrency());
}