nobug 0.7.0

#[allow(unused_imports)]
use crate::*;

/// Annotate a bug that must be fixed.
///
/// * Not permitted in release mode. Will yield a `compile_error!`.
///
/// This macro can be used in 2 forms:
/// 1. With a code block and optional formatstring and arguments.
///    * Will print the message once.
///    * Asserts that the code block returns true.
/// 2. Only with formatstring and optional arguments.
///    * Will abort the program with the message.
///
/// The first form allows to add testing snippets to code under development while being able
/// to run tests as long the bug is not triggered.
///
/// # Examples
///
/// ```rust
/// # if false { use nobug::*;
/// FIXME!({true} "this is a bug when the code block returns false");
/// FIXME!("here is a bug");
/// # }
/// ```
#[macro_export]
macro_rules! FIXME{
    ({$($code:tt)*} $($fmt:literal $(, $($args:tt),*)? $(,)?)?) => {{
        $crate::TRACE_NOBUG!(($($fmt)*) $(,$($args),*)?);
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                $crate::ASSERT!({$($code)*}, ("FIXME: " $(, $fmt)?) $($(, $($args),*)?)?);
                $crate::NOTICE_ONCE!(("FIXME: " $(, $fmt)?) $($(, $($args),*)?)?);
            } else {
                compile_error!(concat!("FIXME: " $(, $fmt)?) $($(, $($args),*)?)?);
            }
        }
    }};
    ($fmt:literal $(, $($args:tt),*)? $(,)?) => {{
        $crate::TRACE_NOBUG!($fmt $(,$($args),*)?);
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                $crate::DIE!(("FIXME: ", $fmt) $(, $($args),*)?);
            } else {
                compile_error!(concat!("FIXME: ", $fmt) $(, $($args),*)?);
            }
        }
    }};
}

#[test]
#[cfg(debug_assertions)]
#[should_panic = "FIXME:"]
fn test_fixme() {
    FIXME!("this is a bug");
}

#[test]
#[cfg(debug_assertions)]
#[should_panic = "FIXME:"]
fn test_fixme2() {
    fn fm() -> i32 {
        FIXME!("this is a bug")
    }

    fm();
}

#[test]
#[cfg(debug_assertions)]
fn test_fixme_codeblock() {
    FIXME!({ true });
    FIXME!({true} "this is ok");
}

#[test]
#[cfg(debug_assertions)]
#[should_panic = "FIXME:"]
fn test_fixme_codeblock_fail() {
    FIXME!({false} "this is a bug again");
}

/// Annotate fixed bugs.
///
/// This is a drop in replacement for [`FIXME!`]. Once a bug has been fixed it can be tagged
/// as `FIXED!` and committed for documentation purposes and checking that the problem will
/// not regress again. Bugs should be accompanies with a test that verifies the bug and
/// protects against regressions. For simple things or a limited time this can be done with
/// the [`FIXED!`] macro. Eventually a proper test should be moved over into the test suite.
///
/// This macro can be used in 2 forms:
/// 1. With a code block and optional formatstring and arguments.
///    * in release builds it becomes optimized out
///    * In debug builds the correctness is asserted.
/// 2. Only with formatstring and optional arguments.
///    * Will be completely optimized out.
///
/// # Examples
///
/// ```rust
/// # use nobug::*; nobug::CFG_IF! { if #[cfg(debug_assertions)] { if false {
/// FIXED!({true} "hopefully fixed bug");
/// FIXED!("no bug");
/// # }}}
/// ```
#[macro_export]
macro_rules! FIXED{
    ({$($code:tt)*} $($fmt:literal $(, $($args:tt),*)? $(,)?)?) => {{
        $crate::TRACE_NOBUG!($($fmt $(,$($args),*)?)?);
         $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                $crate::ASSERT!({$($code)*}, ("REGRESSION: " $(, $fmt)?) $($(, $($args),*)?)?)
            } else if #[cfg(not(feature = "completed_in_release"))] {
                compile_error!("FIXED: forbidden in release")
            }
        }
    }};
    ($fmt:literal $(, $($args:tt),*)? $(,)?) => {
         $crate::CFG_IF! {
             if #[cfg(not(any(debug_assertions, feature = "completed_in_release")))] {
                compile_error!("FIXED: forbidden in release")
            }
        }
    };
}

#[test]
fn test_fixed() {
    FIXED!({true} "no bug");
}

#[test]
#[cfg(debug_assertions)]
#[should_panic = "REGRESSION:"]
fn test_fixed_fail() {
    FIXED!({false} "this is a bug again");
}

/// Annotate incomplete but required code.
///
/// Takes a optional literal string that describes the missing code.
/// TODO's are strict about missing functionality. When things are optional then [`PLANNED!`]
/// or [`IDEA!`] should be used.
///
/// * Not permitted in release mode. Will yield a `compile_error!`.
/// * Will abort in debug mode.
///
/// # Examples
///
/// ```rust
/// # use nobug::*;
/// # if false {
/// TODO!("not yet done");
/// TODO!();
/// # }
/// ```
#[macro_export]
macro_rules! TODO {
    ($text:literal) => {{
        $crate::TRACE_NOBUG!($text);
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                $crate::DIE!("TODO: {}", $text)
            } else {
                compile_error!(concat!("TODO: ",$text))
            }
        }
    }};
    () => {{
        $crate::TRACE_NOBUG!();
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                $crate::DIE!("TODO")
            } else {
                compile_error!("TODO")
            }
        }
    }};
}

#[test]
#[cfg(debug_assertions)]
#[should_panic = "TODO:"]
fn test_todo() {
    TODO!("message");
}

#[test]
#[cfg(debug_assertions)]
#[should_panic = "TODO"]
fn test_todo_nomsg() {
    TODO!();
}

/// Annotate code which is work in progress.
///
/// This macro can be used in 2 forms:
/// 1. With a code block and optional message.
///    * Not permitted in release mode. Will yield a `compile_error!`.
///    * In debug builds a message is printed when the code block returns `false`.
/// 2. Only with a message.
///    * Not permitted in release mode. Will yield a `compile_error!`.
///    * Will print the message in debug mode.
///
/// By nature work-in-progress code may have missing or incorrect parts, thus this
/// macro is forbidden in release mode. Still it won't abort the program to be able
/// to run tests while working on the code.
///
/// # Examples
///
/// ```rust
/// # if false { use nobug::*;
/// WIP!({true} "this is a work in progress");
/// WIP!("this is a work in progress");
/// WIP!();
/// # }
#[macro_export]
macro_rules! WIP {
    ({$($code:tt)*} $text:literal) => {{
        $crate::TRACE_NOBUG!($text);
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                if !{$($code)*} {
                    $crate::NOTICE!(
                        ("WIP: {}: {{{}}}"),
                        $text,
                        stringify!($($code)*)
                    )
                } else {
                    $crate::NOTICE!(
                        ("WIP DONE: {}: {{{}}}"),
                        $text,
                        stringify!($($code)*)
                    )
                }
            } else {
                compile_error!(concat!("WIP:", $text))
            }
        }
    }};
    ({$($code:tt)*}) => {{
        $crate::TRACE_NOBUG!();
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                if !{$($code)*} {
                    $crate::NOTICE!(
                        ("WIP: {{{}}}"),
                        stringify!($($code)*)
                    )
                } else {
                    $crate::NOTICE!(
                        ("WIP DONE: {{{}}}"),
                        stringify!($($code)*)
                    )
                }
            } else {
                compile_error!(concat!("WIP"))
            }
        }
    }};
    ($text:literal) => {{
        $crate::TRACE_NOBUG!($text);
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                $crate::NOTICE_ONCE!("WIP: {}", $text)
            } else {
                compile_error!(concat!("WIP: ", $text))
            }
        }
    }};
    () => {{
        $crate::TRACE_NOBUG!();
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                $crate::NOTICE!("WIP")
            } else {
                compile_error!("WIP")
            }
        }
    }};
}

#[cfg(debug_assertions)]
#[test]
fn test_wip_only_text() {
    WIP!("only text");
    WIP!(); // No text
}

#[cfg(debug_assertions)]
#[test]
fn test_wip_with_code() {
    WIP!({false} "some idea");
    WIP!({ false });
    WIP!({true} "some idea");
    WIP!({ true });
}

/// Annotate code which is done.
///
/// The main purpose for this macro is to have a transition from [`TODO!`] or [`WIP!`]
/// to [`DONE!`].
///
/// This macro can be used in 2 forms and is controlled by the `completed_in_release` feature.
/// 1. With a code block and optional message.
///    * Asserts the that the code block returns `true` in debug builds.
///    * Either optimized out in release mode or a compile error when `completed_in_release` is disabled.
/// 2. Only with a message.
///    * Either optimized out in release mode or a compile error when `completed_in_release` is disabled.
///
/// # Example
///
/// ```rust
/// # if false { use nobug::*;
/// DONE!({true} "this is done");
/// DONE!("this is done");
/// # }
/// ```
#[macro_export]
macro_rules! DONE {
    ({$($code:tt)*} $text:literal) => {
        $crate::TRACE_NOBUG!($text);
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                $crate::ASSERT!({$($code)*}, "DONE REGRESSION: {}", $text)
            } else if #[cfg(not(feature = "completed_in_release"))] {
                compile_error!("DONE: forbidden in release")
            }
        }
    };
    ({$($code:tt)*}) => {
        $crate::TRACE_NOBUG!();
        $crate::CFG_IF! {
            if #[cfg(debug_assertions)] {
                $crate::ASSERT!({$($code)*}, "DONE REGRESSION")
            } else if #[cfg(not(feature = "completed_in_release"))] {
                compile_error!("DONE: forbidden in release")
            }
        }
    };
    ($text:literal) => {
        $crate::CFG_IF! {
            if #[cfg(not(any(debug_assertions, feature = "completed_in_release")))] {
                compile_error!("DONE: forbidden in release")
            }
        }
    };
}

#[test]
fn test_done_with_code() {
    DONE!({true} "this works");
    DONE!({ true });
}

#[test]
#[allow(clippy::missing_const_for_fn)]
fn test_done_textonly() {
    DONE!("this works");
}

#[test]
#[cfg(debug_assertions)]
#[should_panic = "DONE REGRESSION:"]
fn test_done_with_code_fail() {
    DONE!({false} "this doesn't");
}

#[test]
#[cfg(debug_assertions)]
#[should_panic = "DONE REGRESSION"]
fn test_done_code_only_fail() {
    DONE!({ false });
}

/// Annotate a not required improvement of existing code.
///
/// Optimized out in release mode.
/// Prints a message once in debug mode.
///
/// # Example
///
/// ```rust
/// # use nobug::*;
/// # if false {
/// IDEA!("this is a good idea");
/// # }
#[macro_export]
macro_rules! IDEA {
    ($text:literal) => {{
        $crate::TRACE_NOBUG!($text);
        #[cfg(debug_assertions)]
        $crate::NOTICE_ONCE!(("IDEA: ", $text));
    }};
}

#[test]
fn test_idea() {
    IDEA!("message");
}

/// Annotate a potentially planned feature.
///
/// Optimized out in release mode.
/// Prints a message once in debug mode.
///
/// This can be considered a lesser form of `TODO!` where the feature is not required but
/// might be implemented in the future.
///
/// # Example
///
/// ```rust
/// # use nobug::*;
/// # if false {
/// PLANNED!("this is a planned feature");
/// # }
/// ```
#[macro_export]
macro_rules! PLANNED {
    ($text:literal) => {{
        $crate::TRACE_NOBUG!($text);
        #[cfg(debug_assertions)]
        $crate::NOTICE_ONCE!(("PLANNED: ", $text));
    }};
}