From c72650df3017a5000970f3b8bc89465140e8a8ce Mon Sep 17 00:00:00 2001
From: Klemens Morgenstern <klemens.morgenstern@gmx.net>
Date: Thu, 26 Jun 2025 22:48:16 +0800
Subject: [PATCH] added example for modifying inherited environment.

---
 doc/env.adoc    | 21 +++++++++++++++++++++
 example/env.cpp | 26 ++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/doc/env.adoc b/doc/env.adoc
index 8421c9fb..3dca9054 100644
--- a/doc/env.adoc
+++ b/doc/env.adoc
@@ -29,3 +29,24 @@ The subprocess environment assignment follows the same constraints:
 ----
 include::../example/env.cpp[tag=subprocess_env]
 ----
+
+== Inheriting an environment
+
+The current environment can be obtained by calling `environment::current` which returns
+a forward range of `environment::key_value_pair_view`.
+
+.example/env.cpp:48-54
+[source,cpp,ident=0]
+----
+include::../example/env.cpp[tag=vector_env]
+----
+
+Alternatively you can use a map container for the environment.
+
+.example/env.cpp:61-68
+[source,cpp,ident=0]
+----
+include::../example/env.cpp[tag=map_env]
+----
+
+
diff --git a/example/env.cpp b/example/env.cpp
index d12cf990..d0974efb 100644
--- a/example/env.cpp
+++ b/example/env.cpp
@@ -42,4 +42,30 @@ int main()
     process pro2(ctx, exe, {"test.cpp"}, process_environment(my_env));
     // end::subprocess_env[]
   }
+
+  {
+    // tag::vector_env[]
+    asio::io_context ctx;
+    auto c = environment::current();
+    // a view is fine since the value is our value is static.
+    std::vector<environment::key_value_pair_view> my_env{c.begin(), c.end()};
+    my_env.push_back("SECRET=THIS_IS_A_TEST");
+    auto exe = environment::find_executable("g++", my_env);
+    process proc(ctx, exe, {"main.cpp"}, process_environment(my_env));
+    // end::vector_env[]
+
+  }
+
+  {
+    // tag::map_env[]
+    asio::io_context ctx;
+    std::unordered_map<environment::key, environment::value> my_env;
+    for (const auto & kv : environment::current())
+      if (kv.key() != "SECRET")
+        my_env[kv.key()] = kv.value();
+
+    auto exe = environment::find_executable("g++", my_env);
+    process proc(ctx, exe, {"main.cpp"}, process_environment(my_env));
+    // end::map_env[]
+  }
 }