ADDED: library(os), reasoning about environment variables.

Together with library(files), this addresses #511.

src/lib/error.pl

@@ -44,6 +44,7 @@ must_be_(var, Term) :-
         ).
 must_be_(integer, Term) :- check_(integer, integer, Term).
 must_be_(atom, Term)    :- check_(atom, atom, Term).
+must_be_(character, T)  :- check_(character, character, T).
 must_be_(list, Term)    :- check_(ilist, list, Term).
 must_be_(type, Term)    :- check_(type, type, Term).
 must_be_(boolean, Term) :- check_(boolean, boolean, Term).
@@ -56,6 +57,10 @@ check_(Pred, Type, Term) :-
 
 boolean(B) :- ( B == true ; B == false ).
 
+character(C) :-
+        atom(C),
+        atom_length(C, 1).
+
 ilist(V) :- var(V), instantiation_error(must_be/2).
 ilist([]).
 ilist([_|Ls]) :- ilist(Ls).
@@ -63,6 +68,7 @@ ilist([_|Ls]) :- ilist(Ls).
 type(type).
 type(integer).
 type(atom).
+type(character).
 type(list).
 type(var).
 type(boolean).
@@ -90,6 +96,7 @@ can_be(Type, Term) :-
 
 can_(integer, Term) :- integer(Term).
 can_(atom, Term)    :- atom(Term).
+can_(character, T)  :- character(T).
 can_(list, Term)    :- list_or_partial_list(Term).
 can_(boolean, Term) :- boolean(Term).
 

src/lib/os.pl

@@ -0,0 +1,58 @@
+/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+   Predicates for reasoning about the operating system (OS) environment.
+   Written July 2020 by Markus Triska (triska@metalevel.at).
+
+   Lists of characters are used throughout to represent keys and values.
+
+   Example:
+
+       ?- getenv("LANG", Ls).
+          Ls = "en_US.UTF-8"
+       ;  false.
+
+   Public domain code.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+
+:- module(os, [getenv/2,
+               setenv/2,
+               unsetenv/1]).
+
+:- use_module(library(error)).
+:- use_module(library(charsio)).
+:- use_module(library(lists)).
+
+getenv(Key, Value) :-
+        must_be_env_var(Key),
+        '$getenv'(Key, Value).
+
+setenv(Key, Value) :-
+        must_be_env_var(Key),
+        must_be_chars(Value),
+        '$setenv'(Key, Value).
+
+unsetenv(Key) :-
+        must_be_env_var(Key),
+        '$unsetenv'(Key).
+
+/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+   For now, we only support a restricted subset of variable names.
+
+   The reason is that Rust may panic if a key is empty, contains an
+   ASCII equals sign '=' or the NUL character '\0', or when the value
+   contains the NUL character.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+
+must_be_env_var(Cs) :-
+        must_be_chars(Cs),
+        Cs = [_|_],
+        (   maplist(permitted, Cs) -> true
+        ;   domain_error(env_var, Cs, os)
+        ).
+
+permitted(C) :- char_type(C, alnum).
+permitted(C) :- char_type(C, ascii_punctuation).
+permitted('_').
+
+must_be_chars(Cs) :-
+        must_be(list, Cs),
+        maplist(must_be(character), Cs).