From 6815c2e8e8dae3d8dedfe95e985a79c57841bdb2 Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Fri, 3 Oct 2014 14:23:09 -0700 Subject: [PATCH 1/3] Add error module with Error and FromError traits As per [RFC 70](https://github.com/rust-lang/rfcs/blob/master/active/0070-error-chaining.md) Closes #17747 Note that the `error` module must live in `std` in order to refer to `String`. Note that, until multidispatch lands, the `FromError` trait cannot be usefully implemented outside of the blanket impl given here. --- src/libcore/prelude.rs | 4 +- src/libstd/error.rs | 111 +++++++++++++++++++++++++++++++++++++++++ src/libstd/lib.rs | 2 + src/libstd/macros.rs | 9 +++- src/libstd/prelude.rs | 4 +- 5 files changed, 124 insertions(+), 6 deletions(-) create mode 100644 src/libstd/error.rs diff --git a/src/libcore/prelude.rs b/src/libcore/prelude.rs index 64917fb2541b9..0d4979a357512 100644 --- a/src/libcore/prelude.rs +++ b/src/libcore/prelude.rs @@ -37,8 +37,6 @@ pub use ops::{Shl, Shr}; pub use ops::{Index, IndexMut}; pub use ops::{Slice, SliceMut}; pub use ops::{Fn, FnMut, FnOnce}; -pub use option::{Option, Some, None}; -pub use result::{Result, Ok, Err}; // Reexported functions pub use iter::range; @@ -56,7 +54,9 @@ pub use iter::{OrdIterator, MutableDoubleEndedIterator, ExactSize}; pub use num::{Num, NumCast, CheckedAdd, CheckedSub, CheckedMul}; pub use num::{Signed, Unsigned, Float}; pub use num::{Primitive, Int, ToPrimitive, FromPrimitive}; +pub use option::{Option, Some, None}; pub use ptr::RawPtr; +pub use result::{Result, Ok, Err}; pub use str::{Str, StrSlice}; pub use tuple::{Tuple1, Tuple2, Tuple3, Tuple4}; pub use tuple::{Tuple5, Tuple6, Tuple7, Tuple8}; diff --git a/src/libstd/error.rs b/src/libstd/error.rs new file mode 100644 index 0000000000000..6bb9f4b473bc1 --- /dev/null +++ b/src/libstd/error.rs @@ -0,0 +1,111 @@ +// Copyright 2014 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +//! Traits for working with Errors. +//! +//! # The `Error` trait +//! +//! `Error` is a trait representing the basic expectations for error values, +//! i.e. values of type `E` in `Result`. At a minimum, errors must provide +//! a description, but they may optionally provide additional detail and cause +//! chain information: +//! +//! ``` +//! trait Error: Send { +//! fn description(&self) -> &str; +//! +//! fn detail(&self) -> Option { None } +//! fn cause(&self) -> Option<&Error> { None } +//! } +//! ``` +//! +//! The `cause` method is generally used when errors cross "abstraction +//! boundaries", i.e. when a one module must report an error that is "caused" +//! by an error from a lower-level module. This setup makes it possible for the +//! high-level module to provide its own errors that do not commit to any +//! particular implementation, but also reveal some of its implementation for +//! debugging via `cause` chains. +//! +//! The trait inherits from `Any` to allow *downcasting*: converting from a +//! trait object to a specific concrete type when applicable. +//! +//! # The `FromError` trait +//! +//! `FromError` is a simple trait that expresses conversions between different +//! error types. To provide maximum flexibility, it does not require either of +//! the types to actually implement the `Error` trait, although this will be the +//! common case. +//! +//! The main use of this trait is in the `try!` macro, which uses it to +//! automatically convert a given error to the error specified in a function's +//! return type. +//! +//! For example, +//! +//! ``` +//! use std::error::FromError; +//! use std::io::{File, IoError}; +//! use std::os::{MemoryMap, MapError}; +//! use std::path::Path; +//! +//! enum MyError { +//! Io(IoError), +//! Map(MapError) +//! } +//! +//! impl FromError for MyError { +//! fn from_error(err: IoError) -> MyError { +//! Io(err) +//! } +//! } +//! +//! impl FromError for MyError { +//! fn from_error(err: MapError) -> MyError { +//! Map(err) +//! } +//! } +//! +//! #[allow(unused_variables)] +//! fn open_and_map() -> Result<(), MyError> { +//! let f = try!(File::open(&Path::new("foo.txt"))); +//! let m = try!(MemoryMap::new(0, &[])); +//! // do something interesting here... +//! Ok(()) +//! } +//! ``` + +use option::{Option, None}; +use kinds::Send; +use string::String; + +/// Base functionality for all errors in Rust. +pub trait Error: Send { + /// A short description of the error; usually a static string. + fn description(&self) -> &str; + + /// A detailed description of the error, usually including dynamic information. + fn detail(&self) -> Option { None } + + /// The lower-level cause of this error, if any. + fn cause(&self) -> Option<&Error> { None } +} + +/// A trait for types that can be converted from a given error type `E`. +pub trait FromError { + /// Perform the conversion. + fn from_error(err: E) -> Self; +} + +// Any type is convertable from itself +impl FromError for E { + fn from_error(err: E) -> E { + err + } +} diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 67080f4551f06..f10a1d5e5edc7 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -218,6 +218,7 @@ pub mod time; /* Common traits */ +pub mod error; pub mod from_str; pub mod num; pub mod to_string; @@ -257,6 +258,7 @@ mod std { pub use hash; pub use comm; // used for select!() + pub use error; // used for try!() pub use fmt; // used for any formatting strings pub use io; // used for println!() pub use local_data; // used for local_data_key!() diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 0712719dd042d..55e364b1961a2 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -317,8 +317,13 @@ macro_rules! local_data_key( /// error if the value of the expression is `Err`. For more information, see /// `std::io`. #[macro_export] -macro_rules! try( - ($e:expr) => (match $e { Ok(e) => e, Err(e) => return Err(e) }) +macro_rules! try ( + ($expr:expr) => ({ + match $expr { + Ok(val) => val, + Err(err) => return Err(::std::error::FromError::from_error(err)) + } + }) ) /// Create a `std::vec::Vec` containing the arguments. diff --git a/src/libstd/prelude.rs b/src/libstd/prelude.rs index b2ff29c0f7eef..47befb2286bde 100644 --- a/src/libstd/prelude.rs +++ b/src/libstd/prelude.rs @@ -48,8 +48,6 @@ #[doc(no_inline)] pub use ops::{Index, IndexMut}; #[doc(no_inline)] pub use ops::{Slice, SliceMut}; #[doc(no_inline)] pub use ops::{Fn, FnMut, FnOnce}; -#[doc(no_inline)] pub use option::{Option, Some, None}; -#[doc(no_inline)] pub use result::{Result, Ok, Err}; // Reexported functions #[doc(no_inline)] pub use from_str::from_str; @@ -73,8 +71,10 @@ #[doc(no_inline)] pub use num::{Signed, Unsigned, Primitive, Int, Float}; #[doc(no_inline)] pub use num::{FloatMath, ToPrimitive, FromPrimitive}; #[doc(no_inline)] pub use boxed::Box; +#[doc(no_inline)] pub use option::{Option, Some, None}; #[doc(no_inline)] pub use path::{GenericPath, Path, PosixPath, WindowsPath}; #[doc(no_inline)] pub use ptr::{RawPtr, RawMutPtr}; +#[doc(no_inline)] pub use result::{Result, Ok, Err}; #[doc(no_inline)] pub use io::{Buffer, Writer, Reader, Seek}; #[doc(no_inline)] pub use str::{Str, StrVector, StrSlice}; #[doc(no_inline)] pub use str::{IntoMaybeOwned, StrAllocating, UnicodeStrSlice}; From 7c152f870da62348ec5a0d9104c20db69910a415 Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Fri, 3 Oct 2014 14:24:49 -0700 Subject: [PATCH 2/3] Add Error impls to a few key error types --- src/libserialize/base64.rs | 14 ++++++++++++++ src/libserialize/hex.rs | 15 +++++++++++++++ src/libserialize/json.rs | 5 +++++ src/libstd/io/mod.rs | 18 ++++++++++++++++++ src/libstd/os.rs | 14 ++++++++++++++ 5 files changed, 66 insertions(+) diff --git a/src/libserialize/base64.rs b/src/libserialize/base64.rs index c999157b89a8f..e69a0ea7929cb 100644 --- a/src/libserialize/base64.rs +++ b/src/libserialize/base64.rs @@ -13,6 +13,7 @@ //! Base64 binary-to-text encoding use std::fmt; use std::string; +use std::error; /// Available encoding character sets pub enum CharacterSet { @@ -178,6 +179,19 @@ impl fmt::Show for FromBase64Error { } } +impl error::Error for FromBase64Error { + fn description(&self) -> &str { + match *self { + InvalidBase64Byte(_, _) => "invalid character", + InvalidBase64Length => "invalid length", + } + } + + fn detail(&self) -> Option { + Some(self.to_string()) + } +} + impl<'a> FromBase64 for &'a str { /** * Convert any base64 encoded string (literal, `@`, `&`, or `~`) diff --git a/src/libserialize/hex.rs b/src/libserialize/hex.rs index ffe63f738cf97..b591d35c67c09 100644 --- a/src/libserialize/hex.rs +++ b/src/libserialize/hex.rs @@ -13,6 +13,7 @@ //! Hex binary-to-text encoding use std::fmt; use std::string; +use std::error; /// A trait for converting a value to hexadecimal encoding pub trait ToHex { @@ -77,6 +78,20 @@ impl fmt::Show for FromHexError { } } +impl error::Error for FromHexError { + fn description(&self) -> &str { + match *self { + InvalidHexCharacter(_, _) => "invalid character", + InvalidHexLength => "invalid length", + } + } + + fn detail(&self) -> Option { + Some(self.to_string()) + } +} + + impl<'a> FromHex for &'a str { /** * Convert any hexadecimal encoded string (literal, `@`, `&`, or `~`) diff --git a/src/libserialize/json.rs b/src/libserialize/json.rs index 06f934c075d1a..cde2dfac37821 100644 --- a/src/libserialize/json.rs +++ b/src/libserialize/json.rs @@ -313,6 +313,11 @@ fn io_error_to_error(io: io::IoError) -> ParserError { IoError(io.kind, io.desc) } +impl std::error::Error for DecoderError { + fn description(&self) -> &str { "decoder error" } + fn detail(&self) -> Option { Some(self.to_string()) } +} + pub type EncodeResult = io::IoResult<()>; pub type DecodeResult = Result; diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index c6f237ff1da34..3dcd8d792a4d8 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -222,7 +222,9 @@ responding to errors that may occur while attempting to read the numbers. #![deny(unused_must_use)] use char::Char; +use clone::Clone; use default::Default; +use error::{FromError, Error}; use fmt; use int; use iter::Iterator; @@ -433,6 +435,22 @@ impl fmt::Show for IoError { } } +impl Error for IoError { + fn description(&self) -> &str { + self.desc + } + + fn detail(&self) -> Option { + self.detail.clone() + } +} + +impl FromError for Box { + fn from_error(err: IoError) -> Box { + box err + } +} + /// A list specifying general categories of I/O error. #[deriving(PartialEq, Eq, Clone, Show)] pub enum IoErrorKind { diff --git a/src/libstd/os.rs b/src/libstd/os.rs index 5b3c872d2b726..9846f7b653e2b 100644 --- a/src/libstd/os.rs +++ b/src/libstd/os.rs @@ -32,11 +32,13 @@ #![allow(non_snake_case)] use clone::Clone; +use error::{FromError, Error}; use fmt; use io::{IoResult, IoError}; use iter::Iterator; use libc::{c_void, c_int}; use libc; +use boxed::Box; use ops::Drop; use option::{Some, None, Option}; use os; @@ -48,6 +50,7 @@ use slice::{AsSlice, ImmutableSlice, MutableSlice, ImmutablePartialEqSlice}; use slice::CloneableVector; use str::{Str, StrSlice, StrAllocating}; use string::String; +use to_string::ToString; use sync::atomic::{AtomicInt, INIT_ATOMIC_INT, SeqCst}; use vec::Vec; @@ -1437,6 +1440,17 @@ impl fmt::Show for MapError { } } +impl Error for MapError { + fn description(&self) -> &str { "memory map error" } + fn detail(&self) -> Option { Some(self.to_string()) } +} + +impl FromError for Box { + fn from_error(err: MapError) -> Box { + box err + } +} + #[cfg(unix)] impl MemoryMap { /// Create a new mapping with the given `options`, at least `min_len` bytes From 38e0745e3f5e6c772c973c1d0b73abb0b20faba0 Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Fri, 31 Oct 2014 12:54:10 -0700 Subject: [PATCH 3/3] Add type annotation to deal with fallout --- src/librustc/driver/driver.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/librustc/driver/driver.rs b/src/librustc/driver/driver.rs index f6aab6ef47777..d3ed0dbd99eff 100644 --- a/src/librustc/driver/driver.rs +++ b/src/librustc/driver/driver.rs @@ -660,7 +660,7 @@ fn write_out_deps(sess: &Session, _ => return, }; - let result = (|| { + let result = (|| -> io::IoResult<()> { // Build a list of files used to compile the output and // write Makefile-compatible dependency rules let files: Vec = sess.codemap().files.borrow()