1 ! Copyright (C) 2008 Doug Coleman.
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: assocs help.markup help.syntax io.streams.string
4 libc sequences strings ;
11 { $description "Returns a sequence of key/value pairs from the operating system." }
12 { $notes "In most cases, use " { $link os-envs } " instead." } ;
17 { $description "Low-level word for replacing the current set of environment variables." }
18 { $notes "In most cases, use " { $link set-os-envs } " instead." } ;
22 { $values { "key" string } { "value" string } }
23 { $description "Looks up the value of a shell environment variable." }
25 "This is an operating system-specific feature. On Unix, you can do:"
27 "USING: environment io ;"
28 "\"USER\" os-env print"
34 { $values { "key" string } { "quot" { $quotation ( old -- new ) } } }
35 { $description "Applies a quotation to change the value stored in an environment variable." }
37 "This is an operating system-specific feature. On Unix, you can do:"
39 "USING: environment io ;"
40 "\"USER\" os-env print"
41 "\"USER\" [ \"-doe\" append ] change-os-env"
42 "\"USER\" os-env print"
46 { $side-effects "key" } ;
49 { $values { "assoc" "an association mapping strings to strings" } }
50 { $description "Outputs the current set of environment variables." }
52 "Names and values of environment variables are operating system-specific."
56 { $values { "assoc" "an association mapping strings to strings" } }
57 { $description "Replaces the current set of environment variables." }
58 { $warning "Leaks memory on Unix. If your program calls this function repeatedly, call " { $link set-os-envs-pointer } " with a malloced pointer and manage your memory instead." }
60 "Names and values of environment variables are operating system-specific. Windows NT allows values up to 32766 characters in length."
63 HELP: set-os-envs-pointer
64 { $values { "malloc" "a pointer to memory from the heap obtained through " { $link malloc } " or similar" } }
65 { $description "Set then " { $snippet "environ" } " pointer. Factor must retain a pointer to this memory until exiting the program." }
67 "Names and values of environment variables are operating system-specific."
71 { $values { "value" string } { "key" string } }
72 { $description "Set an environment variable." }
74 "Names and values of environment variables are operating system-specific."
78 { $values { "key" string } }
79 { $description "Unset an environment variable." }
81 "Names and values of environment variables are operating system-specific."
85 { $values { "value" string } { "key" string } { "quot" "quotation" } }
86 { $description "Calls a quotation with the " { $snippet "key" } " environment variable set to " { $snippet "value" } ", resetting the environment variable afterwards to its previous value." } ;
88 { os-env os-envs set-os-env unset-os-env set-os-envs set-os-envs-pointer change-os-env with-os-env } related-words
91 ARTICLE: "environment" "Environment variables"
92 "The " { $vocab-link "environment" } " vocabulary interfaces to the platform-dependent mechanism for setting environment variables." $nl
93 "Reading environment variables:"
98 "Writing environment variables:"
105 "Leak-free setting of all environment variables on Unix:"