shaddup/
lib.rs

1//! # `shaddup`!
2//!
3//! This library prevents your program from printing to stdout and stderr
4//! by using platform-specific utilities to redirect them to /dev/null (or equivalent).
5//!
6//! By default, this will cause a compile-error if the platform is not supported,
7//! because we don't know how to perform the redirection.
8//! If you'd like the library to be a no-op in these cases,
9//! use the `allow_unsupported` feature.
10//!
11//! If you want to make this library be a no-op even if the platform is supported
12//! (for example, for debugging),
13//! add the `no_op` feature:
14//! this turns the entire library into a no-op.
15//!
16//! ## Usage
17//!
18//! ```rust
19//! use shaddup::run_quietly;
20//!
21//! let result = run_quietly(|| {
22//!     println!("This will not be printed");
23//!     eprintln!("This will also not be printed");
24//!     123
25//! });
26//! assert_eq!(result.unwrap(), 123);
27//! ```
28//!
29//! ## Features
30//!
31//! - `no_op`: turns the entire library into a no-op.
32//! - `allow_unsupported`: turns the library into a no-op if the platform is supported (otherwise, the library will cause a compile-error).
33//!
34//! ## See also
35//!
36//! [`gag`](https://docs.rs/gag/latest/gag/) is another library that implements this functionality.
37//! It uses a different API, based on guards
38//! rather than closures.
39//! It supports Unix and Windows.
40
41pub mod error;
42pub mod opts;
43pub use error::Error;
44pub use opts::*;
45
46cfg_if::cfg_if! {
47    if #[cfg(feature = "no_op")] {
48        mod unsupported;
49        use unsupported as platform;
50    } else if #[cfg(unix)] {
51        mod unix;
52        use unix as platform;
53    } else if #[cfg(feature = "allow_unsupported")] {
54        mod unsupported;
55        use unsupported as platform;
56    } else {
57        compile_error!("Currently, only the `unix` target is supported");
58    }
59}
60
61/// Run the given function, preventing it from printing to stdout and stderr.
62///
63/// ```
64/// use shaddup::run_quietly;
65///
66/// let result = run_quietly(|| {
67///     println!("This will not be printed");
68///     123
69/// });
70/// assert_eq!(result.unwrap(), 123);
71/// ```
72pub fn run_quietly<TOut>(
73    action: impl FnOnce() -> TOut + std::panic::UnwindSafe,
74) -> Result<TOut, error::Error<TOut>> {
75    platform::run_quietly_with_opts(action, Opts::default())
76}
77
78/// Run the given function, preventing it from printing to descriptors.
79/// You can customize which ones.
80///
81/// ```
82/// use shaddup::run_quietly_with_opts;
83///
84/// let result = run_quietly_with_opts(|| {
85///     println!("This will not be printed,");
86///     eprintln!("but this will be!");
87///     123
88/// }, shaddup::opts::Opts {
89///     descriptors: shaddup::opts::Descriptors::Stdout,
90/// });
91/// assert_eq!(result.unwrap(), 123);
92/// ```
93pub fn run_quietly_with_opts<TOut>(
94    action: impl FnOnce() -> TOut + std::panic::UnwindSafe,
95    opts: Opts,
96) -> Result<TOut, error::Error<TOut>> {
97    platform::run_quietly_with_opts(action, opts)
98}
shaddup/lib.rs

shaddup/
lib.rs
