Skip to content

Commit

Permalink
task: clarify process::Command docs (#5406)
Browse files Browse the repository at this point in the history
  • Loading branch information
@mTsBucy1
mTsBucy1 committed Jan 30, 2023
1 parent 88b1eb5 commit 469b94f
Showing 1 changed file with 67 additions and 28 deletions.
95 changes: 67 additions & 28 deletions tokio/src/process/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -309,7 +309,8 @@ impl Command {
///
/// ```no_run
/// use tokio::process::Command;
/// let command = Command::new("sh");
/// let mut command = Command::new("sh");
/// # let _ = command.output(); // assert borrow checker
/// ```
///
/// [rust-lang/rust#37519]: https://github.com/rust-lang/rust/issues/37519
Expand All @@ -328,16 +329,20 @@ impl Command {
/// Only one argument can be passed per use. So instead of:
///
/// ```no_run
/// tokio::process::Command::new("sh")
/// .arg("-C /path/to/repo");
/// let mut command = tokio::process::Command::new("sh");
/// command.arg("-C /path/to/repo");
///
/// # let _ = command.output(); // assert borrow checker
/// ```
///
/// usage would be:
///
/// ```no_run
/// tokio::process::Command::new("sh")
/// .arg("-C")
/// .arg("/path/to/repo");
/// let mut command = tokio::process::Command::new("sh");
/// command.arg("-C");
/// command.arg("/path/to/repo");
///
/// # let _ = command.output(); // assert borrow checker
/// ```
///
/// To pass multiple arguments see [`args`].
Expand All @@ -349,11 +354,15 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
///
/// let command = Command::new("ls")
/// let output = Command::new("ls")
/// .arg("-l")
/// .arg("-a");
/// .arg("-a")
/// .output().await.unwrap();
/// # }
///
/// ```
pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Command {
self.std.arg(arg);
Expand All @@ -371,10 +380,13 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
///
/// let command = Command::new("ls")
/// .args(&["-l", "-a"]);
/// let output = Command::new("ls")
/// .args(&["-l", "-a"])
/// .output().await.unwrap();
/// # }
/// ```
pub fn args<I, S>(&mut self, args: I) -> &mut Command
where
Expand All @@ -395,10 +407,13 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
///
/// let command = Command::new("ls")
/// .env("PATH", "/bin");
/// let output = Command::new("ls")
/// .env("PATH", "/bin")
/// .output().await.unwrap();
/// # }
/// ```
pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Command
where
Expand All @@ -416,6 +431,7 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
/// use std::process::{Stdio};
/// use std::env;
Expand All @@ -426,11 +442,13 @@ impl Command {
/// k == "TERM" || k == "TZ" || k == "LANG" || k == "PATH"
/// ).collect();
///
/// let command = Command::new("printenv")
/// let output = Command::new("printenv")
/// .stdin(Stdio::null())
/// .stdout(Stdio::inherit())
/// .env_clear()
/// .envs(&filtered_env);
/// .envs(&filtered_env)
/// .output().await.unwrap();
/// # }
/// ```
pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Command
where
Expand All @@ -449,10 +467,13 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
///
/// let command = Command::new("ls")
/// .env_remove("PATH");
/// let output = Command::new("ls")
/// .env_remove("PATH")
/// .output().await.unwrap();
/// # }
/// ```
pub fn env_remove<K: AsRef<OsStr>>(&mut self, key: K) -> &mut Command {
self.std.env_remove(key);
Expand All @@ -466,10 +487,13 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
///
/// let command = Command::new("ls")
/// .env_clear();
/// let output = Command::new("ls")
/// .env_clear()
/// .output().await.unwrap();
/// # }
/// ```
pub fn env_clear(&mut self) -> &mut Command {
self.std.env_clear();
Expand All @@ -493,10 +517,13 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
///
/// let command = Command::new("ls")
/// .current_dir("/bin");
/// let output = Command::new("ls")
/// .current_dir("/bin")
/// .output().await.unwrap();
/// # }
/// ```
pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Command {
self.std.current_dir(dir);
Expand All @@ -516,11 +543,14 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use std::process::{Stdio};
/// use tokio::process::Command;
///
/// let command = Command::new("ls")
/// .stdin(Stdio::null());
/// let output = Command::new("ls")
/// .stdin(Stdio::null())
/// .output().await.unwrap();
/// # }
/// ```
pub fn stdin<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command {
self.std.stdin(cfg);
Expand All @@ -540,11 +570,14 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
/// use std::process::Stdio;
///
/// let command = Command::new("ls")
/// .stdout(Stdio::null());
/// let output = Command::new("ls")
/// .stdout(Stdio::null())
/// .output().await.unwrap();
/// # }
/// ```
pub fn stdout<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command {
self.std.stdout(cfg);
Expand All @@ -564,11 +597,14 @@ impl Command {
/// Basic usage:
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
/// use std::process::{Stdio};
///
/// let command = Command::new("ls")
/// .stderr(Stdio::null());
/// let output = Command::new("ls")
/// .stderr(Stdio::null())
/// .output().await.unwrap();
/// # }
/// ```
pub fn stderr<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command {
self.std.stderr(cfg);
Expand Down Expand Up @@ -707,10 +743,13 @@ impl Command {
/// [`tokio::process::Command`]: crate::process::Command
///
/// ```no_run
/// # async fn test() { // allow using await
/// use tokio::process::Command;
///
/// let command = Command::new("ls")
/// .process_group(0);
/// let output = Command::new("ls")
/// .process_group(0)
/// .output().await.unwrap();
/// # }
/// ```
#[cfg(unix)]
#[cfg(tokio_unstable)]
Expand Down

0 comments on commit 469b94f

Please sign in to comment.