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};