Skip to content

Improve std::process module docs #45295

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 29, 2017
Merged

Improve std::process module docs #45295

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5243a98
Add a brief description and two examples to std::process
Technius Oct 14, 2017
e788e90
Fixed accidental deletion of colon
Technius Oct 15, 2017
bb74b13
Fix std::process hello world example
Technius Oct 15, 2017
f67f662
Create section on how to spawn processes; change module description
Technius Oct 16, 2017
3566832
Add child process IO handling docs
Technius Oct 18, 2017
84ab6ae
Add no_run to process examples involving unix commands
Technius Oct 29, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 42 additions & 6 deletions src/libstd/process.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
//!
//! 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")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

child needs to be mut.

[01:19:37] failures:
[01:19:37] 
[01:19:37] ---- process.rs - process (line 21) stdout ----
[01:19:37] 	error[E0596]: cannot borrow immutable local variable `child` as mutable
[01:19:37]   --> process.rs:12:13
[01:19:37]    |
[01:19:37] 7  | let child = Command::new("echo")
[01:19:37]    |     ----- consider changing this to `mut child`
[01:19:37] ...
[01:19:37] 12 | let ecode = child.wait()
[01:19:37]    |             ^^^^^ cannot borrow mutably
[01:19:37] 
[01:19:37] thread 'rustc' panicked at 'couldn't compile the test', /checkout/src/librustdoc/test.rs:283:12
[01:19:37] note: Run with `RUST_BACKTRACE=1` for a backtrace.
[01:19:37] 
[01:19:37] 
[01:19:37] failures:
[01:19:37]     process.rs - process (line 21)
[01:19:37] 
[01:19:37] test result: FAILED. 877 passed; 1 failed; 10 ignored; 0 measured; 0 filtered out

//! .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
Expand All @@ -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")]

Expand Down