#![stable(feature = "env", since = "1.0.0")]
+#[cfg(test)]
+mod tests;
+
use crate::error::Error;
use crate::ffi::{OsStr, OsString};
use crate::fmt;
/// An iterator over a snapshot of the environment variables of this process.
///
-/// This structure is created by the [`std::env::vars`] function. See its
-/// documentation for more.
+/// This structure is created by [`env::vars()`]. See its documentation for more.
///
-/// [`std::env::vars`]: vars
+/// [`env::vars()`]: vars
#[stable(feature = "env", since = "1.0.0")]
pub struct Vars {
inner: VarsOs,
/// An iterator over a snapshot of the environment variables of this process.
///
-/// This structure is created by the [`std::env::vars_os`] function. See
-/// its documentation for more.
+/// This structure is created by [`env::vars_os()`]. See its documentation for more.
///
-/// [`std::env::vars_os`]: vars_os
+/// [`env::vars_os()`]: vars_os
#[stable(feature = "env", since = "1.0.0")]
pub struct VarsOs {
inner: os_imp::Env,
/// # 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.
-///
-/// [`env::vars_os`]: vars_os
+/// environment is not valid unicode. If this is not desired, consider using
+/// [`env::vars_os()`].
///
/// # Examples
///
/// println!("{}: {}", key, value);
/// }
/// ```
+///
+/// [`env::vars_os()`]: vars_os
#[stable(feature = "env", since = "1.0.0")]
pub fn vars() -> Vars {
Vars { inner: vars_os() }
}
/// The error type for operations interacting with environment variables.
-/// Possibly returned from the [`env::var`] function.
+/// Possibly returned from [`env::var()`].
///
-/// [`env::var`]: var
+/// [`env::var()`]: var
#[derive(Debug, PartialEq, Eq, Clone)]
#[stable(feature = "env", since = "1.0.0")]
pub enum VarError {
///
/// The iterator element type is [`PathBuf`].
///
-/// This structure is created by the [`std::env::split_paths`] function. See its
+/// This structure is created by [`env::split_paths()`]. See its
/// documentation for more.
///
-/// [`std::env::split_paths`]: split_paths
+/// [`env::split_paths()`]: split_paths
#[stable(feature = "env", since = "1.0.0")]
pub struct SplitPaths<'a> {
inner: os_imp::SplitPaths<'a>,
}
/// The error type for operations on the `PATH` variable. Possibly returned from
-/// the [`env::join_paths`] function.
+/// [`env::join_paths()`].
///
-/// [`env::join_paths`]: join_paths
+/// [`env::join_paths()`]: join_paths
#[derive(Debug)]
#[stable(feature = "env", since = "1.0.0")]
pub struct JoinPathsError {
/// }
/// ```
///
-/// Joining a path containing a colon on a Unix-like platform results in an error:
+/// Joining a path containing a colon on a Unix-like platform results in an
+/// error:
///
/// ```
/// # if cfg!(unix) {
/// # }
/// ```
///
-/// Using `env::join_paths` with [`env::split_paths`] to append an item to the `PATH` environment
-/// variable:
+/// Using `env::join_paths()` with [`env::split_paths()`] to append an item to
+/// the `PATH` environment variable:
///
/// ```
/// use std::env;
/// }
/// ```
///
-/// [`env::split_paths`]: split_paths
+/// [`env::split_paths()`]: split_paths
#[stable(feature = "env", since = "1.0.0")]
pub fn join_paths<I, T>(paths: I) -> Result<OsString, JoinPathsError>
where
/// An iterator over the arguments of a process, yielding a [`String`] value for
/// each argument.
///
-/// This struct is created by the [`std::env::args`] function. See its
-/// documentation for more.
+/// This struct is created by [`env::args()`]. See its documentation
+/// for more.
///
/// The first element is traditionally the path of the executable, but it can be
/// set to arbitrary text, and may not even exist. This means this property
/// should not be relied upon for security purposes.
///
-/// [`std::env::args`]: args
+/// [`env::args()`]: args
#[stable(feature = "env", since = "1.0.0")]
pub struct Args {
inner: ArgsOs,
/// An iterator over the arguments of a process, yielding an [`OsString`] value
/// for each argument.
///
-/// This struct is created by the [`std::env::args_os`] function. See its
-/// documentation for more.
+/// This struct is created by [`env::args_os()`]. See its documentation
+/// for more.
///
/// The first element is traditionally the path of the executable, but it can be
/// set to arbitrary text, and may not even exist. This means this property
/// should not be relied upon for security purposes.
///
-/// [`std::env::args_os`]: args_os
+/// [`env::args_os()`]: args_os
#[stable(feature = "env", since = "1.0.0")]
pub struct ArgsOs {
inner: sys::args::Args,
}
-/// Returns the arguments which this program was started with (normally passed
+/// Returns the arguments that this program was started with (normally passed
/// via the command line).
///
/// The first element is traditionally the path of the executable, but it can be
/// set to arbitrary text, and may not even exist. This means this property should
/// not be relied upon for security purposes.
///
-/// On Unix systems shell usually expands unquoted arguments with glob patterns
+/// On Unix systems the shell usually expands unquoted arguments with glob patterns
/// (such as `*` and `?`). On Windows this is not done, and such arguments are
/// passed as-is.
///
-/// On glibc Linux systems, arguments are retrieved by placing a function in ".init_array".
-/// Glibc passes argc, argv, and envp to functions in ".init_array", as a non-standard extension.
-/// This allows `std::env::args` to work even in a `cdylib` or `staticlib`, as it does on macOS
-/// and Windows.
+/// On glibc Linux systems, arguments are retrieved by placing a function in `.init_array`.
+/// Glibc passes `argc`, `argv`, and `envp` to functions in `.init_array`, as a non-standard
+/// extension. This allows `std::env::args` to work even in a `cdylib` or `staticlib`, as it
+/// does on macOS and Windows.
///
/// # Panics
///
#[stable(feature = "env", since = "1.0.0")]
pub const EXE_EXTENSION: &str = os::EXE_EXTENSION;
}
-
-#[cfg(test)]
-mod tests {
- use super::*;
-
- use crate::path::Path;
-
- #[test]
- #[cfg_attr(any(target_os = "emscripten", target_env = "sgx"), ignore)]
- fn test_self_exe_path() {
- let path = current_exe();
- assert!(path.is_ok());
- let path = path.unwrap();
-
- // Hard to test this function
- assert!(path.is_absolute());
- }
-
- #[test]
- fn test() {
- assert!((!Path::new("test-path").is_absolute()));
-
- #[cfg(not(target_env = "sgx"))]
- current_dir().unwrap();
- }
-
- #[test]
- #[cfg(windows)]
- fn split_paths_windows() {
- use crate::path::PathBuf;
-
- fn check_parse(unparsed: &str, parsed: &[&str]) -> bool {
- split_paths(unparsed).collect::<Vec<_>>()
- == parsed.iter().map(|s| PathBuf::from(*s)).collect::<Vec<_>>()
- }
-
- assert!(check_parse("", &mut [""]));
- assert!(check_parse(r#""""#, &mut [""]));
- assert!(check_parse(";;", &mut ["", "", ""]));
- assert!(check_parse(r"c:\", &mut [r"c:\"]));
- assert!(check_parse(r"c:\;", &mut [r"c:\", ""]));
- assert!(check_parse(r"c:\;c:\Program Files\", &mut [r"c:\", r"c:\Program Files\"]));
- assert!(check_parse(r#"c:\;c:\"foo"\"#, &mut [r"c:\", r"c:\foo\"]));
- assert!(check_parse(
- r#"c:\;c:\"foo;bar"\;c:\baz"#,
- &mut [r"c:\", r"c:\foo;bar\", r"c:\baz"]
- ));
- }
-
- #[test]
- #[cfg(unix)]
- fn split_paths_unix() {
- use crate::path::PathBuf;
-
- fn check_parse(unparsed: &str, parsed: &[&str]) -> bool {
- split_paths(unparsed).collect::<Vec<_>>()
- == parsed.iter().map(|s| PathBuf::from(*s)).collect::<Vec<_>>()
- }
-
- assert!(check_parse("", &mut [""]));
- assert!(check_parse("::", &mut ["", "", ""]));
- assert!(check_parse("/", &mut ["/"]));
- assert!(check_parse("/:", &mut ["/", ""]));
- assert!(check_parse("/:/usr/local", &mut ["/", "/usr/local"]));
- }
-
- #[test]
- #[cfg(unix)]
- fn join_paths_unix() {
- use crate::ffi::OsStr;
-
- fn test_eq(input: &[&str], output: &str) -> bool {
- &*join_paths(input.iter().cloned()).unwrap() == OsStr::new(output)
- }
-
- assert!(test_eq(&[], ""));
- assert!(test_eq(&["/bin", "/usr/bin", "/usr/local/bin"], "/bin:/usr/bin:/usr/local/bin"));
- assert!(test_eq(&["", "/bin", "", "", "/usr/bin", ""], ":/bin:::/usr/bin:"));
- assert!(join_paths(["/te:st"].iter().cloned()).is_err());
- }
-
- #[test]
- #[cfg(windows)]
- fn join_paths_windows() {
- use crate::ffi::OsStr;
-
- fn test_eq(input: &[&str], output: &str) -> bool {
- &*join_paths(input.iter().cloned()).unwrap() == OsStr::new(output)
- }
-
- assert!(test_eq(&[], ""));
- assert!(test_eq(&[r"c:\windows", r"c:\"], r"c:\windows;c:\"));
- assert!(test_eq(&["", r"c:\windows", "", "", r"c:\", ""], r";c:\windows;;;c:\;"));
- assert!(test_eq(&[r"c:\te;st", r"c:\"], r#""c:\te;st";c:\"#));
- assert!(join_paths([r#"c:\te"st"#].iter().cloned()).is_err());
- }
-
- #[test]
- fn args_debug() {
- assert_eq!(
- format!("Args {{ inner: {:?} }}", args().collect::<Vec<_>>()),
- format!("{:?}", args())
- );
- assert_eq!(
- format!("ArgsOs {{ inner: {:?} }}", args_os().collect::<Vec<_>>()),
- format!("{:?}", args_os())
- );
- }
-}
projects / rustc.git / blobdiff