src/doc/style/errors/ergonomics.md

   1 % Ergonomic error handling
   2
   3 Error propagation with raw `Result`s can require tedious matching and
   4 repackaging. This tedium is largely alleviated by the `try!` macro,
   5 and can be completely removed (in some cases) by the "`Result`-`impl`"
   6 pattern.
   7
   8 ### The `try!` macro
   9
  10 Prefer
  11
  12 ```rust,ignore
  13 use std::io::{File, Open, Write, IoError};
  14
  15 struct Info {
  16     name: String,
  17     age: i32,
  18     rating: i32
  19 }
  20
  21 fn write_info(info: &Info) -> Result<(), IoError> {
  22     let mut file = File::open_mode(&Path::new("my_best_friends.txt"),
  23                                    Open, Write);
  24     // Early return on error
  25     try!(file.write_line(&format!("name: {}", info.name)));
  26     try!(file.write_line(&format!("age: {}", info.age)));
  27     try!(file.write_line(&format!("rating: {}", info.rating)));
  28     return Ok(());
  29 }
  30 ```
  31
  32 over
  33
  34 ```rust,ignore
  35 use std::io::{File, Open, Write, IoError};
  36
  37 struct Info {
  38     name: String,
  39     age: i32,
  40     rating: i32
  41 }
  42
  43 fn write_info(info: &Info) -> Result<(), IoError> {
  44     let mut file = File::open_mode(&Path::new("my_best_friends.txt"),
  45                                    Open, Write);
  46     // Early return on error
  47     match file.write_line(&format!("name: {}", info.name)) {
  48         Ok(_) => (),
  49         Err(e) => return Err(e)
  50     }
  51     match file.write_line(&format!("age: {}", info.age)) {
  52         Ok(_) => (),
  53         Err(e) => return Err(e)
  54     }
  55     return file.write_line(&format!("rating: {}", info.rating));
  56 }
  57 ```
  58
  59 See
  60 [the `result` module documentation](https://doc.rust-lang.org/stable/std/result/index.html#the-try-macro)
  61 for more details.
  62
  63 ### The `Result`-`impl` pattern [FIXME]
  64
  65 > **[FIXME]** Document the way that the `io` module uses trait impls
  66 > on `std::io::Result` to painlessly propagate errors.