Provide separate _with_options overloads

Author: bash

crates/pycolorsaurus/src/lib.rs

@@ -31,7 +31,7 @@ create_exception!(colorsaurus, ColorsaurusError, PyException);
 #[pyfunction]
 #[pyo3(signature = (*, timeout=None))]
 fn color_scheme(timeout: Option<Timeout>) -> PyResult<ColorScheme> {
-    imp::color_scheme(query_options(timeout))
+    imp::color_scheme_with_options(query_options(timeout))
         .map(ColorScheme::from)
         .map_err(to_py_error)
 }
@@ -40,7 +40,7 @@ fn color_scheme(timeout: Option<Timeout>) -> PyResult<ColorScheme> {
 #[pyfunction]
 #[pyo3(signature = (*, timeout=None))]
 fn color_palette(timeout: Option<Timeout>) -> PyResult<ColorPalette> {
-    imp::color_palette(query_options(timeout))
+    imp::color_palette_with_options(query_options(timeout))
         .map(ColorPalette)
         .map_err(to_py_error)
 }
@@ -49,7 +49,7 @@ fn color_palette(timeout: Option<Timeout>) -> PyResult<ColorPalette> {
 #[pyfunction]
 #[pyo3(signature = (*, timeout=None))]
 fn foreground_color(timeout: Option<Timeout>) -> PyResult<Color> {
-    imp::foreground_color(query_options(timeout))
+    imp::foreground_color_with_options(query_options(timeout))
         .map(Color)
         .map_err(to_py_error)
 }
@@ -58,7 +58,7 @@ fn foreground_color(timeout: Option<Timeout>) -> PyResult<Color> {
 #[pyfunction]
 #[pyo3(signature = (*, timeout=None))]
 fn background_color(timeout: Option<Timeout>) -> PyResult<Color> {
-    imp::background_color(query_options(timeout))
+    imp::background_color_with_options(query_options(timeout))
         .map(Color)
         .map_err(to_py_error)
 }

crates/termtheme/src/main.rs

@@ -5,7 +5,7 @@ use std::{
     io::{self, stdout, IsTerminal},
     process::exit,
 };
-use terminal_colorsaurus::{color_scheme, ColorScheme, QueryOptions};
+use terminal_colorsaurus::{color_scheme, ColorScheme};
 
 fn main() {
     let args = Args::parse();
@@ -16,7 +16,7 @@ fn main() {
         );
         exit(1);
     }
-    match color_scheme(QueryOptions::default()) {
+    match color_scheme() {
         Ok(s) => display_theme(s, !args.no_newline),
         Err(e) => {
             display_error(e);

examples/benchmark/src/main.rs

@@ -5,7 +5,7 @@ use std::fs::OpenOptions;
 use std::hint::black_box;
 use std::io::{self, Write as _};
 use std::time::{Duration, Instant};
-use terminal_colorsaurus::{color_palette, Error, QueryOptions, Result};
+use terminal_colorsaurus::{color_palette, Error, Result};
 
 #[derive(Parser, Debug)]
 struct Args {
@@ -40,7 +40,7 @@ fn main() -> Result<()> {
         .collect::<Result<Vec<_>>>()?;
     bar.finish();
 
-    let supported = match color_palette(QueryOptions::default()) {
+    let supported = match color_palette() {
         Ok(_) => true,
         Err(Error::UnsupportedTerminal) => false,
         Err(e) => return Err(e),
@@ -53,7 +53,7 @@ fn main() -> Result<()> {
 
 fn bench() -> Result<Duration> {
     let start = Instant::now();
-    match black_box(color_palette(QueryOptions::default())) {
+    match black_box(color_palette()) {
         Ok(_) | Err(Error::UnsupportedTerminal) => Ok(start.elapsed()),
         Err(err) => Err(err),
     }

examples/bg.rs

@@ -1,9 +1,9 @@
 //! This example shows how to retrieve the terminal's background color.
 
-use terminal_colorsaurus::{background_color, Error, QueryOptions};
+use terminal_colorsaurus::{background_color, Error};
 
 fn main() -> Result<(), display::DisplayAsDebug<Error>> {
-    let bg = background_color(QueryOptions::default())?;
+    let bg = background_color()?;
     let bg_8bit = bg.scale_to_8bit();
     println!("rgb16({}, {}, {})", bg.r, bg.g, bg.b);
     println!("rgb8({}, {}, {})", bg_8bit.0, bg_8bit.1, bg_8bit.2);

examples/fg.rs

@@ -1,9 +1,9 @@
 //! This example shows how to retrieve the terminal's foreground color.
 
-use terminal_colorsaurus::{foreground_color, Error, QueryOptions};
+use terminal_colorsaurus::{foreground_color, Error};
 
 fn main() -> Result<(), display::DisplayAsDebug<Error>> {
-    let fg = foreground_color(QueryOptions::default())?;
+    let fg = foreground_color()?;
     let fg_8bit = fg.scale_to_8bit();
     println!("rgb16({}, {}, {})", fg.r, fg.g, fg.b);
     println!("rgb8({}, {}, {})", fg_8bit.0, fg_8bit.1, fg_8bit.2);

examples/pager.rs

@@ -20,14 +20,11 @@
 //! 4. `cargo run --example pager 2>&1 >/dev/tty | less`—should print the color scheme (or error). This is a false positive.
 
 use std::io::{stdout, IsTerminal as _};
-use terminal_colorsaurus::{color_palette, Error, QueryOptions};
+use terminal_colorsaurus::{color_palette, Error};
 
 fn main() -> Result<(), display::DisplayAsDebug<Error>> {
     if stdout().is_terminal() {
-        eprintln!(
-            "Here's the color scheme: {:#?}",
-            color_palette(QueryOptions::default())?
-        );
+        eprintln!("Here's the color scheme: {:#?}", color_palette()?);
     } else {
         eprintln!("No color scheme for you today :/");
     }

examples/theme.rs

@@ -1,10 +1,10 @@
 //! This example shows how to detect if the terminal uses
 //! a dark-on-light or a light-on-dark theme.
 
-use terminal_colorsaurus::{color_palette, ColorScheme, Error, QueryOptions};
+use terminal_colorsaurus::{color_palette, ColorScheme, Error};
 
 fn main() -> Result<(), display::DisplayAsDebug<Error>> {
-    let colors = color_palette(QueryOptions::default())?;
+    let colors = color_palette()?;
 
     let theme = match colors.color_scheme() {
         ColorScheme::Dark => "dark",

readme.md

@@ -13,11 +13,12 @@ Windows is unfortunately [not supported](./doc/windows.md).
 
 ## Example
 ```rust,no_run
-use terminal_colorsaurus::{color_scheme, QueryOptions, ColorScheme};
+use terminal_colorsaurus::{color_scheme, ColorScheme};
 
-match color_scheme(QueryOptions::default()).unwrap() {
-    ColorScheme::Dark => { /* ... */ },
-    ColorScheme::Light => { /* ... */ },
+match color_scheme() {
+    Ok(ColorScheme::Dark) => { /* ... */ },
+    Ok(ColorScheme::Light) => { /* ... */ },
+    Err(_e) => { /* something went wrong, fallback to something else */ },
 }
 ```
 

src/lib.rs

@@ -16,17 +16,17 @@
 //!
 //! ## Example 1: Test If the Terminal Uses a Dark Background
 //! ```no_run
-//! use terminal_colorsaurus::{color_scheme, QueryOptions, ColorScheme};
+//! use terminal_colorsaurus::{color_scheme, ColorScheme};
 //!
-//! let color_scheme = color_scheme(QueryOptions::default()).unwrap();
+//! let color_scheme = color_scheme().unwrap();
 //! dbg!(color_scheme == ColorScheme::Dark);
 //! ```
 //!
 //! ## Example 2: Query for the Terminal's Foreground Color
 //! ```no_run
-//! use terminal_colorsaurus::{foreground_color, QueryOptions};
+//! use terminal_colorsaurus::foreground_color;
 //!
-//! let fg = foreground_color(QueryOptions::default()).unwrap();
+//! let fg = foreground_color().unwrap();
 //! println!("rgb({}, {}, {})", fg.r, fg.g, fg.b);
 //! ```
 //!
@@ -183,7 +183,7 @@ impl ColorPalette {
 pub type Result<T> = std::result::Result<T, Error>;
 pub use error::Error;
 
-/// Options to be used with [`foreground_color`] and [`background_color`].
+/// Options to be used with [`foreground_color_with_options`] and [`background_color_with_options`].
 /// You should almost always use the unchanged [`QueryOptions::default`] value.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
@@ -208,33 +208,61 @@ impl Default for QueryOptions {
     }
 }
 
-/// Detects if the terminal is dark or light.
-#[doc = include_str!("../doc/caveats.md")]
-#[doc(alias = "theme")]
-pub fn color_scheme(options: QueryOptions) -> Result<ColorScheme> {
-    color_palette(options).map(|p| p.color_scheme())
+macro_rules! impl_query_fn {
+    ($(#[$($meta:meta)*])* $vis:vis fn $name:ident() -> $ret:ty; $vis_opt:vis fn $name_opt:ident($opt:ident : $opt_ty:ty) -> $ret_opt:ty $impl:block) => {
+        $(#[$($meta)*])*
+        #[doc = concat!("\n\nUse [`", stringify!($name_opt), "`] instead, if you want to provide custom query options.")]
+        $vis fn $name() -> $ret {
+            $name_opt(Default::default())
+        }
+
+        $(#[$($meta)*])* $vis_opt fn $name_opt($opt:$opt_ty) -> $ret_opt $impl
+    };
+}
+
+impl_query_fn! {
+    /// Detects if the terminal is dark or light.
+    #[doc = include_str!("../doc/caveats.md")]
+    #[doc(alias = "theme")]
+    pub fn color_scheme() -> Result<ColorScheme>;
+
+    pub fn color_scheme_with_options(options: QueryOptions) -> Result<ColorScheme> {
+        color_palette_with_options(options).map(|p| p.color_scheme())
+    }
 }
 
-/// Queries the terminal for it's color scheme (foreground and background color).
-#[doc = include_str!("../doc/caveats.md")]
-pub fn color_palette(options: QueryOptions) -> Result<ColorPalette> {
-    imp::color_palette(options)
+impl_query_fn! {
+    /// Queries the terminal for it's color scheme (foreground and background color).
+    #[doc = include_str!("../doc/caveats.md")]
+    pub fn color_palette() -> Result<ColorPalette>;
+
+    pub fn color_palette_with_options(options: QueryOptions) -> Result<ColorPalette> {
+        imp::color_palette(options)
+    }
 }
 
-/// Queries the terminal for it's foreground color. \
-/// If you also need the foreground color it is more efficient to use [`color_palette`] instead.
-#[doc = include_str!("../doc/caveats.md")]
-#[doc(alias = "fg")]
-pub fn foreground_color(options: QueryOptions) -> Result<Color> {
-    imp::foreground_color(options)
+impl_query_fn! {
+    /// Queries the terminal for it's foreground color. \
+    /// If you also need the background color it is more efficient to use [`color_palette`] instead.
+    #[doc = include_str!("../doc/caveats.md")]
+    #[doc(alias = "fg")]
+    pub fn foreground_color() -> Result<Color>;
+
+    pub fn foreground_color_with_options(options: QueryOptions) -> Result<Color> {
+        imp::foreground_color(options)
+    }
 }
 
-/// Queries the terminal for it's background color. \
-/// If you also need the foreground color it is more efficient to use [`color_palette`] instead.
-#[doc = include_str!("../doc/caveats.md")]
-#[doc(alias = "bg")]
-pub fn background_color(options: QueryOptions) -> Result<Color> {
-    imp::background_color(options)
+impl_query_fn! {
+    /// Queries the terminal for it's background color. \
+    /// If you also need the foreground color it is more efficient to use [`color_palette`] instead.
+    #[doc = include_str!("../doc/caveats.md")]
+    #[doc(alias = "fg")]
+    pub fn background_color() -> Result<Color>;
+
+    pub fn background_color_with_options(options: QueryOptions) -> Result<Color> {
+        imp::background_color(options)
+    }
 }
 
 #[cfg(test)]