/
environment-docs.factor
110 lines (94 loc) · 3.75 KB
/
environment-docs.factor
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
! Copyright (C) 2008 Doug Coleman.
! See https://factorcode.org/license.txt for BSD license.
USING: assocs help.markup help.syntax io.streams.string
libc sequences strings ;
IN: environment
HELP: (os-envs)
{ $values
{ "seq" sequence } }
{ $description "Returns a sequence of key/value pairs from the operating system." }
{ $notes "In most cases, use " { $link os-envs } " instead." } ;
HELP: (set-os-envs)
{ $values
{ "seq" sequence } }
{ $description "Low-level word for replacing the current set of environment variables." }
{ $notes "In most cases, use " { $link set-os-envs } " instead." } ;
HELP: os-env
{ $values { "key" string } { "value" string } }
{ $description "Looks up the value of a shell environment variable." }
{ $examples
"This is an operating system-specific feature. On Unix, you can do:"
{ $unchecked-example
"USING: environment io ;"
"\"USER\" os-env print"
"jane"
}
} ;
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." }
{ $notes
"Names and values of environment variables are operating system-specific."
} ;
HELP: set-os-envs
{ $values { "assoc" "an association mapping strings to strings" } }
{ $description "Replaces the current set of environment variables." }
{ $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." }
{ $notes
"Names and values of environment variables are operating system-specific. Windows NT allows values up to 32766 characters in length."
} ;
HELP: set-os-envs-pointer
{ $values { "malloc" "a pointer to memory from the heap obtained through " { $link malloc } " or similar" } }
{ $description "Set then " { $snippet "environ" } " pointer. Factor must retain a pointer to this memory until exiting the program." }
{ $notes
"Names and values of environment variables are operating system-specific."
} ;
HELP: set-os-env
{ $values { "value" string } { "key" string } }
{ $description "Set an environment variable." }
{ $notes
"Names and values of environment variables are operating system-specific."
} ;
HELP: unset-os-env
{ $values { "key" string } }
{ $description "Unset an environment variable." }
{ $notes
"Names and values of environment variables are operating system-specific."
} ;
HELP: with-os-env
{ $values { "value" string } { "key" string } { "quot" "quotation" } }
{ $description "Calls a quotation with the " { $snippet "key" } " environment variable set to " { $snippet "value" } ", resetting the environment variable afterwards to its previous value." } ;
{ 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
ARTICLE: "environment" "Environment variables"
"The " { $vocab-link "environment" } " vocabulary interfaces to the platform-dependent mechanism for setting environment variables." $nl
"Reading environment variables:"
{ $subsections
os-env
os-envs
}
"Writing environment variables:"
{ $subsections
set-os-env
unset-os-env
set-os-envs
change-os-env
}
"Leak-free setting of all environment variables on Unix:"
{ $subsections
set-os-envs-pointer
} ;
ABOUT: "environment"