bawawa 0.1.5

Opinionated set of tools to manage and compose process executions
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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

/*!
# process management

this module provides some wrapping around the standard library's
`std::process::Command` and `std::process::Child` and associated
types.

Here we provide an opinionated API where we capture standard inputs
and outputs by default. The errors are also wrapped to provide better
understanding of what did fail (especially the PID or the command line).

There are a couple of items to keep in mind when utilising this API:

* as soon as [`Process`] is _dropped_ the associated process will be terminated;
* [`Process`] captures _Stdout_ and _Stderr_, if you don't read the standard output it won't
  be visible on your terminal;
* [`Process`] control _Stdin_ too
* the API utilizes the `Future` framework. If you don't push it in a runtime or call
  `wait` the functions will do nothing.

# the `Program`

[`Program`] is an object that guarantees (within reason) the existence of a
program within the execution environment. When constructing, the [`Program`]
is checked so that once created it is known if it exists and if it has
appropriate execution rights.

```
# use bawawa::{Program, Error};
#
let rustc = Program::new("rustc".to_owned())?;
# Ok::<(), Error>(())
```

# the `Command`

this is the command line, the [`Program`], the parameters and the associated
environment variables necessary to spawn a new [`Process`].

```
# use bawawa::{Command, Program, Error};
#
# let rustc = Program::new("rustc".to_owned())?;
let mut get_rustc_version = Command::new(rustc);
get_rustc_version.arguments(&["--version"]);

println!("{}", get_rustc_version);
# Ok::<(), Error>(())
```

# spawn a `Process`

Once the [`Command`] is ready with the appropriate parameter it is possible
to _spawn_ a [`Process`]. The trait [`Control`] allows to follow the life
cycle of the spawned [`Process`].

```
# use bawawa::{Command, Control, Process, Program, Error};
#
# let rustc = Program::new("rustc".to_owned())?;
# let mut get_rustc_version = Command::new(rustc);
# get_rustc_version.arguments(&["--version"]);
let process = Process::spawn(get_rustc_version)?;

println!("spawned command: '{}' (PID: {})", process.command(), process.id());
# Ok::<(), Error>(())
```

We provide functions to capture the standard output and standard error output
utilising the [`StandardOutput::capture_stdout`] or [`StandardError::capture_stderr`]
and to send items to the standard inputs with [`StandardInput::send_stdin`].

```
# use bawawa::{Command, Control, StandardOutput, Process, Program, Error};
# use futures::Stream as _;
#
# let rustc = Program::new("rustc".to_owned())?;
# let mut get_rustc_version = Command::new(rustc);
# get_rustc_version.arguments(&["--version"]);
# let process = Process::spawn(get_rustc_version)?;

let mut capture_stdout = process
    .capture_stdout(
        // specify the codec, the way to decode data
        // from the captured output. Here we read line
        // by line.
        tokio_codec::LinesCodec::new()
    )
    .wait(); // from the _futures_ crate's Stream trait

println!("compiler: {}", capture_stdout.next().unwrap()?);
// compiler: rustc 1.35.0 (3c235d560 2019-05-20)
# Ok::<(), Error>(())
```

[`Process`]: ./struct.Process.html
[`Program`]: ./struct.Program.html
[`Command`]: ./struct.Command.html
[`Control`]: ./trait.Control.html
[`StandardOutput::capture_stdout`]: ./trait.StandardOutput.html#method.capture_stdout
[`StandardError::capture_stderr`]: ./trait.StandardError.html#method.capture_stderr
[`StandardInput::send_stdin`]: ./trait.StandardInput.html#method.send_stdin
*/

#[macro_use(error_chain)]
extern crate error_chain;

mod capture;
mod command;
mod control;
mod process;
mod program;
mod send_stdin;

pub use self::capture::Capture;
pub use self::command::Command;
pub use self::control::*;
pub use self::process::Process;
pub use self::program::Program;
pub use self::send_stdin::SendStdin;

error_chain! {
    foreign_links {
        Io(::std::io::Error);
    }

    errors {
        InvalidProgramName(p: Program) {
            description("invalid program name")
            display("invalid program name: '{}'", p)
        }

        CannotSpawnCommand(c: Command) {
            description("cannot spawn command")
            display("cannot spawn command: '{}'", c)
        }

        CannotKillProcess(c: Command, id: u32) {
            description("cannot kill process")
            display("cannot kill process '{}' ({})", id, c)
        }

        Poll(c: Command) {
            description("error while waiting for command to finish")
            display("Error while waiting for command to finish: {}", c)
        }

        Capture {
            description("error in `capture`")
        }

        SendStdin {
            description("error in `send_stdin`")
        }
    }
}