Improve error handling (#59)

* Error handling

- Added `Error` struct.
- Added `Result` return type to methods.
- Added justfile to facilitate building multiple platforms.
- Updated README.md
- Removed busy loops

Author: Eduardo Flores

Cargo.toml

@@ -1,22 +1,17 @@
 [package]
 name = "dark-light"
 version = "2.0.0"
-authors = ["Corey Farwell <[email protected]>"]
-edition = "2018"
+authors = [
+    "Corey Farwell <[email protected]>",
+    "Eduardo Flores <[email protected]>",
+]
+edition = "2021"
 license = "MIT/Apache-2.0"
-repository = "https://github.com/frewsxcv/rust-dark-light"
+repository = "https://github.com/rust-dark-light/rust-dark-light"
 description = "Detect if dark mode or light mode is enabled"
 readme = "README.md"
 build = "build.rs"
 
-[[example]]
-name = "sync"
-path = "examples/sync.rs"
-required-features = ["sync"]
-
-[features]
-sync = []
-
 [dependencies]
 futures-lite = "2.3.0"
 log = "0.4.22"

README.md

@@ -7,7 +7,9 @@
     <br>
 </div>
 
-Supports macOS, Windows, Linux, BSDs, and WASM. On Linux the XDG Desktop Portal D-Bus API is checked for the `color-scheme` preference, which works in Flatpak sandboxes without needing filesystem access.
+Supports macOS, Windows, Linux, BSDs, and WebAssembly. 
+
+On Linux the XDG Desktop Portal D-Bus API is checked for the `color-scheme` preference, which works in Flatpak sandboxes without needing filesystem access.
 
 [API Documentation](https://docs.rs/dark-light/)
 
@@ -16,70 +18,39 @@ Supports macOS, Windows, Linux, BSDs, and WASM. On Linux the XDG Desktop Portal
 ### Detect current theme mode
 You can detect the current mode by using the `detect` function. This function returns a `Mode` value.
 ```rust
-use dark_light::Mode;
-
-let mode = dark_light::detect().await;
-
-match mode {
-    Mode::Dark => {},
-    Mode::Light => {},
-    Mode::Default => {},
+fn main() -> Result<(), dark_light::Error> {
+    match dark_light::detect()? {
+        dark_light::Mode::Dark => println!("Dark mode"),
+        dark_light::Mode::Light => println!("Light mode"),
+        dark_light::Mode::Unspecified => println!("Unspecified"),
+    }
+    Ok(())
 }
 ```
 
 ### Subscribe to system theme changes
 You can subscribe to system theme changes by using the `subscribe` function. This function returns a stream of `Mode` values. The stream will emit a new value whenever the system theme changes.
 
+> [!WARNING]
+> The `subscribe` function is not yet supported on macOS, Windows, and WebAssembly.
+> Using it will result in an empty stream.
+
 ```rust
-use dark_light::Mode;
+use futures_lite::StreamExt;
 
 #[tokio::main]
-async fn main() {
-    let mut stream = dark_light::subscribe().await;
+async fn main() -> Result<(), dark_light::Error> {
+    let mut stream = dark_light::subscribe().await?;
     while let Some(mode) = stream.next().await {
-        match mode {
-            Mode::Dark => {},
-            Mode::Light => {},
-            Mode::Default => {},
-        }
+        println!("System mode changed: {:?}", mode);
     }
+    Ok(())
 }
 ```
 
-This crate is asynchronous by default, but can be used in a synchronous manner by enabling the `sync` feature and prefixing the methods with `sync::`. 
-
- ```rust
-let mode = dark_light::sync::detect();
-let rx = dark_light::sync::subscribe();
-```
-
-> If you are upgrading this crate, you may update your code to use the async API or alternatively, you can use the `sync` feature to use the synchronous version of the methods.
-
-## Example
-
-Async:
-```
-cargo run --example async
-```
-
-Sync
-```
-cargo run --example sync
-```
-
-## Test
-To test the crate, run the following command:
-```
-cargo test --doc --all-features
-```
-
 ## License
 
-Licensed under either of
+Licensed under either of the following licenses:
 
  * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
-
-at your option.
-
-
+ * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

examples/async.rs

@@ -0,0 +1,12 @@
+fn main() -> Result<(), dark_light::Error> {
+    match dark_light::detect() {
+        Ok(_) => todo!(),
+        Err(err) => println!("Error: {}", err),
+    }
+    match dark_light::detect()? {
+        dark_light::Mode::Dark => println!("Dark mode"),
+        dark_light::Mode::Light => println!("Light mode"),
+        dark_light::Mode::Unspecified => println!("Unspecified"),
+    }
+    Ok(())
+}

examples/detect.rs

@@ -0,0 +1,10 @@
+use futures_lite::StreamExt;
+
+#[tokio::main]
+async fn main() -> Result<(), dark_light::Error> {
+    let mut stream = dark_light::subscribe().await?;
+    while let Some(mode) = stream.next().await {
+        println!("System mode changed: {:?}", mode);
+    }
+    Ok(())
+}

examples/notify.rs

@@ -0,0 +1,41 @@
+build:
+    echo "Building for Linux..."
+    cargo build --target x86_64-unknown-linux-gnu
+    echo "Building for macOS..."
+    cargo build --target aarch64-apple-darwin
+    echo "Building for Windows..."
+    cargo build --target x86_64-pc-windows-gnu
+    echo "Building for wasm..."
+    cargo build --target wasm32-unknown-unknown
+
+test:
+    cargo test --doc
+
+doc-linux:
+    cargo doc --no-deps --open --target x86_64-unknown-linux-gnu
+
+doc-macos:
+    cargo doc --no-deps --open --target aarch64-apple-darwin
+
+doc-windows:
+    cargo doc --no-deps --open --target x86_64-pc-windows-gnu
+
+doc-wasm:
+    cargo doc --no-deps --open --target wasm32-unknown-unknown
+
+example-linux:
+    echo "Building examples for Linux..."
+    cargo build --example detect --target x86_64-unknown-linux-gnu
+    cargo build --example subscribe --target x86_64-unknown-linux-gnu
+example-macos:
+    echo "Building examples for macOS..."
+    cargo build --example detect --target aarch64-apple-darwin
+    cargo build --example subscribe --target aarch64-apple-darwin
+example-windows:
+    echo "Building examples for Windows..."
+    cargo build --example detect --target x86_64-pc-windows-gnu
+    cargo build --example subscribe --target x86_64-pc-windows-gnu
+example-wasm:
+    echo "Building examples for wasm..."
+    cargo build --example detect --target wasm32-unknown-unknown
+    cargo build --example subscribe --target wasm32-unknown-unknown

examples/subscribe.rs

@@ -0,0 +1,69 @@
+use std::fmt::Display;
+
+/// An error that can occur when detecting the system theme mode.
+#[derive(Debug)]
+pub enum Error {
+    /// If an I/O error occurs.
+    Io(std::io::Error),
+    /// If the system theme mode could not be detected.
+    DetectionFailed,
+
+    #[cfg(target_os = "linux")]
+    /// If the XDG Desktop Portal could not be communicated with.
+    XdgDesktopPortal(ashpd::Error),
+
+    /// Failed to get persistent domain for Apple Global Domain
+    #[cfg(target_os = "macos")]
+    PersistentDomainFailed,
+    /// Failed to get AppleInterfaceStyle
+    #[cfg(target_os = "macos")]
+    AppleInterfaceStyleFailed,
+
+    #[cfg(target_arch = "wasm32")]
+    /// If the window could not be found.
+    WindowNotFound,
+    #[cfg(target_arch = "wasm32")]
+    /// If the media query could not be executed.
+    MediaQueryFailed,
+    #[cfg(target_arch = "wasm32")]
+    /// If the media query is not supported.
+    MediaQueryNotSupported,
+}
+
+impl Display for Error {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Error::Io(error) => write!(f, "I/O error: {}", error),
+            Error::DetectionFailed => write!(f, "Failed to detect system theme mode"),
+            #[cfg(target_os = "linux")]
+            Error::XdgDesktopPortal(err) => write!(f, "XDG Desktop Portal error: {}", err),
+            #[cfg(target_os = "macos")]
+            Error::PersistentDomainFailed => {
+                write!(f, "Failed to get persistent domain for Apple Global Domain")
+            }
+            #[cfg(target_os = "macos")]
+            Error::AppleInterfaceStyleFailed => write!(f, "Failed to get AppleInterfaceStyle"),
+            #[cfg(target_arch = "wasm32")]
+            Error::WindowNotFound => write!(f, "Window not found"),
+            #[cfg(target_arch = "wasm32")]
+            Error::MediaQueryFailed => write!(f, "Media query failed"),
+            #[cfg(target_arch = "wasm32")]
+            Error::MediaQueryNotSupported => write!(f, "Media query not supported"),
+        }
+    }
+}
+
+impl std::error::Error for Error {}
+
+impl From<std::io::Error> for Error {
+    fn from(error: std::io::Error) -> Self {
+        Error::Io(error)
+    }
+}
+
+#[cfg(target_os = "linux")]
+impl From<ashpd::Error> for Error {
+    fn from(error: ashpd::Error) -> Self {
+        Error::XdgDesktopPortal(error)
+    }
+}