std: Add a new `env` module

This is an implementation of [RFC 578][rfc] which adds a new `std::env` module
to replace most of the functionality in the current `std::os` module. More
details can be found in the RFC itself, but as a summary the following methods
have all been deprecated:

[rfc]: https://github.com/rust-lang/rfcs/pull/578

* `os::args_as_bytes`   => `env::args`
* `os::args`            => `env::args`
* `os::consts`          => `env::consts`
* `os::dll_filename`    => no replacement, use `env::consts` directly
* `os::page_size`       => `env::page_size`
* `os::make_absolute`   => use `env::current_dir` + `join` instead
* `os::getcwd`          => `env::current_dir`
* `os::change_dir`      => `env::set_current_dir`
* `os::homedir`         => `env::home_dir`
* `os::tmpdir`          => `env::temp_dir`
* `os::join_paths`      => `env::join_paths`
* `os::split_paths`     => `env::split_paths`
* `os::self_exe_name`   => `env::current_exe`
* `os::self_exe_path`   => use `env::current_exe` + `pop`
* `os::set_exit_status` => `env::set_exit_status`
* `os::get_exit_status` => `env::get_exit_status`
* `os::env`             => `env::vars`
* `os::env_as_bytes`    => `env::vars`
* `os::getenv`          => `env::var` or `env::var_string`
* `os::getenv_as_bytes` => `env::var`
* `os::setenv`          => `env::set_var`
* `os::unsetenv`        => `env::remove_var`

Many function signatures have also been tweaked for various purposes, but the
main changes were:

* `Vec`-returning APIs now all return iterators instead
* All APIs are now centered around `OsString` instead of `Vec<u8>` or `String`.
  There is currently on convenience API, `env::var_string`, which can be used to
  get the value of an environment variable as a unicode `String`.

All old APIs are `#[deprecated]` in-place and will remain for some time to allow
for migrations. The semantics of the APIs have been tweaked slightly with regard
to dealing with invalid unicode (panic instead of replacement).

The new `std::env` module is all contained within the `env` feature, so crates
must add the following to access the new APIs:

    #![feature(env)]

[breaking-change]

1 files changed, 106 insertions, 141 deletions

diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index 600ca60349a..27e843d2383 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -34,29 +34,32 @@ use self::MemoryMapKind::*;
 use self::MapOption::*;
 use self::MapError::*;
 
+use boxed::Box;
 use clone::Clone;
+use env;
 use error::{FromError, Error};
+use ffi::{OsString, OsStr};
 use fmt;
-use old_io::{IoResult, IoError};
 use iter::{Iterator, IteratorExt};
-use marker::{Copy, Send};
 use libc::{c_void, c_int, c_char};
 use libc;
-use boxed::Box;
+use marker::{Copy, Send};
+use old_io::{IoResult, IoError};
 use ops::{Drop, FnOnce};
-use option::Option;
 use option::Option::{Some, None};
+use option::Option;
 use path::{Path, GenericPath, BytesContainer};
-use sys;
-use sys::os as os_imp;
 use ptr::PtrExt;
 use ptr;
-use result::Result;
 use result::Result::{Err, Ok};
+use result::Result;
 use slice::{AsSlice, SliceExt};
 use str::{Str, StrExt};
+use str;
 use string::{String, ToString};
 use sync::atomic::{AtomicIsize, ATOMIC_ISIZE_INIT, Ordering};
+use sys::os as os_imp;
+use sys;
 use vec::Vec;
 
 #[cfg(unix)] use ffi::{self, CString};
@@ -97,23 +100,10 @@ pub const TMPBUF_SZ : uint = 1000u;
 /// let current_working_directory = os::getcwd().unwrap();
 /// println!("The current directory is {:?}", current_working_directory.display());
 /// ```
+#[deprecated(since = "1.0.0", reason = "renamed to std::env::current_dir")]
+#[unstable(feature = "os")]
 pub fn getcwd() -> IoResult<Path> {
-    sys::os::getcwd()
-}
-
-/*
-Accessing environment variables is not generally threadsafe.
-Serialize access through a global lock.
-*/
-fn with_env_lock<T, F>(f: F) -> T where
-    F: FnOnce() -> T,
-{
-    use sync::{StaticMutex, MUTEX_INIT};
-
-    static LOCK: StaticMutex = MUTEX_INIT;
-
-    let _guard = LOCK.lock();
-    f()
+    env::current_dir()
 }
 
 /// Returns a vector of (variable, value) pairs, for all the environment
@@ -132,37 +122,22 @@ fn with_env_lock<T, F>(f: F) -> T where
 ///     println!("'{}': '{}'", key, value );
 /// }
 /// ```
+#[deprecated(since = "1.0.0", reason = "use env::vars instead")]
+#[unstable(feature = "os")]
 pub fn env() -> Vec<(String,String)> {
-    env_as_bytes().into_iter().map(|(k,v)| {
-        let k = String::from_utf8_lossy(k.as_slice()).into_owned();
-        let v = String::from_utf8_lossy(v.as_slice()).into_owned();
-        (k,v)
+    env::vars().map(|(k, v)| {
+        (k.to_string_lossy().into_owned(), v.to_string_lossy().into_owned())
     }).collect()
 }
 
 /// Returns a vector of (variable, value) byte-vector pairs for all the
 /// environment variables of the current process.
-pub fn env_as_bytes() -> Vec<(Vec<u8>,Vec<u8>)> {
-    unsafe {
-        fn env_convert(input: Vec<Vec<u8>>) -> Vec<(Vec<u8>, Vec<u8>)> {
-            let mut pairs = Vec::new();
-            for p in input.iter() {
-                let mut it = p.splitn(1, |b| *b == b'=');
-                let key = it.next().unwrap().to_vec();
-                let default: &[u8] = &[];
-                let val = it.next().unwrap_or(default).to_vec();
-                pairs.push((key, val));
-            }
-            pairs
-        }
-        with_env_lock(|| {
-            let unparsed_environ = sys::os::get_env_pairs();
-            env_convert(unparsed_environ)
-        })
-    }
+#[deprecated(since = "1.0.0", reason = "use env::vars instead")]
+#[unstable(feature = "os")]
+pub fn env_as_bytes() -> Vec<(Vec<u8>, Vec<u8>)> {
+    env::vars().map(|(k, v)| (byteify(k), byteify(v))).collect()
 }
 
-#[cfg(unix)]
 /// Fetches the environment variable `n` from the current process, returning
 /// None if the variable isn't set.
 ///
@@ -184,52 +159,32 @@ pub fn env_as_bytes() -> Vec<(Vec<u8>,Vec<u8>)> {
 ///     None => println!("{} is not defined in the environment.", key)
 /// }
 /// ```
+#[deprecated(since = "1.0.0", reason = "use env::var or env::var_string instead")]
+#[unstable(feature = "os")]
 pub fn getenv(n: &str) -> Option<String> {
-    getenv_as_bytes(n).map(|v| String::from_utf8_lossy(v.as_slice()).into_owned())
+    env::var_string(n).ok()
 }
 
-#[cfg(unix)]
 /// Fetches the environment variable `n` byte vector from the current process,
 /// returning None if the variable isn't set.
 ///
 /// # Panics
 ///
 /// Panics if `n` has any interior NULs.
+#[deprecated(since = "1.0.0", reason = "use env::var instead")]
+#[unstable(feature = "os")]
 pub fn getenv_as_bytes(n: &str) -> Option<Vec<u8>> {
-    unsafe {
-        with_env_lock(|| {
-            let s = CString::from_slice(n.as_bytes());
-            let s = libc::getenv(s.as_ptr()) as *const _;
-            if s.is_null() {
-                None
-            } else {
-                Some(ffi::c_str_to_bytes(&s).to_vec())
-            }
-        })
-    }
+    env::var(n).map(byteify)
 }
 
-#[cfg(windows)]
-/// Fetches the environment variable `n` from the current process, returning
-/// None if the variable isn't set.
-pub fn getenv(n: &str) -> Option<String> {
-    unsafe {
-        with_env_lock(|| {
-            use sys::os::fill_utf16_buf_and_decode;
-            let mut n: Vec<u16> = n.utf16_units().collect();
-            n.push(0);
-            fill_utf16_buf_and_decode(|buf, sz| {
-                libc::GetEnvironmentVariableW(n.as_ptr(), buf, sz)
-            })
-        })
-    }
+#[cfg(unix)]
+fn byteify(s: OsString) -> Vec<u8> {
+    use os::unix::*;
+    s.into_vec()
 }
-
 #[cfg(windows)]
-/// Fetches the environment variable `n` byte vector from the current process,
-/// returning None if the variable isn't set.
-pub fn getenv_as_bytes(n: &str) -> Option<Vec<u8>> {
-    getenv(n).map(|s| s.into_bytes())
+fn byteify(s: OsString) -> Vec<u8> {
+    s.to_string_lossy().as_bytes().to_vec()
 }
 
 /// Sets the environment variable `n` to the value `v` for the currently running
@@ -247,68 +202,30 @@ pub fn getenv_as_bytes(n: &str) -> Option<Vec<u8>> {
 ///     None => println!("{} is not defined in the environment.", key)
 /// }
 /// ```
+#[deprecated(since = "1.0.0", reason = "renamed to env::set_var")]
+#[unstable(feature = "os")]
 pub fn setenv<T: BytesContainer>(n: &str, v: T) {
     #[cfg(unix)]
     fn _setenv(n: &str, v: &[u8]) {
-        unsafe {
-            with_env_lock(|| {
-                let k = CString::from_slice(n.as_bytes());
-                let v = CString::from_slice(v);
-                if libc::funcs::posix01::unistd::setenv(k.as_ptr(),
-                                                        v.as_ptr(), 1) != 0 {
-                    panic!(IoError::last_error());
-                }
-            })
-        }
+        use os::unix::*;
+        let v: OsString = OsStringExt::from_vec(v.to_vec());
+        env::set_var(n, &v)
     }
 
     #[cfg(windows)]
     fn _setenv(n: &str, v: &[u8]) {
-        let mut n: Vec<u16> = n.utf16_units().collect();
-        n.push(0);
-        let mut v: Vec<u16> = ::str::from_utf8(v).unwrap().utf16_units().collect();
-        v.push(0);
-
-        unsafe {
-            with_env_lock(|| {
-                if libc::SetEnvironmentVariableW(n.as_ptr(), v.as_ptr()) == 0 {
-                    panic!(IoError::last_error());
-                }
-            })
-        }
+        let v = str::from_utf8(v).unwrap();
+        env::set_var(n, v)
     }
 
     _setenv(n, v.container_as_bytes())
 }
 
 /// Remove a variable from the environment entirely.
+#[deprecated(since = "1.0.0", reason = "renamed to env::remove_var")]
+#[unstable(feature = "os")]
 pub fn unsetenv(n: &str) {
-    #[cfg(unix)]
-    fn _unsetenv(n: &str) {
-        unsafe {
-            with_env_lock(|| {
-                let nbuf = CString::from_slice(n.as_bytes());
-                if libc::funcs::posix01::unistd::unsetenv(nbuf.as_ptr()) != 0 {
-                    panic!(IoError::last_error());
-                }
-            })
-        }
-    }
-
-    #[cfg(windows)]
-    fn _unsetenv(n: &str) {
-        let mut n: Vec<u16> = n.utf16_units().collect();
-        n.push(0);
-        unsafe {
-            with_env_lock(|| {
-                if libc::SetEnvironmentVariableW(n.as_ptr(), ptr::null()) == 0 {
-                    panic!(IoError::last_error());
-                }
-            })
-        }
-    }
-
-    _unsetenv(n)
+    env::remove_var(n)
 }
 
 /// Parses input according to platform conventions for the `PATH`
@@ -328,8 +245,12 @@ pub fn unsetenv(n: &str) {
 ///     None => println!("{} is not defined in the environment.", key)
 /// }
 /// ```
+#[deprecated(since = "1.0.0", reason = "renamed to env::split_paths")]
+#[unstable(feature = "os")]
 pub fn split_paths<T: BytesContainer>(unparsed: T) -> Vec<Path> {
-    sys::os::split_paths(unparsed.container_as_bytes())
+    let b = unparsed.container_as_bytes();
+    let s = str::from_utf8(b).unwrap();
+    env::split_paths(s).collect()
 }
 
 /// Joins a collection of `Path`s appropriately for the `PATH`
@@ -353,8 +274,14 @@ pub fn split_paths<T: BytesContainer>(unparsed: T) -> Vec<Path> {
 /// paths.push(Path::new("/home/xyz/bin"));
 /// os::setenv(key, os::join_paths(paths.as_slice()).unwrap());
 /// ```
+#[deprecated(since = "1.0.0", reason = "renamed to env::join_paths")]
+#[unstable(feature = "os")]
 pub fn join_paths<T: BytesContainer>(paths: &[T]) -> Result<Vec<u8>, &'static str> {
-    sys::os::join_paths(paths)
+    env::join_paths(paths.iter().map(|s| {
+        str::from_utf8(s.container_as_bytes()).unwrap()
+    })).map(|s| {
+        s.to_string_lossy().into_owned().into_bytes()
+    }).map_err(|_| "failed to join paths")
 }
 
 /// A low-level OS in-memory pipe.
@@ -388,6 +315,8 @@ pub unsafe fn pipe() -> IoResult<Pipe> {
 /// Returns the proper dll filename for the given basename of a file
 /// as a String.
 #[cfg(not(target_os="ios"))]
+#[deprecated(since = "1.0.0", reason = "this function will be removed, use the constants directly")]
+#[unstable(feature = "os")]
 pub fn dll_filename(base: &str) -> String {
     format!("{}{}{}", consts::DLL_PREFIX, base, consts::DLL_SUFFIX)
 }
@@ -405,8 +334,10 @@ pub fn dll_filename(base: &str) -> String {
 ///     None => println!("Unable to get the path of this executable!")
 /// };
 /// ```
+#[deprecated(since = "1.0.0", reason = "renamed to env::current_exe")]
+#[unstable(feature = "os")]
 pub fn self_exe_name() -> Option<Path> {
-    sys::os::load_self().and_then(Path::new_opt)
+    env::current_exe().ok()
 }
 
 /// Optionally returns the filesystem path to the current executable which is
@@ -424,8 +355,10 @@ pub fn self_exe_name() -> Option<Path> {
 ///     None => println!("Impossible to fetch the path of this executable.")
 /// };
 /// ```
+#[deprecated(since = "1.0.0", reason = "use env::current_exe + dir_path/pop")]
+#[unstable(feature = "os")]
 pub fn self_exe_path() -> Option<Path> {
-    self_exe_name().map(|mut p| { p.pop(); p })
+    env::current_exe().ok().map(|mut p| { p.pop(); p })
 }
 
 /// Optionally returns the path to the current user's home directory if known.
@@ -452,6 +385,9 @@ pub fn self_exe_path() -> Option<Path> {
 ///     None => println!("Impossible to get your home dir!")
 /// }
 /// ```
+#[deprecated(since = "1.0.0", reason = "renamed to env::home_dir")]
+#[allow(deprecated)]
+#[unstable(feature = "os")]
 pub fn homedir() -> Option<Path> {
     #[inline]
     #[cfg(unix)]
@@ -487,6 +423,9 @@ pub fn homedir() -> Option<Path> {
 /// On Windows, returns the value of, in order, the 'TMP', 'TEMP',
 /// 'USERPROFILE' environment variable  if any are set and not the empty
 /// string. Otherwise, tmpdir returns the path to the Windows directory.
+#[deprecated(since = "1.0.0", reason = "renamed to env::temp_dir")]
+#[allow(deprecated)]
+#[unstable(feature = "os")]
 pub fn tmpdir() -> Path {
     return lookup();
 
@@ -542,11 +481,13 @@ pub fn tmpdir() -> Path {
 // NB: this is here rather than in path because it is a form of environment
 // querying; what it does depends on the process working directory, not just
 // the input paths.
+#[deprecated(since = "1.0.0", reason = "use env::current_dir + .join directly")]
+#[unstable(feature = "os")]
 pub fn make_absolute(p: &Path) -> IoResult<Path> {
     if p.is_absolute() {
         Ok(p.clone())
     } else {
-        getcwd().map(|mut cwd| {
+        env::current_dir().map(|mut cwd| {
             cwd.push(p);
             cwd
         })
@@ -565,6 +506,8 @@ pub fn make_absolute(p: &Path) -> IoResult<Path> {
 /// assert!(os::change_dir(&root).is_ok());
 /// println!("Successfully changed working directory to {}!", root.display());
 /// ```
+#[deprecated(since = "1.0.0", reason = "renamed to env::set_current_dir")]
+#[unstable(feature = "os")]
 pub fn change_dir(p: &Path) -> IoResult<()> {
     return sys::os::chdir(p);
 }
@@ -592,8 +535,6 @@ pub fn last_os_error() -> String {
     error_string(errno() as uint)
 }
 
-static EXIT_STATUS: AtomicIsize = ATOMIC_ISIZE_INIT;
-
 /// Sets the process exit code
 ///
 /// Sets the exit code returned by the process if all supervised tasks
@@ -602,14 +543,18 @@ static EXIT_STATUS: AtomicIsize = ATOMIC_ISIZE_INIT;
 /// ignored and the process exits with the default panic status.
 ///
 /// Note that this is not synchronized against modifications of other threads.
+#[deprecated(since = "1.0.0", reason = "renamed to env::set_exit_status")]
+#[unstable(feature = "os")]
 pub fn set_exit_status(code: int) {
-    EXIT_STATUS.store(code, Ordering::SeqCst)
+    env::set_exit_status(code as i32)
 }
 
 /// Fetches the process's current exit code. This defaults to 0 and can change
 /// by calling `set_exit_status`.
+#[deprecated(since = "1.0.0", reason = "renamed to env::get_exit_status")]
+#[unstable(feature = "os")]
 pub fn get_exit_status() -> int {
-    EXIT_STATUS.load(Ordering::SeqCst)
+    env::get_exit_status() as isize
 }
 
 #[cfg(target_os = "macos")]
@@ -726,7 +671,7 @@ fn real_args() -> Vec<String> {
         // Push it onto the list.
         let ptr = ptr as *const u16;
         let buf = slice::from_raw_buf(&ptr, len);
-        let opt_s = String::from_utf16(sys::os::truncate_utf16_at_nul(buf));
+        let opt_s = String::from_utf16(sys::truncate_utf16_at_nul(buf));
         opt_s.ok().expect("CommandLineToArgvW returned invalid UTF-16")
     }).collect();
 
@@ -777,12 +722,16 @@ extern "system" {
 ///     println!("{}", argument);
 /// }
 /// ```
+#[deprecated(since = "1.0.0", reason = "use env::args instead")]
+#[unstable(feature = "os")]
 pub fn args() -> Vec<String> {
     real_args()
 }
 
 /// Returns the arguments which this program was started with (normally passed
 /// via the command line) as byte vectors.
+#[deprecated(since = "1.0.0", reason = "use env::args_raw instead")]
+#[unstable(feature = "os")]
 pub fn args_as_bytes() -> Vec<Vec<u8>> {
     real_args_as_bytes()
 }
@@ -790,11 +739,13 @@ pub fn args_as_bytes() -> Vec<Vec<u8>> {
 #[cfg(target_os = "macos")]
 extern {
     // These functions are in crt_externs.h.
-    pub fn _NSGetArgc() -> *mut c_int;
-    pub fn _NSGetArgv() -> *mut *mut *mut c_char;
+    fn _NSGetArgc() -> *mut c_int;
+    fn _NSGetArgv() -> *mut *mut *mut c_char;
 }
 
 /// Returns the page size of the current architecture in bytes.
+#[deprecated(since = "1.0.0", reason = "renamed to env::page_size")]
+#[unstable(feature = "os")]
 pub fn page_size() -> uint {
     sys::os::page_size()
 }
@@ -970,7 +921,7 @@ impl MemoryMap {
         let mut fd = -1;
         let mut offset = 0;
         let mut custom_flags = false;
-        let len = round_up(min_len, page_size());
+        let len = round_up(min_len, env::page_size());
 
         for &o in options.iter() {
             match o {
@@ -1020,7 +971,7 @@ impl MemoryMap {
     /// Granularity that the offset or address must be for `MapOffset` and
     /// `MapAddr` respectively.
     pub fn granularity() -> uint {
-        page_size()
+        env::page_size()
     }
 }
 
@@ -1049,7 +1000,7 @@ impl MemoryMap {
         let mut executable = false;
         let mut handle: HANDLE = libc::INVALID_HANDLE_VALUE;
         let mut offset: uint = 0;
-        let len = round_up(min_len, page_size());
+        let len = round_up(min_len, env::page_size());
 
         for &o in options.iter() {
             match o {
@@ -1184,6 +1135,8 @@ impl MemoryMap {
 }
 
 #[cfg(target_os = "linux")]
+#[deprecated(since = "1.0.0", reason = "renamed to env::consts")]
+#[unstable(feature = "os")]
 pub mod consts {
     pub use os::arch_consts::ARCH;
 
@@ -1215,6 +1168,8 @@ pub mod consts {
 }
 
 #[cfg(target_os = "macos")]
+#[deprecated(since = "1.0.0", reason = "renamed to env::consts")]
+#[unstable(feature = "os")]
 pub mod consts {
     pub use os::arch_consts::ARCH;
 
@@ -1246,6 +1201,8 @@ pub mod consts {
 }
 
 #[cfg(target_os = "ios")]
+#[deprecated(since = "1.0.0", reason = "renamed to env::consts")]
+#[unstable(feature = "os")]
 pub mod consts {
     pub use os::arch_consts::ARCH;
 
@@ -1265,6 +1222,8 @@ pub mod consts {
 }
 
 #[cfg(target_os = "freebsd")]
+#[deprecated(since = "1.0.0", reason = "renamed to env::consts")]
+#[unstable(feature = "os")]
 pub mod consts {
     pub use os::arch_consts::ARCH;
 
@@ -1296,6 +1255,8 @@ pub mod consts {
 }
 
 #[cfg(target_os = "dragonfly")]
+#[deprecated(since = "1.0.0", reason = "renamed to env::consts")]
+#[unstable(feature = "os")]
 pub mod consts {
     pub use os::arch_consts::ARCH;
 
@@ -1327,6 +1288,8 @@ pub mod consts {
 }
 
 #[cfg(target_os = "android")]
+#[deprecated(since = "1.0.0", reason = "renamed to env::consts")]
+#[unstable(feature = "os")]
 pub mod consts {
     pub use os::arch_consts::ARCH;
 
@@ -1358,6 +1321,8 @@ pub mod consts {
 }
 
 #[cfg(target_os = "windows")]
+#[deprecated(since = "1.0.0", reason = "renamed to env::consts")]
+#[unstable(feature = "os")]
 pub mod consts {
     pub use os::arch_consts::ARCH;