rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

std: Tweak the std::env OsString/String interface

Browse Source 
This commit tweaks the interface of the `std::env` module to make it more
ergonomic for common usage:

* `env::var` was renamed to `env::var_os`
* `env::var_string` was renamed to `env::var`
* `env::args` was renamed to `env::args_os`
* `env::args` was re-added as a panicking iterator over string values
* `env::vars` was renamed to `env::vars_os`
* `env::vars` was re-added as a panicking iterator over string values.

This should make common usage (e.g. unicode values everywhere) more ergonomic
as well as "the default". This is also a breaking change due to the differences
of what's yielded from each of these functions, but migration should be fairly
easy as the defaults operate over `String` which is a common type to use.

[breaking-change]
This commit is contained in:
Alex Crichton
2015-02-11 11:47:53 -08:00
parent 446bc899b2
commit a828e79480
21 changed files with 169 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
src/libstd/env.rs
View File

@@ -71,12 +71,46 @@ static ENV_LOCK: StaticMutex = MUTEX_INIT;
/// An iterator over a snapshot of the environment variables of this process.
///
/// This iterator is created through `std::env::vars()` and yields `(OsString,
/// OsString)` pairs.
pub struct Vars { inner: os_imp::Env }
/// This iterator is created through `std::env::vars()` and yields `(String,
/// String)` pairs.
pub struct Vars { inner: VarsOs }
/// Returns an iterator of (variable, value) pairs, for all the environment
/// variables of the current process.
/// An iterator over a snapshot of the environment variables of this process.
///
/// This iterator is created through `std::env::vars_os()` and yields
/// `(OsString, OsString)` pairs.
pub struct VarsOs { inner: os_imp::Env }
/// Returns an iterator of (variable, value) pairs of strings, for all the
/// environment variables of the current process.
///
/// The returned iterator contains a snapshot of the process's environment
/// variables at the time of this invocation, modifications to environment
/// variables afterwards will not be reflected in the returned iterator.
///
/// # Panics
///
/// While iterating, the returned iterator will panic if any key or value in the
/// environment is not valid unicode. If this is not desired, consider using the
/// `env::vars_os` function.
///
/// # Example
///
/// ```rust
/// use std::env;
///
/// // We will iterate through the references to the element returned by
/// // env::vars();
/// for (key, value) in env::vars() {
/// println!("{}: {}", key, value);
/// }
/// ```
pub fn vars() -> Vars {
Vars { inner: vars_os() }
}
/// Returns an iterator of (variable, value) pairs of OS strings, for all the
/// environment variables of the current process.
///
/// The returned iterator contains a snapshot of the process's environment
/// variables at the time of this invocation, modifications to environment
@@ -88,39 +122,30 @@ pub struct Vars { inner: os_imp::Env }
/// use std::env;
///
/// // We will iterate through the references to the element returned by
/// // env::vars();
/// for (key, value) in env::vars() {
/// // env::vars_os();
/// for (key, value) in env::vars_os() {
/// println!("{:?}: {:?}", key, value);
/// }
/// ```
pub fn vars() -> Vars {
pub fn vars_os() -> VarsOs {
let _g = ENV_LOCK.lock();
Vars { inner: os_imp::env() }
VarsOs { inner: os_imp::env() }
}
impl Iterator for Vars {
type Item = (OsString, OsString);
fn next(&mut self) -> Option<(OsString, OsString)> { self.inner.next() }
type Item = (String, String);
fn next(&mut self) -> Option<(String, String)> {
self.inner.next().map(|(a, b)| {
(a.into_string().unwrap(), b.into_string().unwrap())
})
}
fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
}
/// Fetches the environment variable `key` from the current process, returning
/// None if the variable isn't set.
///
/// # Example
///
/// ```rust
/// use std::env;
///
/// let key = "HOME";
/// match env::var(key) {
/// Some(val) => println!("{}: {:?}", key, val),
/// None => println!("{} is not defined in the environment.", key)
/// }
/// ```
pub fn var<K: ?Sized>(key: &K) -> Option<OsString> where K: AsOsStr {
let _g = ENV_LOCK.lock();
os_imp::getenv(key.as_os_str())
impl Iterator for VarsOs {
type Item = (OsString, OsString);
fn next(&mut self) -> Option<(OsString, OsString)> { self.inner.next() }
fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
}
/// Fetches the environment variable `key` from the current process.
@@ -135,18 +160,37 @@ pub fn var<K: ?Sized>(key: &K) -> Option<OsString> where K: AsOsStr {
/// use std::env;
///
/// let key = "HOME";
/// match env::var_string(key) {
/// match env::var(key) {
/// Ok(val) => println!("{}: {:?}", key, val),
/// Err(e) => println!("couldn't interpret {}: {}", key, e),
/// }
/// ```
pub fn var_string<K: ?Sized>(key: &K) -> Result<String, VarError> where K: AsOsStr {
match var(key) {
pub fn var<K: ?Sized>(key: &K) -> Result<String, VarError> where K: AsOsStr {
match var_os(key) {
Some(s) => s.into_string().map_err(VarError::NotUnicode),
None => Err(VarError::NotPresent)
}
}
/// Fetches the environment variable `key` from the current process, returning
/// None if the variable isn't set.
///
/// # Example
///
/// ```rust
/// use std::env;
///
/// let key = "HOME";
/// match env::var_os(key) {
/// Some(val) => println!("{}: {:?}", key, val),
/// None => println!("{} is not defined in the environment.", key)
/// }
/// ```
pub fn var_os<K: ?Sized>(key: &K) -> Option<OsString> where K: AsOsStr {
let _g = ENV_LOCK.lock();
os_imp::getenv(key.as_os_str())
}
/// Possible errors from the `env::var` method.
#[derive(Debug, PartialEq, Eq, Clone)]
pub enum VarError {
@@ -190,7 +234,7 @@ impl Error for VarError {
///
/// let key = "KEY";
/// env::set_var(key, "VALUE");
/// assert_eq!(env::var_string(key), Ok("VALUE".to_string()));
/// assert_eq!(env::var(key), Ok("VALUE".to_string()));
/// ```
pub fn set_var<K: ?Sized, V: ?Sized>(k: &K, v: &V)
where K: AsOsStr, V: AsOsStr
@@ -222,7 +266,7 @@ pub struct SplitPaths<'a> { inner: os_imp::SplitPaths<'a> }
/// use std::env;
///
/// let key = "PATH";
/// match env::var(key) {
/// match env::var_os(key) {
/// Some(paths) => {
/// for path in env::split_paths(&paths) {
/// println!("'{}'", path.display());
@@ -262,7 +306,7 @@ pub struct JoinPathsError {
/// ```rust
/// use std::env;
///
/// if let Some(path) = env::var("PATH") {
/// if let Some(path) = env::var_os("PATH") {
/// let mut paths = env::split_paths(&path).collect::<Vec<_>>();
/// paths.push(Path::new("/home/xyz/bin"));
/// let new_path = env::join_paths(paths.iter()).unwrap();
@@ -376,11 +420,44 @@ pub fn get_exit_status() -> i32 {
EXIT_STATUS.load(Ordering::SeqCst) as i32
}
/// An iterator over the arguments of a process, yielding an `OsString` value
/// An iterator over the arguments of a process, yielding an `String` value
/// for each argument.
///
/// This structure is created through the `std::env::args` method.
pub struct Args { inner: os_imp::Args }
pub struct Args { inner: ArgsOs }
/// An iterator over the arguments of a process, yielding an `OsString` value
/// for each argument.
///
/// This structure is created through the `std::env::args_os` method.
pub struct ArgsOs { inner: os_imp::Args }
/// Returns the arguments which this program was started with (normally passed
/// via the command line).
///
/// The first element is traditionally the path to the executable, but it can be
/// set to arbitrary text, and it may not even exist, so this property should
/// not be relied upon for security purposes.
///
/// # Panics
///
/// The returned iterator will panic during iteration if any argument to the
/// process is not valid unicode. If this is not desired it is recommended to
/// use the `args_os` function instead.
///
/// # Example
///
/// ```rust
/// use std::env;
///
/// // Prints each argument on a separate line
/// for argument in env::args() {
/// println!("{}", argument);
/// }
/// ```
pub fn args() -> Args {
Args { inner: args_os() }
}
/// Returns the arguments which this program was started with (normally passed
/// via the command line).
@@ -395,15 +472,23 @@ pub struct Args { inner: os_imp::Args }
/// use std::env;
///
/// // Prints each argument on a separate line
/// for argument in env::args() {
/// for argument in env::args_os() {
/// println!("{:?}", argument);
/// }
/// ```
pub fn args() -> Args {
Args { inner: os_imp::args() }
pub fn args_os() -> ArgsOs {
ArgsOs { inner: os_imp::args() }
}
impl Iterator for Args {
type Item = String;
fn next(&mut self) -> Option<String> {
self.inner.next().map(|s| s.into_string().unwrap())
}
fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
}
impl Iterator for ArgsOs {
type Item = OsString;
fn next(&mut self) -> Option<OsString> { self.inner.next() }
fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
@@ -706,7 +791,7 @@ mod tests {
let n = format!("TEST{}", rng.gen_ascii_chars().take(10)
.collect::<String>());
let n = OsString::from_string(n);
assert!(var(&n).is_none());
assert!(var_os(&n).is_none());
n
}
@@ -718,7 +803,7 @@ mod tests {
fn test_set_var() {
let n = make_rand_name();
set_var(&n, "VALUE");
eq(var(&n), Some("VALUE"));
eq(var_os(&n), Some("VALUE"));
}
#[test]
@@ -726,7 +811,7 @@ mod tests {
let n = make_rand_name();
set_var(&n, "VALUE");
remove_var(&n);
eq(var(&n), None);
eq(var_os(&n), None);
}
#[test]
@@ -734,9 +819,9 @@ mod tests {
let n = make_rand_name();
set_var(&n, "1");
set_var(&n, "2");
eq(var(&n), Some("2"));
eq(var_os(&n), Some("2"));
set_var(&n, "");
eq(var(&n), Some(""));
eq(var_os(&n), Some(""));
}
#[test]
@@ -749,7 +834,7 @@ mod tests {
}
let n = make_rand_name();
set_var(&n, s.as_slice());
eq(var(&n), Some(s.as_slice()));
eq(var_os(&n), Some(s.as_slice()));
}
#[test]
@@ -767,22 +852,22 @@ mod tests {
let n = make_rand_name();
let s = repeat("x").take(10000).collect::<String>();
set_var(&n, &s);
eq(var(&n), Some(s.as_slice()));
eq(var_os(&n), Some(s.as_slice()));
remove_var(&n);
eq(var(&n), None);
eq(var_os(&n), None);
}
#[test]
fn test_env_set_var() {
let n = make_rand_name();
let mut e = vars();
let mut e = vars_os();
set_var(&n, "VALUE");
assert!(!e.any(|(k, v)| {
&*k == &*n && &*v == "VALUE"
}));
assert!(vars().any(|(k, v)| {
assert!(vars_os().any(|(k, v)| {
&*k == &*n && &*v == "VALUE"
}));
}