Merge pull request #4 from artichoke/lopopolo/example

Add crate example

.github/workflows/ci.yaml

@@ -44,6 +44,15 @@ jobs:
       - name: Test with no default features
         run: cargo test --no-default-features
 
+      - name: Check example
+        run: cargo check --examples
+
+      - name: Build examples
+        run: cargo build --examples
+
+      - name: Run example
+        run: cargo run --example get_profile_dir -q
+
   build-msrv:
     name: Build (MSRV)
     runs-on: windows-latest
@@ -58,7 +67,7 @@ jobs:
       - name: Install Rust toolchain
         uses: artichoke/setup-rust/build-and-test@v1.9.0
         with:
-          toolchain: "1.56.0"
+          toolchain: "1.58.0"
 
       - name: Compile
         run: cargo build --verbose
@@ -75,6 +84,15 @@ jobs:
       - name: Test with no default features
         run: cargo test --no-default-features
 
+      - name: Check example
+        run: cargo check --examples
+
+      - name: Build examples
+        run: cargo build --examples
+
+      - name: Run example
+        run: cargo run --example get_profile_dir -q
+
   build-non-windows:
     name: Build (non-Windows platforms)
     runs-on: ${{ matrix.os }}
@@ -112,6 +130,19 @@ jobs:
       - name: Build documentation
         run: cargo doc
 
+      - name: Check example
+        run: cargo check --examples
+
+      - name: Build examples
+        run: cargo build --examples
+
+      - name: Run example
+        shell: bash
+        run: |
+          error_code="0"
+          cargo run --example get_profile_dir -q || error_code="$?"
+          [[ "$error_code" == "1" ]]
+
   rust:
     name: Lint and format Rust
     runs-on: windows-latest

Cargo.toml

@@ -4,7 +4,7 @@ version = "1.0.0" # remember to set `html_root_url` in `src/lib.rs`.
 authors = ["Ryan Lopopolo <rjl@hyperbo.la>"]
 license = "Apache-2.0 OR MIT"
 edition = "2021"
-rust-version = "1.56.0"
+rust-version = "1.58.0"
 readme = "README.md"
 repository = "https://github.com/artichoke/known-folders-rs"
 documentation = "https://docs.rs/known-folders"

README.md

@@ -34,6 +34,12 @@ use known_folders::{get_known_folder_path, KnownFolder};
 let profile_dir = get_known_folder_path(KnownFolder::Profile);
 ```
 
+You can test this crate works on your platform by running the example:
+
+```shell
+cargo run --example get_profile_dir
+```
+
 ## Implementation
 
 known-folders-rs binds directly to `Win32` using [`windows_sys`].
@@ -44,7 +50,7 @@ Note that this crate is completely empty on non-Windows platforms.
 
 ## Minimum Supported Rust Version
 
-This crate requires at least Rust 1.56.0. This version can be bumped in minor
+This crate requires at least Rust 1.58.0. This version can be bumped in minor
 releases.
 
 ## License

examples/get_profile_dir.rs

@@ -0,0 +1,108 @@
+// examples/get_profile_dir.rs
+//
+// Copyright (c) 2023 Ryan Lopopolo <rjl@hyperbo.la>
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE> or
+// <http://www.apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT>
+// or <http://opensource.org/licenses/MIT>, at your option. All files in the
+// project carrying such notice may not be copied, modified, or distributed
+// except according to those terms.
+
+#![warn(clippy::all)]
+#![warn(clippy::pedantic)]
+#![warn(clippy::cargo)]
+#![allow(clippy::enum_glob_use)]
+#![allow(clippy::wildcard_imports)]
+#![allow(unknown_lints)]
+#![warn(missing_copy_implementations)]
+#![warn(missing_debug_implementations)]
+#![warn(missing_docs)]
+#![warn(rust_2018_idioms)]
+#![warn(trivial_casts, trivial_numeric_casts)]
+#![warn(unused_qualifications)]
+#![warn(variant_size_differences)]
+
+//! Example demonstrating the sysdir well-known directory enumeration API.
+//!
+//! # Usage
+//!
+//! ```shell
+//! cargo run --example enumerate_system_dirs
+//! ```
+
+use std::io::{self, Write as _};
+use std::process;
+
+fn main() {
+    match platform::try_main() {
+        Ok(()) => {}
+        Err(err) => {
+            let _ignore = writeln!(io::stderr(), "{err}");
+            process::exit(1);
+        }
+    }
+}
+
+#[cfg(not(windows))]
+mod platform {
+    use std::error::Error;
+    use std::fmt;
+
+    #[derive(Debug, Clone, Copy)]
+    struct PlatformNotSupported;
+
+    impl fmt::Display for PlatformNotSupported {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            f.write_str("The Known Folders API is not supported on this platform. The Known Folders API is only available on Windows Vista and later.")
+        }
+    }
+
+    impl Error for PlatformNotSupported {}
+
+    pub fn try_main() -> Result<(), Box<dyn Error>> {
+        return Err(Box::new(PlatformNotSupported));
+    }
+}
+
+#[cfg(windows)]
+mod platform {
+    use std::error::Error;
+    use std::fmt;
+    use std::io::{self, Write as _};
+
+    use known_folders::{get_known_folder_path, KnownFolder};
+
+    #[derive(Debug, Clone, Copy)]
+    struct PlatformError;
+
+    impl fmt::Display for PlatformError {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            f.write_str("An unknown error occurred when resolving the known folder.")
+        }
+    }
+
+    impl Error for PlatformError {}
+
+    #[derive(Debug, Clone, Copy)]
+    struct UnsupportedPathEncoding;
+
+    impl fmt::Display for UnsupportedPathEncoding {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            f.write_str("The known folder path was not UTF-8 encoded.")
+        }
+    }
+
+    impl Error for UnsupportedPathEncoding {}
+
+    pub fn try_main() -> Result<(), Box<dyn Error>> {
+        let profile_dir = get_known_folder_path(KnownFolder::Profile).ok_or(PlatformError)?;
+
+        let display = profile_dir
+            .into_os_string()
+            .into_string()
+            .map_err(|_| UnsupportedPathEncoding)?;
+
+        writeln!(io::stdout(), "Profile directory: {display}")?;
+        Ok(())
+    }
+}