Skip to content

Commit 27c01cb

Browse files
GuillaumeGomezGuillaumeGomez
committed
Add process types documentation
1 parent e07e34c commit 27c01cb

File tree

1 file changed

+196
-4
lines changed

1 file changed

+196
-4
lines changed

‎src/libstd/process.rs‎

Lines changed: 196 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -215,19 +215,58 @@ impl Command {
215215
///
216216
/// Builder methods are provided to change these defaults and
217217
/// otherwise configure the process.
218+
///
219+
/// # Examples
220+
///
221+
/// Basic usage:
222+
///
223+
/// ```no_run
224+
/// use std::process::Command;
225+
///
226+
/// Command::new("sh")
227+
/// .spawn()
228+
/// .expect("sh command failed to start");
229+
/// ```
218230
#[stable(feature = "process", since = "1.0.0")]
219231
pub fn new<S: AsRef<OsStr>>(program: S) -> Command {
220232
Command { inner: imp::Command::new(program.as_ref()) }
221233
}
222234

223235
/// Add an argument to pass to the program.
236+
///
237+
/// # Examples
238+
///
239+
/// Basic usage:
240+
///
241+
/// ```no_run
242+
/// use std::process::Command;
243+
///
244+
/// Command::new("ls")
245+
/// .arg("-l")
246+
/// .arg("-a")
247+
/// .spawn()
248+
/// .expect("ls command failed to start");
249+
/// ```
224250
#[stable(feature = "process", since = "1.0.0")]
225251
pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Command {
226252
self.inner.arg(arg.as_ref());
227253
self
228254
}
229255

230256
/// Add multiple arguments to pass to the program.
257+
///
258+
/// # Examples
259+
///
260+
/// Basic usage:
261+
///
262+
/// ```no_run
263+
/// use std::process::Command;
264+
///
265+
/// Command::new("ls")
266+
/// .args(&["-l", "-a"])
267+
/// .spawn()
268+
/// .expect("ls command failed to start");
269+
/// ```
231270
#[stable(feature = "process", since = "1.0.0")]
232271
pub fn args<S: AsRef<OsStr>>(&mut self, args: &[S]) -> &mut Command {
233272
for arg in args {
@@ -240,6 +279,19 @@ impl Command {
240279
///
241280
/// Note that environment variable names are case-insensitive (but case-preserving) on Windows,
242281
/// and case-sensitive on all other platforms.
282+
///
283+
/// # Examples
284+
///
285+
/// Basic usage:
286+
///
287+
/// ```no_run
288+
/// use std::process::Command;
289+
///
290+
/// Command::new("ls")
291+
/// .env("PATH", "/bin")
292+
/// .spawn()
293+
/// .expect("ls command failed to start");
294+
/// ```
243295
#[stable(feature = "process", since = "1.0.0")]
244296
pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Command
245297
where K: AsRef<OsStr>, V: AsRef<OsStr>
@@ -249,41 +301,119 @@ impl Command {
249301
}
250302

251303
/// Removes an environment variable mapping.
304+
///
305+
/// # Examples
306+
///
307+
/// Basic usage:
308+
///
309+
/// ```no_run
310+
/// use std::process::Command;
311+
///
312+
/// Command::new("ls")
313+
/// .env_remove("PATH")
314+
/// .spawn()
315+
/// .expect("ls command failed to start");
316+
/// ```
252317
#[stable(feature = "process", since = "1.0.0")]
253318
pub fn env_remove<K: AsRef<OsStr>>(&mut self, key: K) -> &mut Command {
254319
self.inner.env_remove(key.as_ref());
255320
self
256321
}
257322

258323
/// Clears the entire environment map for the child process.
324+
///
325+
/// # Examples
326+
///
327+
/// Basic usage:
328+
///
329+
/// ```no_run
330+
/// use std::process::Command;
331+
///
332+
/// Command::new("ls")
333+
/// .env_clear()
334+
/// .spawn()
335+
/// .expect("ls command failed to start");
336+
/// ```
259337
#[stable(feature = "process", since = "1.0.0")]
260338
pub fn env_clear(&mut self) -> &mut Command {
261339
self.inner.env_clear();
262340
self
263341
}
264342

265343
/// Sets the working directory for the child process.
344+
///
345+
/// # Examples
346+
///
347+
/// Basic usage:
348+
///
349+
/// ```no_run
350+
/// use std::process::Command;
351+
///
352+
/// Command::new("ls")
353+
/// .current_dir("/bin")
354+
/// .spawn()
355+
/// .expect("ls command failed to start");
356+
/// ```
266357
#[stable(feature = "process", since = "1.0.0")]
267358
pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Command {
268359
self.inner.cwd(dir.as_ref().as_ref());
269360
self
270361
}
271362

272363
/// Configuration for the child process's stdin handle (file descriptor 0).
364+
///
365+
/// # Examples
366+
///
367+
/// Basic usage:
368+
///
369+
/// ```no_run
370+
/// use std::process::{Command, Stdio};
371+
///
372+
/// Command::new("ls")
373+
/// .stdin(Stdio::null())
374+
/// .spawn()
375+
/// .expect("ls command failed to start");
376+
/// ```
273377
#[stable(feature = "process", since = "1.0.0")]
274378
pub fn stdin(&mut self, cfg: Stdio) -> &mut Command {
275379
self.inner.stdin(cfg.0);
276380
self
277381
}
278382

279383
/// Configuration for the child process's stdout handle (file descriptor 1).
384+
///
385+
/// # Examples
386+
///
387+
/// Basic usage:
388+
///
389+
/// ```no_run
390+
/// use std::process::{Command, Stdio};
391+
///
392+
/// Command::new("ls")
393+
/// .stdout(Stdio::null())
394+
/// .spawn()
395+
/// .expect("ls command failed to start");
396+
/// ```
280397
#[stable(feature = "process", since = "1.0.0")]
281398
pub fn stdout(&mut self, cfg: Stdio) -> &mut Command {
282399
self.inner.stdout(cfg.0);
283400
self
284401
}
285402

286403
/// Configuration for the child process's stderr handle (file descriptor 2).
404+
///
405+
/// # Examples
406+
///
407+
/// Basic usage:
408+
///
409+
/// ```no_run
410+
/// use std::process::{Command, Stdio};
411+
///
412+
/// Command::new("ls")
413+
/// .stderr(Stdio::null())
414+
/// .spawn()
415+
/// .expect("ls command failed to start");
416+
/// ```
287417
#[stable(feature = "process", since = "1.0.0")]
288418
pub fn stderr(&mut self, cfg: Stdio) -> &mut Command {
289419
self.inner.stderr(cfg.0);
@@ -293,6 +423,18 @@ impl Command {
293423
/// Executes the command as a child process, returning a handle to it.
294424
///
295425
/// By default, stdin, stdout and stderr are inherited from the parent.
426+
///
427+
/// # Examples
428+
///
429+
/// Basic usage:
430+
///
431+
/// ```no_run
432+
/// use std::process::Command;
433+
///
434+
/// Command::new("ls")
435+
/// .spawn()
436+
/// .expect("ls command failed to start");
437+
/// ```
296438
#[stable(feature = "process", since = "1.0.0")]
297439
pub fn spawn(&mut self) -> io::Result<Child> {
298440
self.inner.spawn(imp::Stdio::Inherit, true).map(Child::from_inner)
@@ -308,8 +450,10 @@ impl Command {
308450
///
309451
/// ```should_panic
310452
/// use std::process::Command;
311-
/// let output = Command::new("/bin/cat").arg("file.txt").output()
312-
/// .expect("failed to execute process");
453+
/// let output = Command::new("/bin/cat")
454+
/// .arg("file.txt")
455+
/// .output()
456+
/// .expect("failed to execute process");
313457
///
314458
/// println!("status: {}", output.status);
315459
/// println!("stdout: {}", String::from_utf8_lossy(&output.stdout));
@@ -333,8 +477,10 @@ impl Command {
333477
/// ```should_panic
334478
/// use std::process::Command;
335479
///
336-
/// let status = Command::new("/bin/cat").arg("file.txt").status()
337-
/// .expect("failed to execute process");
480+
/// let status = Command::new("/bin/cat")
481+
/// .arg("file.txt")
482+
/// .status()
483+
/// .expect("failed to execute process");
338484
///
339485
/// println!("process exited with: {}", status);
340486
///
@@ -469,12 +615,42 @@ impl fmt::Display for ExitStatus {
469615
impl Child {
470616
/// Forces the child to exit. This is equivalent to sending a
471617
/// SIGKILL on unix platforms.
618+
///
619+
/// # Examples
620+
///
621+
/// Basic usage:
622+
///
623+
/// ```no_run
624+
/// use std::process::Command;
625+
///
626+
/// let mut command = Command::new("yes");
627+
/// if let Ok(mut child) = command.spawn() {
628+
/// child.kill().expect("command wasn't running");
629+
/// } else {
630+
/// println!("yes command didn't start");
631+
/// }
632+
/// ```
472633
#[stable(feature = "process", since = "1.0.0")]
473634
pub fn kill(&mut self) -> io::Result<()> {
474635
self.handle.kill()
475636
}
476637

477638
/// Returns the OS-assigned process identifier associated with this child.
639+
///
640+
/// # Examples
641+
///
642+
/// Basic usage:
643+
///
644+
/// ```no_run
645+
/// use std::process::Command;
646+
///
647+
/// let mut command = Command::new("ls");
648+
/// if let Ok(child) = command.spawn() {
649+
/// println!("Child's id is {}", child.id());
650+
/// } else {
651+
/// println!("ls command didn't start");
652+
/// }
653+
/// ```
478654
#[stable(feature = "process_id", since = "1.3.0")]
479655
pub fn id(&self) -> u32 {
480656
self.handle.id()
@@ -488,6 +664,22 @@ impl Child {
488664
/// before waiting. This helps avoid deadlock: it ensures that the
489665
/// child does not block waiting for input from the parent, while
490666
/// the parent waits for the child to exit.
667+
///
668+
/// # Examples
669+
///
670+
/// Basic usage:
671+
///
672+
/// ```no_run
673+
/// use std::process::Command;
674+
///
675+
/// let mut command = Command::new("ls");
676+
/// if let Ok(mut child) = command.spawn() {
677+
/// child.wait().expect("command wasn't running");
678+
/// println!("Child has finished its execution!");
679+
/// } else {
680+
/// println!("ls command didn't start");
681+
/// }
682+
/// ```
491683
#[stable(feature = "process", since = "1.0.0")]
492684
pub fn wait(&mut self) -> io::Result<ExitStatus> {
493685
drop(self.stdin.take());

0 commit comments

Comments
 (0)