### Build Examples with CMake

Source: https://github.com/ph3at/libenvpp/blob/main/CMakeLists.txt

Automatically discovers and builds all C++ files in the examples directory when LIBENVPP_EXAMPLES is enabled.

```cmake
if(LIBENVPP_EXAMPLES)
	file(GLOB_RECURSE LIBENVPP_EXAMPLES_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/examples/*.cpp")

	foreach(LIBENVPP_EXAMPLE_SOURCE ${LIBENVPP_EXAMPLES_SOURCES})
		get_filename_component(LIBENVPP_EXAMPLE_TARGET ${LIBENVPP_EXAMPLE_SOURCE} NAME_WE)
		add_executable(${LIBENVPP_EXAMPLE_TARGET} "${LIBENVPP_EXAMPLE_SOURCE}")
		libenvpp_set_compiler_parameters(${LIBENVPP_EXAMPLE_TARGET})
		target_link_libraries(${LIBENVPP_EXAMPLE_TARGET} PRIVATE libenvpp)
	endforeach()
endif()
```

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

### Configure Installation Targets

Source: https://github.com/ph3at/libenvpp/blob/main/CMakeLists.txt

Sets up installation rules for headers, libraries, and CMake package configuration files.

```cmake
if(LIBENVPP_INSTALL)
	# Libenvpp installation.
	include(CMakePackageConfigHelpers)

	set(LIBENVPP_PROJECT_CONFIG_OUT "${CMAKE_CURRENT_BINARY_DIR}/libenvpp-config.cmake")
	set(LIBENVPP_VERSION_CONFIG_FILE "${CMAKE_CURRENT_BINARY_DIR}/libenvpp-config-version.cmake")
	install(DIRECTORY ${PROJECT_SOURCE_DIR}/include/
		DESTINATION include
	)
	install(TARGETS libenvpp
		EXPORT libenvpp
		LIBRARY DESTINATION lib
		ARCHIVE DESTINATION lib
		INCLUDES DESTINATION include
	)
	install(EXPORT libenvpp
		DESTINATION lib/cmake/libenvpp
		NAMESPACE libenvpp::
		FILE libenvpp-config-targets.cmake
	)
	configure_package_config_file(cmake/libenvpp-config.cmake.in
		"${LIBENVPP_PROJECT_CONFIG_OUT}"
		INSTALL_DESTINATION lib/cmake/libenvpp
	)
	write_basic_package_version_file("${LIBENVPP_VERSION_CONFIG_FILE}"
		VERSION ${LIBENVPP_VERSION}
		COMPATIBILITY SameMajorVersion
	)
	install(FILES "${LIBENVPP_PROJECT_CONFIG_OUT}" "${LIBENVPP_VERSION_CONFIG_FILE}"
		DESTINATION lib/cmake/libenvpp
	)
endif()
```

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

### Integrate Libenvpp with CMake FetchContent

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Integrates libenvpp into a CMake project using the FetchContent mechanism. Ensure LIBENVPP_INSTALL is set if installation is desired.

```cmake
set(LIBENVPP_INSTALL ON CACHE BOOL "" FORCE) # If installation is desired.
FetchContent_Declare(libenvpp
    GIT_REPOSITORY https://github.com/ph3at/libenvpp.git
    GIT_TAG v1.5.2
)
FetchContent_MakeAvailable(libenvpp)

# ...

target_link_libraries(myproject PUBLIC
    libenvpp::libenvpp
)
```

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

### Handling Deprecated Variables in C++

Source: https://context7.com/ph3at/libenvpp/llms.txt

Register deprecated environment variables to guide users during migration. Provide a clear message indicating the replacement variable.

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

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

    // Register deprecated variable with migration message
    pre.register_deprecated(
        "LOG_FILE_PATH",
        "has been deprecated since v2.0, use 'MYPROG_LOG_FILE' instead"
    );

    // Register the new replacement variable
    const auto log_file_id = pre.register_variable<std::filesystem::path>("LOG_FILE");

    const auto parsed_and_validated_pre = pre.parse_and_validate();

    if (parsed_and_validated_pre.ok()) {
        const auto log_file = parsed_and_validated_pre.get_or(log_file_id, "/default/log/file");
        std::cout << "Log file: " << log_file << std::endl;
    } else {
        std::cout << parsed_and_validated_pre.warning_message();
        std::cout << parsed_and_validated_pre.error_message();
    }

    return EXIT_SUCCESS;
}

// Using deprecated variable:
// $ MYPROG_LOG_FILE_PATH=/var/log/old.log ./example
// Error  : Validation error for environment variable 'MYPROG_LOG_FILE_PATH': has been deprecated since v2.0, use 'MYPROG_LOG_FILE' instead

// Using new variable:
// $ MYPROG_LOG_FILE=/var/log/app.log ./example
// Log file: /var/log/app.log
```

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

### Configure CMake for Libenvpp Dependency

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Configures a CMake project to find and use libenvpp as a dependency. This is typically used in a myproject-config.cmake.in file when installation is desired.

```cmake
# ...

include(CMakeFindDependencyMacro)
find_dependency(libenvpp REQUIRED)

# ...
```

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

### Basic Environment Variable Parsing

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Demonstrates registering, parsing, and validating environment variables with a prefix. Use this for standard environment variable management.

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

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

    const auto log_path_id = pre.register_variable<std::filesystem::path>("LOG_FILE_PATH");
    const auto num_threads_id = pre.register_required_variable<unsigned int>("NUM_THREADS");

    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);

        std::cout << "Log path   : " << log_path << std::endl;
        std::cout << "Num threads: " << num_threads << std::endl;
    } else {
        std::cout << parsed_and_validated_pre.warning_message();
        std::cout << parsed_and_validated_pre.error_message();
    }

    return EXIT_SUCCESS;
}
```

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

### Console Output With Both Variables Set

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Shows the successful output when both environment variables are correctly set.

```console
$ MYPROG_LOG_FILE_PATH=/var/log/file MYPROG_NUM_THREADS=4 ./libenvpp_simple_usage_example
Log path   : "/var/log/file"
Num threads: 4
```

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

### Generate Help Message for Environment Variables

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Generates a formatted help message for environment variables registered under a specific prefix. It lists each variable, indicating whether it is required or optional.

```cpp
auto pre = env::prefix("MYPROG");

const auto log_path_id = pre.register_variable<std::filesystem::path>("LOG_FILE_PATH");
const auto num_threads_id = pre.register_required_variable<unsigned int>("NUM_THREADS");

std::cout << pre.help_message();
```

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

### Register environment variables

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Define a prefix and register variables as optional or required.

```cpp
auto pre = env::prefix("MYPROG");

const auto log_path_id = pre.register_variable<std::filesystem::path>("LOG_FILE_PATH");
const auto num_threads_id = pre.register_required_variable<unsigned int>("NUM_THREADS");
```

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

### Parse and validate environment variables

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Execute the parsing and validation process after registration.

```cpp
const auto parsed_and_validated_pre = pre.parse_and_validate();
```

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

### Console Output With Required Variable Set

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Demonstrates the output when only the required environment variable is provided.

```console
$ MYPROG_NUM_THREADS=4 ./libenvpp_simple_usage_example
Log path   : "/default/log/path"
Num threads: 4
```

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

### Generate Help Messages in C++

Source: https://context7.com/ph3at/libenvpp/llms.txt

Automatically generate formatted help messages for your application's environment variables. This includes listing all registered variables and their status (required/optional).

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

int main(int argc, char* argv[])
{
    auto pre = env::prefix("MYAPP");

    const auto log_path_id = pre.register_variable<std::filesystem::path>("LOG_PATH");
    const auto num_threads_id = pre.register_required_variable<unsigned int>("NUM_THREADS");
    const auto debug_id = pre.register_variable<bool>("DEBUG");
    const auto timeout_id = pre.register_range<int>("TIMEOUT_MS", 100, 30000);

    // Print help if requested
    if (argc > 1 && std::string(argv[1]) == "--help") {
        std::cout << pre.help_message();
        return EXIT_SUCCESS;
    }

    const auto parsed_and_validated_pre = pre.parse_and_validate();

    if (!parsed_and_validated_pre.ok()) {
        std::cout << parsed_and_validated_pre.error_message();
        std::cout << "\nUsage:"
        std::cout << parsed_and_validated_pre.help_message();
        return EXIT_FAILURE;
    }

    return EXIT_SUCCESS;
}

// $ ./example --help
// Prefix 'MYAPP_' supports the following 4 environment variable(s):
//     'MYAPP_LOG_PATH' optional
//     'MYAPP_NUM_THREADS' required
//     'MYAPP_DEBUG' optional
//     'MYAPP_TIMEOUT_MS' optional
```

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

### Configure Unit Tests with CMake

Source: https://github.com/ph3at/libenvpp/blob/main/CMakeLists.txt

Defines the test executable and links necessary dependencies when LIBENVPP_TESTS is enabled.

```cmake
if(LIBENVPP_TESTS)
	include(CTest)
	include(Catch)
	add_executable(libenvpp_tests
		"test/levenshtein_test.cpp"
		"test/libenvpp_environment_test.cpp"
		"test/libenvpp_parser_test.cpp"
		"test/libenvpp_test.cpp"
		"test/libenvpp_testing_test.cpp"
	)
	libenvpp_set_compiler_parameters(libenvpp_tests)
	target_link_libraries(libenvpp_tests PRIVATE libenvpp Catch2::Catch2WithMain)

	# Set test as VS startup if libenvpp is master project.
	if(LIBENVPP_MASTER_PROJECT)
		set_property(DIRECTORY PROPERTY VS_STARTUP_PROJECT libenvpp_tests)
	endif()

	catch_discover_tests(libenvpp_tests)
endif()
```

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

### Handle Errors and Warnings with Parsed Prefix

Source: https://context7.com/ph3at/libenvpp/llms.txt

Access detailed error and warning information programmatically after parsing environment variables. This is useful for implementing robust error handling in your application.

```cpp
#include <cstdlib>
#include <iostream>

#include <libenvpp/env.hpp>

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

    const auto port_id = pre.register_required_range<int>("PORT", 1, 65535);
    const auto timeout_id = pre.register_range<int>("TIMEOUT", 1, 3600);

    const auto parsed_pre = pre.parse_and_validate();

    // Check if there are any errors or warnings
    if (!parsed_pre.ok()) {
        // Get formatted messages
        std::cout << parsed_pre.warning_message();
        std::cout << parsed_pre.error_message();

        // Access individual errors programmatically
        for (const auto& err : parsed_pre.errors()) {
            std::cerr << "Error ID: " << err.get_id() << std::endl;
            std::cerr << "Variable: " << err.get_name() << std::endl;
            std::cerr << "Message: " << err.what() << std::endl;
        }

        // Access individual warnings
        for (const auto& warn : parsed_pre.warnings()) {
            std::cerr << "Warning for: " << warn.get_name() << std::endl;
            std::cerr << "Message: " << warn.what() << std::endl;
        }

        return EXIT_FAILURE;
    }

    const auto port = parsed_pre.get(port_id);
    const auto timeout = parsed_pre.get_or(timeout_id, 30);

    std::cout << "Port: " << port << ", Timeout: " << timeout << std::endl;
    return EXIT_SUCCESS;
}

// $ CONFIG_PROT=8080 ./example
// Warning: Unrecognized environment variable 'CONFIG_PROT' set, did you mean 'CONFIG_PORT'?
// Error  : Environment variable 'CONFIG_PORT' not set
```

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

### Include libenvpp header

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Include the main header file to access the library functionality.

```cpp
#include <libenvpp/env.hpp>
```

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

### Accessing Prefixless Environment Variables in C++

Source: https://context7.com/ph3at/libenvpp/llms.txt

Use standalone env::get and env::get_or functions for direct access to environment variables without prefix registration.

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

int main()
{
    // Get optional variable with default value
    const auto log_path = env::get_or<std::filesystem::path>("LOG_FILE_PATH", "/default/log/path");

    // Get required variable - returns expected<T, error>
    const auto num_threads = env::get<unsigned int>("NUM_THREADS");

    if (num_threads.has_value()) {
        std::cout << "Log path   : " << log_path << std::endl;
        std::cout << "Num threads: " << num_threads.value() << std::endl;
    } else {
        // Access error information
        std::cout << num_threads.error().what() << std::endl;
    }

    return EXIT_SUCCESS;
}
```

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

### Custom Environment

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Passing a custom map to override system environment variables during parsing.

```APIDOC
## Custom Environment

### Description
Allows passing a `std::unordered_map<std::string, std::string>` to `prefix::parse_and_validate` to act as the source for environment variables instead of the system environment.
```

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

### Registering Variables with a Prefix in C++

Source: https://context7.com/ph3at/libenvpp/llms.txt

Use env::prefix to group variables under a common namespace, enabling automatic validation and typo detection.

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

int main()
{
    // Create a prefix - all variables will start with "MYPROG_"
    auto pre = env::prefix("MYPROG");

    // Register an optional variable (no error if not set)
    const auto log_path_id = pre.register_variable<std::filesystem::path>("LOG_FILE_PATH");

    // Register a required variable (error if not set)
    const auto num_threads_id = pre.register_required_variable<unsigned int>("NUM_THREADS");

    // Parse and validate all registered variables
    const auto parsed_and_validated_pre = pre.parse_and_validate();

    if (parsed_and_validated_pre.ok()) {
        // Get optional variable with default value
        const auto log_path = parsed_and_validated_pre.get_or(log_path_id, "/default/log/path");
        // Get required variable (returns value directly)
        const auto num_threads = parsed_and_validated_pre.get(num_threads_id);

        std::cout << "Log path   : " << log_path << std::endl;
        std::cout << "Num threads: " << num_threads << std::endl;
    } else {
        std::cout << parsed_and_validated_pre.warning_message();
        std::cout << parsed_and_validated_pre.error_message();
    }

    return EXIT_SUCCESS;
}
```

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

### Console Output Without Environment Variables

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Shows the error output when required environment variables are not set.

```console
$ ./libenvpp_simple_usage_example
Error  : Environment variable 'MYPROG_NUM_THREADS' not set
```

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

### Console Output With Typo in Environment Variable

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Illustrates the warning and error messages when an unrecognized environment variable is set, along with a missing required variable.

```console
$ MYPROG_LOG_FILEPATH=/var/log/file ./libenvpp_simple_usage_example
Warning: Unrecognized environment variable 'MYPROG_LOG_FILEPATH' set, did you mean 'MYPROG_LOG_FILE_PATH'?
Error  : Environment variable 'MYPROG_NUM_THREADS' not set
```

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

### Specialize env::default_parser for custom types

Source: https://context7.com/ph3at/libenvpp/llms.txt

Implement a custom parser by specializing env::default_parser<T>. Throw env::parser_error if parsing fails.

```cpp
#include <cstdlib>
#include <iostream>
#include <sstream>
#include <string>
#include <string_view>
#include <vector>

#include <libenvpp/env.hpp>

static std::vector<std::string> split(const std::string_view str, const char delimiter)
{
    auto result = std::vector<std::string>{};
    auto sstream = std::istringstream(std::string(str));
    auto item = std::string{};
    while (std::getline(sstream, item, delimiter)) {
        result.push_back(std::move(item));
    }
    return result;
}

struct server_config {
    std::string host;
    int port;
};

// Specialize default_parser for custom type
namespace env {
template <>
struct default_parser<server_config> {
    server_config operator()(const std::string_view str) const
    {
        const auto parts = split(str, ':');
        if (parts.size() != 2) {
            throw parser_error{"Expected format 'host:port'"};
        }

        server_config config;
        config.host = parts[0];
        // Delegate primitive parsing to built-in parser
        config.port = default_parser<int>{}(parts[1]);

        if (config.port <= 0 || config.port > 65535) {
            throw parser_error{"Port must be between 1 and 65535"};
        }

        return config;
    }
};
} // namespace env

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

    const auto config_id = pre.register_required_variable<server_config>("CONFIG");

    const auto parsed_and_validated_pre = pre.parse_and_validate();

    if (parsed_and_validated_pre.ok()) {
        const auto config = parsed_and_validated_pre.get(config_id);
        std::cout << "Host: " << config.host << std::endl;
        std::cout << "Port: " << config.port << std::endl;
    } else {
        std::cout << parsed_and_validated_pre.error_message();
    }

    return EXIT_SUCCESS;
}
```

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

### Test with Custom Environment Map

Source: https://context7.com/ph3at/libenvpp/llms.txt

Use a custom environment map with `parse_and_validate()` for complete isolation from system environment variables during testing. This allows for precise control over the environment your code interacts with.

```cpp
#include <cstdlib>
#include <iostream>
#include <unordered_map>

#include <libenvpp/env.hpp>

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

    const auto host_id = pre.register_required_variable<std::string>("HOST");
    const auto port_id = pre.register_required_variable<int>("PORT");

    // Custom environment - completely isolated from system
    std::unordered_map<std::string, std::string> test_environment = {
        {"APP_HOST", "localhost"},
        {"APP_PORT", "3000"},
    };

    // Parse using custom environment instead of system environment
    const auto parsed_pre = pre.parse_and_validate(test_environment);

    if (parsed_pre.ok()) {
        const auto host = parsed_pre.get(host_id);
        const auto port = parsed_pre.get(port_id);
        std::cout << "Connecting to " << host << ":" << port << std::endl;
    }

    return EXIT_SUCCESS;
}
// Output: Connecting to localhost:3000
```

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

### Global Testing Environment

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Utility for mocking environment variables during unit tests using a scoped environment.

```APIDOC
## Global Testing Environment

### Description
Allows temporary injection of key/value pairs into the environment. Variables are automatically removed when the `env::scoped_test_environment` object goes out of scope.

### Usage
```cpp
const auto _ = env::scoped_test_environment({
    {"MYPROG_LOG_FILE_PATH", "/dev/null"},
    {"MYPROG_NUM_THREADS", "8"},
});
```
```

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

### Specialize env::default_validator for custom validation

Source: https://context7.com/ph3at/libenvpp/llms.txt

Implement custom validation by specializing env::default_validator<T>. Throw env::validation_error on failure.

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

// Validate that paths must exist on the filesystem
namespace env {
template <>
struct default_validator<std::filesystem::path> {
    void operator()(const std::filesystem::path& path) const
    {
        if (!std::filesystem::exists(path)) {
            throw validation_error{path.string() + " path does not exist"};
        }
    }
};
} // namespace env

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

    // This path will be validated to exist
    const auto config_path_id = pre.register_variable<std::filesystem::path>("CONFIG_PATH");

    const auto parsed_and_validated_pre = pre.parse_and_validate();

    if (parsed_and_validated_pre.ok()) {
        auto path = parsed_and_validated_pre.get(config_path_id);
        if (path.has_value()) {
            std::cout << "Config path: " << *path << std::endl;
        } else {
            std::cout << "Using default config" << std::endl;
        }
    } else {
        std::cout << parsed_and_validated_pre.error_message();
    }

    return EXIT_SUCCESS;
}
```

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

### Register Option Variables with libenvpp

Source: https://context7.com/ph3at/libenvpp/llms.txt

Register variables that must match one of a predefined set of options. Supports both string-mapped options and parsed enum values. Use `register_option` for optional variables and `register_required_option` for mandatory ones.

```cpp
#include <cstdlib>
#include <iostream>
#include <string>
#include <string_view>

#include <libenvpp/env.hpp>

enum class log_level {
    debug,
    info,
    warning,
    error,
};

// Option with string mapping - no parser needed
enum class output_format {
    json,
    xml,
    text,
};

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

    // Option with explicit string-to-value mapping
    const auto format_id = pre.register_option<output_format>(
        "OUTPUT_FORMAT",
        {{"json", output_format::json}, {"xml", output_format::xml}, {"text", output_format::text}}
    );

    // Required option with string mapping
    const auto level_id = pre.register_required_option<log_level>(
        "LOG_LEVEL",
        {{"debug", log_level::debug}, {"info", log_level::info},
         {"warning", log_level::warning}, {"error", log_level::error}}
    );

    const auto parsed_and_validated_pre = pre.parse_and_validate();

    if (parsed_and_validated_pre.ok()) {
        const auto format = parsed_and_validated_pre.get_or(format_id, output_format::text);
        const auto level = parsed_and_validated_pre.get(level_id);

        std::cout << "Output format: " << static_cast<int>(format) << std::endl;
        std::cout << "Log level: " << static_cast<int>(level) << std::endl;
    } else {
        std::cout << parsed_and_validated_pre.warning_message();
        std::cout << parsed_and_validated_pre.error_message();
    }

    return EXIT_SUCCESS;
}

// $ APP_LOG_LEVEL=info ./example
// Output format: 2
// Log level: 1

// $ APP_OUTPUT_FORMAT=yaml APP_LOG_LEVEL=info ./example
// Error  : Option error for environment variable 'APP_OUTPUT_FORMAT': Unrecognized option 'yaml', should be one of [json, xml, text]
```

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

### Handle parsing and validation errors

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Check the status of the parsed environment and retrieve error or warning messages.

```cpp
if (!parsed_and_validated_pre.ok()) {
    std::cout << parsed_and_validated_pre.warning_message();
    std::cout << parsed_and_validated_pre.error_message();
}
```

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

### Parse Prefixless Environment Variables

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Parses environment variables directly without a namespace prefix. Supports required variables using `env::get` and optional variables with a default value using `env::get_or`.

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

int main()
{
    const auto log_path = env::get_or<std::filesystem::path>("LOG_FILE_PATH", "/default/log/path");
    const auto num_threads = env::get<unsigned int>("NUM_THREADS");

    if (num_threads.has_value()) {
        std::cout << "Log path   : " << log_path << std::endl;
        std::cout << "Num threads: " << num_threads.value() << std::endl;
    } else {
        std::cout << num_threads.error().what() << std::endl;
    }

    return EXIT_SUCCESS;
}
```

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

### Bypass Parsing with set_for_testing

Source: https://context7.com/ph3at/libenvpp/llms.txt

Use set_for_testing to manually inject values into a prefix, bypassing standard environment parsing and validation for unit testing.

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

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

    const auto log_path_id = pre.register_variable<std::filesystem::path>("LOG_FILE_PATH");
    const auto num_threads_id = pre.register_required_variable<unsigned int>("NUM_THREADS");

    // Directly set values - bypasses parsing and validation
    pre.set_for_testing(log_path_id, std::filesystem::path{"/test/log/path"});
    pre.set_for_testing(num_threads_id, 16u);

    const auto parsed_and_validated_pre = pre.parse_and_validate();

    // Values are already set, parsing is skipped for these variables
    const auto log_path = parsed_and_validated_pre.get_or(log_path_id, "/default");
    const auto num_threads = parsed_and_validated_pre.get(num_threads_id);

    std::cout << "Log path   : " << log_path << std::endl;  // /test/log/path
    std::cout << "Num threads: " << num_threads << std::endl;  // 16

    return EXIT_SUCCESS;
}
```

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

### Register Enum Option Variable

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Registers an environment variable with a predefined set of string options that map to an enum class. A fallback option can be provided for when the variable is not set.

```cpp
enum class option {
    first,
    second,
    fallback,
};

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

    const auto option_id =
        pre.register_option<option>("CHOICE", {{"first", option::first}, {"second", option::second}});

    const auto parsed_and_validated_pre = pre.parse_and_validate();

    if (parsed_and_validated_pre.ok()) {
        const auto opt = parsed_and_validated_pre.get_or(option_id, option::fallback);
    }
}
```

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

### Configure Edit Distance for Typo Detection

Source: https://context7.com/ph3at/libenvpp/llms.txt

Adjust typo detection sensitivity by passing an edit_distance option to the prefix constructor. Setting the distance to 0 disables suggestions.

```cpp
#include <cstdlib>
#include <iostream>

#include <libenvpp/env.hpp>

int main()
{
    // Default edit distance (varies by name length):
    // - length <= 3: 0 (no suggestions)
    // - length <= 6: 1
    // - length <= 9: 2
    // - length > 9: 3
    auto pre_default = env::prefix("APP");

    // Custom edit distance of 2 for all variables
    auto pre_custom = env::prefix("CONFIG", env::edit_distance(2));

    // Disable typo detection entirely
    auto pre_strict = env::prefix("STRICT", env::edit_distance(0));

    const auto host_id = pre_custom.register_required_variable<std::string>("HOST");

    const auto parsed_pre = pre_custom.parse_and_validate();

    if (!parsed_pre.ok()) {
        // With edit_distance(2), CONFIG_HSOT would suggest CONFIG_HOST
        std::cout << parsed_pre.warning_message();
        std::cout << parsed_pre.error_message();
    }

    return EXIT_SUCCESS;
}

// $ CONFIG_HSOT=localhost ./example
// Warning: Unrecognized environment variable 'CONFIG_HSOT' set, did you mean 'CONFIG_HOST'?
// Error  : Environment variable 'CONFIG_HOST' not set
```

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

### Scoped Test Environment in C++

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Use `env::scoped_test_environment` to temporarily set environment variables for testing. Variables are automatically removed when the instance goes out of scope. This environment takes precedence over system variables.

```cpp
const auto _ = env::scoped_test_environment({
    {"MYPROG_LOG_FILE_PATH", "/dev/null"},
    {"MYPROG_NUM_THREADS", "8"},
});
```

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

### Register Range Variable with libenvpp

Source: https://context7.com/ph3at/libenvpp/llms.txt

Register a variable with minimum and maximum constraints. Values outside the specified range will generate validation errors. The default value is not validated against the range.

```cpp
#include <cstdlib>
#include <iostream>
#include <thread>

#include <libenvpp/env.hpp>

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

    // Register a range variable: value must be between 1 and hardware_concurrency (inclusive)
    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()) {
        // Default value is NOT validated against range
        const auto num_threads = parsed_and_validated_pre.get_or(
            num_threads_id,
            std::thread::hardware_concurrency()
        );
        std::cout << "Number of threads: " << num_threads << std::endl;
    } else {
        std::cout << parsed_and_validated_pre.warning_message();
        std::cout << parsed_and_validated_pre.error_message();
    }

    return EXIT_SUCCESS;
}

// $ RANGE_NUM_THREADS=4 ./example
// Number of threads: 4

// $ RANGE_NUM_THREADS=0 ./example
// Error  : Range error for environment variable 'RANGE_NUM_THREADS': Value 0 outside of range [1, 8]

// $ RANGE_NUM_THREADS=100 ./example
// Error  : Range error for environment variable 'RANGE_NUM_THREADS': Value 100 outside of range [1, 8]
```

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

### Test with Scoped Test Environment

Source: https://context7.com/ph3at/libenvpp/llms.txt

Use `env::scoped_test_environment` to inject test values that override system environment variables for the duration of the scope. Values are automatically cleaned up when the scope ends.

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

int main()
{
    // Create scoped test environment - values removed when scope ends
    const auto test_env = env::scoped_test_environment({
        {"MYPROG_LOG_FILE_PATH", "/dev/null"},
        {"MYPROG_NUM_THREADS", "8"},
    });

    // Or for a single variable:
    // const auto test_env = env::scoped_test_environment("MYPROG_DEBUG", "true");

    auto pre = env::prefix("MYPROG");

    const auto log_path_id = pre.register_variable<std::filesystem::path>("LOG_FILE_PATH");
    const auto num_threads_id = pre.register_required_variable<unsigned int>("NUM_THREADS");

    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);

        // Values come from test environment, not system environment
        std::cout << "Log path   : " << log_path << std::endl;  // /dev/null
        std::cout << "Num threads: " << num_threads << std::endl;  // 8
    }

    return EXIT_SUCCESS;
}
// Test environment values take precedence over actual environment variables
```

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

### Set Variable for Testing in C++

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Bypasses parsing and validation to directly set a registered variable's value for testing purposes. This ensures the specified value is returned, ignoring any environment settings.

```cpp
auto pre = env::prefix("MYPROG");

const auto log_path_id = pre.register_variable<std::filesystem::path>("LOG_FILE_PATH");
const auto num_threads_id = pre.register_required_variable<unsigned int>("NUM_THREADS");

pre.set_for_testing(log_path_id, "/dev/null");
pre.set_for_testing(num_threads_id, 8);
```

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

### Error and Warning Reporting

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Functions to retrieve and inspect errors and warnings generated during prefix parsing and validation.

```APIDOC
## Error and Warning Reporting

### Description
Provides access to the state of parsing and validation, allowing users to check for errors or warnings and retrieve detailed messages.

### Methods
- **ok()**: Returns `bool` indicating if any errors or warnings exist.
- **warning_message()**: Returns `std::string` with all formatted warnings.
- **error_message()**: Returns `std::string` with all formatted errors.
- **warnings()**: Returns `std::vector<env::error>` containing all warnings.
- **errors()**: Returns `std::vector<env::error>` containing all errors.
```

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

### Register Deprecated Environment Variable

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Registers a deprecated environment variable to provide users with helpful messages when it's encountered. This includes specifying a version and suggesting an alternative.

```cpp
#include <libenvpp/env.hpp>

int main()
{
    auto pre = env::prefix("APP");
    pre.register_deprecated("FEATURE", "The option 'APP_FEATURE' has been deprecated since version x.y. Please use SOMETHING instead.");
}
```

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

### Custom Type Parser for program_data

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Defines a custom parser for a `program_data` struct, expecting comma-separated integer and float values. This enables parsing complex types from environment variables.

```cpp
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) {
            // Report an error if the input does not have the expected format
            throw parser_error{"Expected 2 comma delimited values"};
        }

        auto parsed_data = program_data{};

        // Delegate parsing of primitive types to the default_parser
        parsed_data.number = default_parser<int>{}(split_str[0]);
        parsed_data.percent = default_parser<float>{}(split_str[1]);

        return parsed_data;
    }
};
} // namespace env
```

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

### Custom Type Validator for std::filesystem::path

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Specializes `env::default_validator` to ensure that a `std::filesystem::path` environment variable points to an existing file or directory. This adds a filesystem-level validation step.

```cpp
namespace env {
template <>
struct default_validator<std::filesystem::path> {
    void operator()(const std::filesystem::path& path) const
    {
        if (!std::filesystem::exists(path)) {
            throw validation_error{path.string() + " path does not exist"};
        }
    }
};
} // namespace env
```

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

### env::error Type

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

The structure used to represent individual errors or warnings.

```APIDOC
## env::error Type

### Description
Represents an error or warning associated with a specific variable.

### Methods
- **get_id()**: Returns `std::size_t` ID of the variable that caused the issue.
- **get_name()**: Returns `std::string` containing the name of the variable.
- **what()**: Returns `std::string` containing the descriptive message.
```

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

### Implement Custom Variable Parser and Validator

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Define a custom callable to handle specific parsing and validation logic for a variable. This bypasses default parsers and validators for the registered variable.

```cpp
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;
}

int main()
{
    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);

    /*...*/
}
```

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

### Register Range-Validated Variables

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Use register_range to enforce inclusive minimum and maximum bounds on numeric environment variables. Range validation is applied after the default parsing process.

```cpp
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());
    std::cout << "Number of threads: " << num_threads << std::endl;
} else {
    std::cout << parsed_and_validated_pre.warning_message();
    std::cout << parsed_and_validated_pre.error_message();
}
```

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

### Custom Variable Parser and Validator in C++

Source: https://context7.com/ph3at/libenvpp/llms.txt

Register a custom parser and validator function for a specific environment variable to enforce unique constraints. This function is called during the parse and validate phase.

```cpp
#include <cstdlib>
#include <filesystem>
#include <iostream>

#include <libenvpp/env.hpp>

// Combined parser and validator function for a specific variable
std::filesystem::path log_directory_parser_and_validator(const std::string_view str)
{
    const auto log_path = std::filesystem::path(str);

    if (!std::filesystem::exists(log_path)) {
        // Try to create the directory
        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;
}

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

    // Register with custom parser/validator function
    const auto log_dir_id = pre.register_required_variable<std::filesystem::path>(
        "LOG_DIR",
        log_directory_parser_and_validator  // Can be function, lambda, or functor
    );

    const auto parsed_and_validated_pre = pre.parse_and_validate();

    if (parsed_and_validated_pre.ok()) {
        const auto log_dir = parsed_and_validated_pre.get(log_dir_id);
        std::cout << "Log directory: " << log_dir << std::endl;
    } else {
        std::cout << parsed_and_validated_pre.error_message();
    }

    return EXIT_SUCCESS;
}

// $ APP_LOG_DIR=/var/log/myapp ./example
// (creates directory if needed) Log directory: /var/log/myapp

// $ APP_LOG_DIR=/etc/passwd ./example
// Error  : Validation error for environment variable 'APP_LOG_DIR': Log path is not a directory
```

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

### Retrieve parsed variable values

Source: https://github.com/ph3at/libenvpp/blob/main/README.md

Access the successfully parsed values using the registered variable IDs.

```cpp
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);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.