From 5243a98b48da3bdac81e9685526d731e88dc48a1 Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Fri, 13 Oct 2017 23:38:55 -0700 Subject: [PATCH 1/6] Add a brief description and two examples to std::process --- src/libstd/process.rs | 50 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 7 deletions(-) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 7d8ce4154fbfc..d3e60e3dff9d8 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -10,24 +10,57 @@ //! A module for working with processes. //! +//! This module provides a [`Command`] struct that can be used to configure and +//! spawn a process, as well as a [`Child`] struct that represents a running or +//! terminated process. +//! //! # Examples //! -//! Basic usage where we try to execute the `cat` shell command: +//! Hello world, `std::process` edition: //! -//! ```should_panic -//! use std::process::Command; +//! ``` +//! use std::process:Command; //! -//! let mut child = Command::new("/bin/cat") -//! .arg("file.txt") +//! // Note that by default, the output of the command will be sent to stdout +//! let child = Command::new("echo") +//! .arg("Hello world") //! .spawn() -//! .expect("failed to execute child"); +//! .expect("Failed to start process"); //! //! let ecode = child.wait() -//! .expect("failed to wait on child"); +//! .expect("Failed to wait on child"); //! //! assert!(ecode.success()); //! ``` //! +//! Piping output from one command into another command: +//! +//! ``` +//! use std::process::{Command, Stdio}; +//! +//! // stdout must be configured with `Stdio::piped` in order to use +//! // `echo_child.stdout` +//! let echo_child = Command::new("echo") +//! .arg("Oh no, a tpyo!") +//! .stdout(Stdio::piped()) +//! .spawn() +//! .expect("Failed to start echo process"); +//! +//! // Note that `echo_child` is moved here, but we won't be needing +//! // `echo_child` anymore +//! let echo_out = echo_child.stdout.expect("Failed to open echo stdout"); +//! +//! let mut sed_child = Command::new("sed") +//! .arg("s/tpyo/typo/") +//! .stdin(Stdio::from(echo_out)) +//! .stdout(Stdio::piped()) +//! .spawn() +//! .expect("Failed to start sed process"); +//! +//! let output = sed_child.wait_with_output().expect("Failed to wait on sed"); +//! assert_eq!(b"Oh no, a typo!\n", output.stdout.as_slice()); +//! ``` +//! //! Calling a command with input and reading its output: //! //! ```no_run @@ -52,6 +85,9 @@ //! //! assert_eq!(b"test", output.stdout.as_slice()); //! ``` +//! +//! [`Command`]: struct.Command.html +//! [`Child`]: struct.Child.html #![stable(feature = "process", since = "1.0.0")] From e788e90bad6b1ee5c028d5536c373c3f2c8a3bc4 Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Sat, 14 Oct 2017 20:41:58 -0700 Subject: [PATCH 2/6] Fixed accidental deletion of colon --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index d3e60e3dff9d8..5428ed59c68d9 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -19,7 +19,7 @@ //! Hello world, `std::process` edition: //! //! ``` -//! use std::process:Command; +//! use std::process::Command; //! //! // Note that by default, the output of the command will be sent to stdout //! let child = Command::new("echo") From bb74b13b742d214d20bb646d5b8d3eaebaad9b8b Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Sun, 15 Oct 2017 13:11:14 -0700 Subject: [PATCH 3/6] Fix std::process hello world example --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 5428ed59c68d9..38f218ba9d54a 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -22,7 +22,7 @@ //! use std::process::Command; //! //! // Note that by default, the output of the command will be sent to stdout -//! let child = Command::new("echo") +//! let mut child = Command::new("echo") //! .arg("Hello world") //! .spawn() //! .expect("Failed to start process"); From f67f6622b37bca1b2430ab2987d94d31ad436762 Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Sun, 15 Oct 2017 19:45:07 -0700 Subject: [PATCH 4/6] Create section on how to spawn processes; change module description --- src/libstd/process.rs | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 38f218ba9d54a..72402aaae3000 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -10,29 +10,36 @@ //! A module for working with processes. //! -//! This module provides a [`Command`] struct that can be used to configure and -//! spawn a process, as well as a [`Child`] struct that represents a running or -//! terminated process. +//! This module is mostly concerned with spawning and interacting with child +//! processes, but it also provides [`abort`] and [`exit`] for terminating the +//! current process. //! -//! # Examples +//! # Spawning a process //! -//! Hello world, `std::process` edition: +//! The [`Command`] struct is used to configure and spawn processes: //! //! ``` //! use std::process::Command; //! -//! // Note that by default, the output of the command will be sent to stdout -//! let mut child = Command::new("echo") -//! .arg("Hello world") -//! .spawn() -//! .expect("Failed to start process"); -//! -//! let ecode = child.wait() -//! .expect("Failed to wait on child"); +//! let output = Command::new("echo") +//! .arg("Hello world") +//! .output() +//! .expect("Failed to execute command"); //! -//! assert!(ecode.success()); +//! assert_eq!(b"Hello world\n", output.stdout.as_slice()); //! ``` //! +//! Several methods on [`Command`], such as [`spawn`] or [`output`], can be used +//! to spawn a process. In particular, [`output`] spawns the child process and +//! waits until the process terminates, while [`spawn`] will return a [`Child`] +//! that represents the spawned child process. +//! +//! # Handling I/O +//! +//! TODO +//! +//! # Examples +//! //! Piping output from one command into another command: //! //! ``` @@ -86,8 +93,15 @@ //! assert_eq!(b"test", output.stdout.as_slice()); //! ``` //! +//! [`abort`]: fn.abort.html +//! [`exit`]: fn.exit.html +//! //! [`Command`]: struct.Command.html +//! [`spawn`]: struct.Command.html#method.spawn +//! [`output`]: struct.Command.html#method.output +//! //! [`Child`]: struct.Child.html +//! [`Stdio`]: struct.Stdio.html #![stable(feature = "process", since = "1.0.0")] From 3566832ef3a5af2ee29a76f95b55c6e1fafcf02a Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Tue, 17 Oct 2017 17:49:02 -0700 Subject: [PATCH 5/6] Add child process IO handling docs --- src/libstd/process.rs | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 72402aaae3000..bcdbee52ca3be 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -36,11 +36,11 @@ //! //! # Handling I/O //! -//! TODO -//! -//! # Examples -//! -//! Piping output from one command into another command: +//! The [`stdout`], [`stdin`], and [`stderr`] of a child process can be +//! configured by passing an [`Stdio`] to the corresponding method on +//! [`Command`]. Once spawned, they can be accessed from the [`Child`]. For +//! example, piping output from one command into another command can be done +//! like so: //! //! ``` //! use std::process::{Command, Stdio}; @@ -68,9 +68,10 @@ //! assert_eq!(b"Oh no, a typo!\n", output.stdout.as_slice()); //! ``` //! -//! Calling a command with input and reading its output: +//! Note that [`ChildStderr`] and [`ChildStdout`] implement [`Write`] and +//! [`ChildStdin`] implements [`Read`]: //! -//! ```no_run +//! ``` //! use std::process::{Command, Stdio}; //! use std::io::Write; //! @@ -101,7 +102,17 @@ //! [`output`]: struct.Command.html#method.output //! //! [`Child`]: struct.Child.html +//! [`ChildStdin`]: struct.ChildStdin.html +//! [`ChildStdout`]: struct.ChildStdout.html +//! [`ChildStderr`]: struct.ChildStderr.html //! [`Stdio`]: struct.Stdio.html +//! +//! [`stdout`]: struct.Command.html#method.stdout +//! [`stdin`]: struct.Command.html#method.stdin +//! [`stderr`]: struct.Command.html#method.stderr +//! +//! [`Write`]: ../io/trait.Write.html +//! [`Read`]: ../io/trait.Read.html #![stable(feature = "process", since = "1.0.0")] From 84ab6aec4380b0d1de2a46a9f57e172cc709fcb8 Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Sat, 28 Oct 2017 20:24:49 -0700 Subject: [PATCH 6/6] Add no_run to process examples involving unix commands --- src/libstd/process.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index bcdbee52ca3be..7f9d043c1e554 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -42,7 +42,7 @@ //! example, piping output from one command into another command can be done //! like so: //! -//! ``` +//! ```no_run //! use std::process::{Command, Stdio}; //! //! // stdout must be configured with `Stdio::piped` in order to use @@ -71,7 +71,7 @@ //! Note that [`ChildStderr`] and [`ChildStdout`] implement [`Write`] and //! [`ChildStdin`] implements [`Read`]: //! -//! ``` +//! ```no_run //! use std::process::{Command, Stdio}; //! use std::io::Write; //!