added example for modifying inherited environment.

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]
+----
+
+

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[]
+  }
 }