Document behavior of read_line with respect to reported signals

murarth · Jun 27, 2018 · 2965083 · 2965083
1 parent 923498d
commit 2965083
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 17 deletions.
diff --git a/examples/signals.rs b/examples/signals.rs
@@ -77,12 +77,15 @@ fn main() -> io::Result<()> {
                             }
                         }
                     }
-                    _ => ()
+                    _ => println!("read input: {:?}", line)
                 }
             }
             ReadResult::Signal(sig) => {
-                println!();
-                println!("signal received: {:?}", sig);
+                if sig == Signal::Interrupt {
+                    interface.cancel_read_line()?;
+                }
+
+                let _ = writeln!(interface, "signal received: {:?}", sig);
             }
         }
     }

diff --git a/src/interface.rs b/src/interface.rs
@@ -141,15 +141,18 @@ impl<Term: Terminal> Interface<Term> {
 impl<Term: Terminal> Interface<Term> {
     /// Interactively reads a line from the terminal device.
     ///
-    /// If the user issues an end-of-file, `ReadResult::Eof` is returned.
+    /// User input is collected until one of the following conditions is met:
     ///
-    /// If a reported signal (see [`set_report_signal`]) is received,
-    /// it is returned as `ReadResult::Signal(_)`.
-    ///
-    /// Otherwise, user input is collected until a newline is entered.
-    /// The resulting input (not containing a trailing newline character)
-    /// is returned as `ReadResult::Input(_)`.
+    /// * If the user issues an end-of-file, `ReadResult::Eof` is returned.
+    /// * When the user inputs a newline (`'\n'`), the resulting input
+    ///   (not containing a trailing newline character) is returned as
+    ///   `ReadResult::Input(_)`.
+    /// * When a reported signal (see [`set_report_signal`]) is received,
+    ///   it is returned as `ReadResult::Signal(_)`. The `read_line` operation may
+    ///   then be either resumed with another call to `read_line` or ended by
+    ///   calling [`cancel_read_line`].
     ///
+    /// [`cancel_read_line`]: #method.cancel_read_line
     /// [`set_report_signal`]: #method.set_report_signal
     pub fn read_line(&self) -> io::Result<ReadResult> {
         self.lock_reader().read_line()

diff --git a/src/reader.rs b/src/reader.rs
@@ -139,15 +139,18 @@ impl<'a, Term: 'a + Terminal> Reader<'a, Term> {
 
     /// Interactively reads a line from the terminal device.
     ///
-    /// If the user issues an end-of-file, `ReadResult::Eof` is returned.
+    /// User input is collected until one of the following conditions is met:
     ///
-    /// If a reported signal (see [`set_report_signal`]) is received,
-    /// it is returned as `ReadResult::Signal(_)`.
-    ///
-    /// Otherwise, user input is collected until a newline is entered.
-    /// The resulting input (not containing a trailing newline character)
-    /// is returned as `ReadResult::Input(_)`.
+    /// * If the user issues an end-of-file, `ReadResult::Eof` is returned.
+    /// * When the user inputs a newline (`'\n'`), the resulting input
+    ///   (not containing a trailing newline character) is returned as
+    ///   `ReadResult::Input(_)`.
+    /// * When a reported signal (see [`set_report_signal`]) is received,
+    ///   it is returned as `ReadResult::Signal(_)`. The `read_line` operation may
+    ///   then be either resumed with another call to `read_line` or ended by
+    ///   calling [`cancel_read_line`].
     ///
+    /// [`cancel_read_line`]: #method.cancel_read_line
     /// [`set_report_signal`]: #method.set_report_signal
     pub fn read_line(&mut self) -> io::Result<ReadResult> {
         loop {