tmp

src/lib.rs

@@ -65,24 +65,51 @@ pub fn new_handle<F>(closure: F)
 }
 */
 
-pub fn handle_read<F>(closure: F)
-    where F: FnOnce(io::Stdin) + UnwindSafe
+
+/// Utility that reads a `Vec` of bytes from standard input (stdin)
+/// and passes it to `closure`. All panics that occur within
+/// `closure` will be treated as aborts. This is done so that
+/// AFL considers a panic to be a crash.
+///
+/// # Examples
+///
+/// ```no_run
+/// extern crate afl;
+/// # struct Image;
+/// # impl Image {
+/// #     fn parse<R: ::std::io::Read>(_: R) {}
+/// # }
+///
+/// fn main() {
+///     afl::handle_read(|read| {
+///         Image::parse(read)
+///     })
+/// }
+/// ```
+pub fn handle_bytes<F>(closure: F)
+    where F: FnOnce(Vec<u8>) + UnwindSafe
 {
+    let mut input = vec![];
+    let result = io::stdin().read_to_end(&mut input);
+    if result.is_err() {
+        return;
+    }
+
     let result = panic::catch_unwind(|| {
-        closure(io::stdin());
+        closure(input);
     });
     if result.is_err() {
-        // TODO: add option to prevent this abort?
         unsafe {
             abort();
         }
     }
 }
 
 /// Utility that reads a `String` from standard input (stdin) and
-/// passes it to `closure`. All panics that occur within `closure`
-/// will be treated as aborts. This is done so that AFL considers
-/// a panic to be a crash.
+/// passes it to `closure`. If a `String` cannot be constructed from
+/// the data provided by standard input, `closure` will _not_ be
+/// called. All panics that occur within `closure` will be treated as
+/// aborts. This is done so that AFL considers a panic to be a crash.
 ///
 /// # Examples
 ///
@@ -117,19 +144,35 @@ pub fn handle_string<F>(closure: F)
     }
 }
 
-pub fn handle_bytes<F>(closure: F)
-    where F: FnOnce(Vec<u8>) + UnwindSafe
+/// Utility that passes `Stdin` to `closure` for use with functions
+/// that expect a structure that implements `Read`. All panics that
+/// occur within `closure` will be treated as aborts. This is done
+/// so that
+/// AFL considers a panic to be a crash.
+///
+/// # Examples
+///
+/// ```no_run
+/// extern crate afl;
+/// # struct Image;
+/// # impl Image {
+/// #     fn parse(_: &[u8]) {}
+/// # }
+///
+/// fn main() {
+///     afl::handle_bytes(|bytes| {
+///         Image::parse(&bytes)
+///     })
+/// }
+/// ```
+pub fn handle_read<F>(closure: F)
+    where F: FnOnce(io::Stdin) + UnwindSafe
 {
-    let mut input = vec![];
-    let result = io::stdin().read_to_end(&mut input);
-    if result.is_err() {
-        return;
-    }
-
     let result = panic::catch_unwind(|| {
-        closure(input);
+        closure(io::stdin());
     });
     if result.is_err() {
+        // TODO: add option to prevent this abort?
         unsafe {
             abort();
         }