environment: Add change-os-env, docs, example, etc.

basis/environment/environment-docs.factor

@@ -29,6 +29,21 @@ HELP: os-env
     }
 } ;
 
+HELP: change-os-env
+{ $values { "key" string } { "quot" { $quotation "( old -- new )" } } }
+{ $description "Applies a quotation to change the value stored in an environment variable." }
+{ $examples
+    "This is an operating system-specific feature. On Unix, you can do:"
+    { $unchecked-example
+        "USING: environment io ;"
+        "\"USER\" os-env print"
+        "\"USER\" [ \"-doe\" append ] change-os-env"
+        "\"USER\" os-env print"
+        "jane\njane-doe"
+    }
+}
+{ $side-effects "key" } ;
+
 HELP: os-envs
 { $values { "assoc" "an association mapping strings to strings" } }
 { $description "Outputs the current set of environment variables." }
@@ -57,7 +72,7 @@ HELP: unset-os-env
     "Names and values of environment variables are operating system-specific."
 } ;
 
-{ os-env os-envs set-os-env unset-os-env set-os-envs } related-words
+{ os-env os-envs set-os-env unset-os-env set-os-envs change-os-env } related-words
 
 
 ARTICLE: "environment" "Environment variables"
@@ -72,6 +87,7 @@ ARTICLE: "environment" "Environment variables"
     set-os-env
     unset-os-env
     set-os-envs
+    change-os-env
 } ;
 
 ABOUT: "environment"

basis/environment/environment-tests.factor

@@ -25,3 +25,10 @@ os unix? [
 ] unit-test
 [ 32766 ] [ "factor-test-key-long" os-env length ] unit-test
 [ ] [ "factor-test-key-long" unset-os-env ] unit-test
+
+[ "abc" ] [
+    "a" "factor-test-key-change" set-os-env
+    "factor-test-key-change" [ "bc" append ] change-os-env
+    "factor-test-key-change" os-env
+] unit-test
+[ ] [ "factor-test-key-change" unset-os-env ] unit-test

basis/environment/environment.factor

@@ -14,6 +14,9 @@ HOOK: (os-envs) os ( -- seq )
 
 HOOK: (set-os-envs) os ( seq -- )
 
+: change-os-env ( key quot -- )
+    [ [ os-env ] keep ] dip dip set-os-env ; inline
+
 : os-envs ( -- assoc )
     (os-envs) [ "=" split1 ] H{ } map>assoc ;