[go: up one dir, main page]

duct 0.13.3

a library for running child processes
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# duct.rs [![Actions Status](https://github.com/oconnor663/duct.rs/workflows/tests/badge.svg)](https://github.com/oconnor663/duct.rs/actions) [![crates.io](https://img.shields.io/crates/v/duct.svg)](https://crates.io/crates/duct) [![docs.rs](https://docs.rs/duct/badge.svg)](https://docs.rs/duct)

Duct is a library for running child processes. Duct makes it easy to build
pipelines and redirect IO like a shell. At the same time, Duct helps you
write correct, portable code: whitespace is never significant, errors from
child processes get reported by default, and a variety of [gotchas, bugs,
and platform
inconsistencies](https://github.com/oconnor663/duct.py/blob/master/gotchas.md)
are handled for you the Right Way™.

- [Documentation](https://docs.rs/duct)
- [Crate](https://crates.io/crates/duct)
- [GitHub repo](https://github.com/oconnor663/duct.rs)
- [the same library, in Python](https://github.com/oconnor663/duct.py)

Changelog
---------

- v0.13.3
  - Added `Handle::pids` and `ReaderHandle::pids`.
- v0.13.2
  - Added `ReaderHandle::try_wait`.
  - Debug output for `Expression` is more concise.
- v0.13.1
  - Added `ReaderHandle::kill`.
  - Kill methods no longer wait on IO threads to complete. This avoids
    blocking on unkilled grandchildren.
- v0.13.0
  - The `kill` method now reaps killed child processes before returning.
  - Removed the `then` method.
  - Added `ReaderHandle` and `Expression::reader`.
  - Added `Expression::stdout_stderr_swap`.
  - Renamed `stdin`/`stdout`/`stderr` to
    `stdin_path`/`stdout_path`/`stderr_path`.
  - Renamed `stdin_handle`/`stdout_handle`/`stderr_handle` to
    `stdin_file`/`stdout_file`/`stderr_file`.
  - Renamed `input` to `stdin_bytes`.
  - Renamed `Handle::output` to `Handle::into_output`.

Examples
--------

Run a command without capturing any output. Here "hi" is printed directly
to the terminal:

```rust
use duct::cmd;
cmd!("echo", "hi").run()?;
```

Capture the standard output of a command. Here "hi" is returned as a
`String`:

```rust
let stdout = cmd!("echo", "hi").read()?;
assert_eq!(stdout, "hi");
```

Capture the standard output of a pipeline:

```rust
let stdout = cmd!("echo", "hi").pipe(cmd!("sed", "s/i/o/")).read()?;
assert_eq!(stdout, "ho");
```

Merge standard error into standard output and read both incrementally:

```rust
use duct::cmd;
use std::io::prelude::*;
use std::io::BufReader;

let big_cmd = cmd!("bash", "-c", "echo out && echo err 1>&2");
let reader = big_cmd.stderr_to_stdout().reader()?;
let mut lines = BufReader::new(reader).lines();
assert_eq!(lines.next().unwrap()?, "out");
assert_eq!(lines.next().unwrap()?, "err");
```

Children that exit with a non-zero status return an error by default:

```rust
let result = cmd!("false").run();
assert!(result.is_err());
```