diff --git a/src/macros.rs b/src/macros.rs index 08df41d..9677179 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -1,4 +1,23 @@ -/// Unwrap a Result, and log the error. +/// Unwrap a Result. If it's Err then log the error and provided format string +/// and return. +/// +/// # Arguments +/// +/// * `$e:expr` : Expression to evaluate, must return `Result>` +/// * `$($arg:tt)*` : Format string and parameters (like `println!()`) +/// +/// # Example +/// +/// ``` +/// use std::fs::File; +/// use rude::result::RudeResult; +/// use rude::try_log; +/// +/// fn main() -> RudeResult<()> { +/// let file = try_log!(File::open(file!()), "Unable to open {}", file!()); +/// Ok(()) +/// } +/// ``` #[macro_export] macro_rules! try_log { ($e:expr, $($arg:tt)*) => { @@ -13,7 +32,26 @@ macro_rules! try_log { }; } -/// Unwrap a Result and print if it's an error +/// Unwrap a Result. If it's Err then print the error and provided format string +/// and return. +/// +/// # Arguments +/// +/// * `$e:expr` : Expression to evaluate, must return `Result>` +/// * `$($arg:tt)*` : Format string and parameters (like `println!()`) +/// +/// # Example +/// +/// ``` +/// use std::fs::File; +/// use rude::result::RudeResult; +/// use rude::try_print; +/// +/// fn main() -> RudeResult<()> { +/// let file = try_print!(File::open(file!()), "Unable to open {}", file!()); +/// Ok(()) +/// } +/// ``` #[macro_export] macro_rules! try_print { ($e:expr, $($arg:tt)*) => { @@ -28,7 +66,30 @@ macro_rules! try_print { }; } -/// Unwrap a `Result`, if it's an error then let client know and return. +/// Unwrap a Result. If it's Err then print the error and return a generic +/// error message for the client. +/// +/// # Arguments +/// +/// * `$i:ident` : mio::Token to designate the client +/// * `$e:expr` : Expression to evaluate, must return `Result>` +/// +/// # Example +/// +/// ``` +/// use std::fs::File; +/// use mio::Token; +/// use rude::queue::SendQueue; +/// use rude::try_send_error; +/// +/// fn check_file() -> SendQueue { +/// let token = Token(12); +/// let file = try_send_error!(token, File::open(file!())); +/// SendQueue::ok(token) +/// } +/// +/// # assert_eq!(check_file().0[0].1, SendQueue::ok(Token(12)).0[0].1); +/// ``` #[macro_export] macro_rules! try_send_error { ($i:ident, $e:expr) => { @@ -41,39 +102,113 @@ macro_rules! try_send_error { line!(), e ); - return SendQueue::error($i); + return $crate::queue::SendQueue::error($i); } } }; } -/// Unwrap a `Result`, send a message if it's E. +/// Unwrap a `Result` and return a custom message to send to the client for Err. +/// +/// # Arguments +/// +/// * `$i:ident` : `mio::Token` client identifier +/// * `$e:expr` : Expression to evaluate, must return `Result>` +/// * `$($arg:tt)*` : Format string and parameters (like `println!()`) +/// +/// # Example +/// +/// ``` +/// use std::fs::File; +/// use mio::Token; +/// use rude::queue::SendQueue; +/// use rude::try_send; +/// +/// fn check_file() -> SendQueue { +/// let token = Token(12); +/// let file = try_send!(token, File::open(file!()), "Unable to open {}", file!()); +/// SendQueue::ok(token) +/// } +/// +/// # assert_eq!(check_file().0[0].1, SendQueue::ok(Token(12)).0[0].1); +/// ``` #[macro_export] macro_rules! try_send { ($i:ident, $e:expr, $($arg:tt)*) => { match $e { Ok(r) => r, Err(_e) => { - return SendQueue(vec![($i, std::fmt::format(format_args!($($arg)*)), true)].into()); - } + return $crate::queue::SendQueue( + vec![($i, std::fmt::format(format_args!($($arg)*)), true)].into() + ); } + } }; } -/// Unwrap a `Option`, send a message if it's None. +/// Unarap an `Option` and return a custom message for the client if it is None. +/// +/// # Arguments +/// +/// * `$i:ident` : `mio::Token` client identifier +/// * `$e:expr` : Expression to evaluate, must return `Option` +/// * `$($arg:tt)*` : Format string and parameters (like `println!()`) +/// +/// # Example +/// +/// ``` +/// use mio::Token; +/// use rude::queue::SendQueue; +/// use rude::option_send; +/// +/// fn check_file() -> SendQueue { +/// let token = Token(12); +/// let option = Some(4); +/// let send = option_send!(token, option, "Option unwrapped to None"); +/// SendQueue::ok(token) +/// } +/// +/// # assert_eq!(check_file().0[0].1, SendQueue::ok(Token(12)).0[0].1); +/// ``` #[macro_export] macro_rules! option_send { ($i:ident, $e:expr, $($arg:tt)*) => { match $e { Some(r) => r, None => { - return SendQueue(vec![($i, std::fmt::format(format_args!($($arg)*)), true)].into()); - } + return $crate::queue::SendQueue( + vec![($i, std::fmt::format(format_args!($($arg)*)), true)].into() + ); } + } }; } -/// Unwrap a `Result, E>`, log message if it's error or none +/// Unwrap a `Result, E>` and for Err or None, log a message and send +/// a generic error message to the client. +/// +/// # Arguments +/// +/// * `$i:ident` : `mio::Token` client identifier +/// * `$e:expr` : Expression to evaluate, must return `Result>` +/// +/// # Example +/// +/// ``` +/// use std::error::Error; +/// use mio::Token; +/// use rude::queue::SendQueue; +/// use rude::try_option_send_error; +/// +/// fn tor() -> SendQueue { +/// let token = Token(12); +/// let tor: Result, Box> = Ok(Some(42)); +/// let file = try_option_send_error!(token, tor); +/// SendQueue::ok(token) +/// } +/// +/// # assert_eq!(tor().0[0].1, SendQueue::ok(Token(12)).0[0].1); +/// ``` #[macro_export] macro_rules! try_option_send_error { ($i:ident, $e:expr) => { @@ -85,7 +220,7 @@ macro_rules! try_option_send_error { file!(), line!() ); - return SendQueue::error($i); + return $crate::queue::SendQueue::error($i); } Err(e) => { log::error!( @@ -94,19 +229,8 @@ macro_rules! try_option_send_error { line!(), e ); - return SendQueue::error($i); + return $crate::queue::SendQueue::error($i); } } }; } - -// #[macro_export] -// macro_rules! try_option_send_error { -// ($i:ident, $e:expr) => { -// if let Ok(Some(r)) = $e { -// r -// } else { -// return SendQueue::error($i); -// } -// }; -// }