metadata0.1.0

1 files changed, 55 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9770430
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+# tokio-pty-process-stream
+
+This crate wraps `tokio-pty-process` in order to provide a simpler API as
+a single stream object.
+
+## Overview
+
+When you need to interact with an interactive program as part of an
+asynchronous application, it can be tricky to figure out the way to
+structure the different parts that are required. This crate simplifies the
+API down to just providing the input via an `AsyncRead` object, and then
+getting updates about what the program is doing via results generated by a
+stream.
+
+## Synopsis
+
+This is an example of how to run an interactive program and have it behave
+identically to running it in the shell. Note that we have to use our own
+`Stdin` implementation here because `tokio::io::stdin()` is actually
+blocking, and so polling it as part of an interactive application doesn't
+work correctly. The implementation of `Stdin` is elided here, but you can
+see the full implementation in `examples/shell.rs` in the repository.
+
+```rust
+let mut argv = std::env::args();
+argv.next().unwrap();
+let cmd = argv.next().unwrap();
+let args: Vec<_> = argv.collect();
+
+let process =
+    tokio_pty_process_stream::Process::new(&cmd, &args, Stdin::new());
+
+let _raw = crossterm::RawScreen::into_raw_mode().unwrap();
+tokio::run(
+    process
+        .for_each(|ev| {
+            match ev {
+                tokio_pty_process_stream::Event::CommandStart {
+                    ..
+                } => {}
+                tokio_pty_process_stream::Event::Output { data } => {
+                    let stdout = std::io::stdout();
+                    let mut stdout = stdout.lock();
+                    stdout.write_all(&data).unwrap();
+                    stdout.flush().unwrap();
+                }
+                tokio_pty_process_stream::Event::CommandExit {
+                    ..
+                } => {}
+            }
+            futures::future::ok(())
+        })
+        .map_err(|e| panic!(e)),
+);
+```