From 5dd987f3d25ebf3c82394d1225b836aefaf93b5d Mon Sep 17 00:00:00 2001 From: apogeeoak <59737221+apogeeoak@users.noreply.github.com> Date: Sun, 15 Aug 2021 14:28:26 -0400 Subject: [PATCH 1/2] Update documentation. --- changelog.md | 45 ++++++++++++++------------------------- src/lib.rs | 59 ++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 69 insertions(+), 35 deletions(-) diff --git a/changelog.md b/changelog.md index d4ca8e2..4cdcc20 100644 --- a/changelog.md +++ b/changelog.md @@ -1,3 +1,9 @@ +# Changelog + +## v2.0.1 (2021-08-15) + +Update documentation. No functionality changes. + ## v2.0.0 (2021-07-25) **Breaking**: Change result from `io::Result` to `io::Result<()>`. @@ -7,22 +13,13 @@ issues with particular programs reporting success even on error, doing error han close to impossible. This releases alleviates most of the issues. -Error information is gathered from the stderr channel of the process using a single read operation. -This prevents the child process from keeping the main process alive if stderr is kept open. - ## Notes `wslview` always reports a 0 exit status, even if the path does not exist, which results in false positives. -The stderr channel is written to but ignored in this implementation because of the successful exit status. -Other programs write to stderr as part of normal operation. Firefox on Linux never seems to be able to load all -the modules it wants to, so it writes to stderr but successfully opens. The only way to avoid these false positives -is to special case wsl or for `wslview` to fix the unsuccessful exit status bug. -This is only a minor problem and can mostly be ignored. -## v1.7.0 (2021-07-17) +## v1.7.1 (2021-07-17) -* improved support [for - windows-subsystem-for-linux](https://github.com/Byron/open-rs/pull/33#issue-691044025) +* Improved support for [Windows Subsystem for Linux](https://github.com/Byron/open-rs/pull/33#issue-691044025) ## v1.7.0 (2021-04-18) @@ -63,37 +60,27 @@ YANKED to avoid potential for breakage by using 'explorer.exe' to open URLs. * **windows**: escape '&' in URLs. On windows, a shell is used to execute the command, which requires certain precautions for the URL to open to get through the interpreter. +## v1.1.1 (2016-04-10) - -### v1.1.1 (2016-04-10) - - -#### Bug Fixes +### Bug Fixes * **cargo:** no docs for open ([31605e0e](https://github.com/Byron/open-rs/commit/31605e0eddfb0cf8db635dd4d86131bc46beae78)) -#### Improvements +### Improvements * **api:** allow OSStrings instead of &str ([1d13a671](https://github.com/Byron/open-rs/commit/1d13a671f2c9bd9616bf185fac77b32da1dcf8ee)) - - - ## 25c0e398 (2015-07-08) - -#### Features +### Features * **open** added 'open' program ([a4c3a352](https://github.com/Byron/open-rs/commit/a4c3a352c8f912211d5ab48daaf41cb847ebcc0c)) -#### Bug Fixes +### Bug Fixes * **cargo** description added ([0fcafb56](https://github.com/Byron/open-rs/commit/0fcafb56cdb5d154b3e983d17c93a1dd7c665426)) * **open** - * use result ([25c0e398](https://github.com/Byron/open-rs/commit/25c0e398856c24a2daf0444640567ed3fd2f4307)) - * don't use 'open' on linux ([30c96b1c](https://github.com/Byron/open-rs/commit/30c96b1cb95c1e03bede218b8fb03bbd9ada9317)) - * linux uses open before anything else ([4696d1a5](https://github.com/Byron/open-rs/commit/4696d1a5ec80691e97bb1be4261d4f79ee0ade4d)) + * use result ([25c0e398](https://github.com/Byron/open-rs/commit/25c0e398856c24a2daf0444640567ed3fd2f4307)) + * don't use 'open' on linux ([30c96b1c](https://github.com/Byron/open-rs/commit/30c96b1cb95c1e03bede218b8fb03bbd9ada9317)) + * linux uses open before anything else ([4696d1a5](https://github.com/Byron/open-rs/commit/4696d1a5ec80691e97bb1be4261d4f79ee0ade4d)) * **rustup** (07560d233 2015-04-20) (built 2015-04-19) ([8b4e1558](https://github.com/Byron/open-rs/commit/8b4e1558f09937c555ab381ea6399a2c0758c23d)) - - - diff --git a/src/lib.rs b/src/lib.rs index 0e36856..b85c0b2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -30,13 +30,13 @@ //! ``` #[cfg(target_os = "windows")] -pub use windows::{that, with}; +use windows as os; #[cfg(target_os = "macos")] -pub use macos::{that, with}; +use macos as os; #[cfg(target_os = "ios")] -pub use ios::{that, with}; +use ios as os; #[cfg(any( target_os = "linux", @@ -47,7 +47,7 @@ pub use ios::{that, with}; target_os = "openbsd", target_os = "solaris" ))] -pub use unix::{that, with}; +use unix as os; #[cfg(not(any( target_os = "linux", @@ -72,13 +72,60 @@ use std::{ type Result = io::Result<()>; -/// Convenience function for opening the passed path in a new thread. -/// See documentation of `that(...)` for more details. +/// Open path with the default application. +/// +/// # Examples +/// +/// ``` +/// let path = "http://rust-lang.org"; +/// +/// match open::that(path) { +/// Ok(()) => println!("Opened '{}' successfully.", path), +/// Err(err) => panic!("An error occurred when opening '{}': {}", path, err), +/// } +/// ``` +/// +/// # Errors +/// +/// A [`std::io::Error`] is returned on failure. Because different operating systems +/// handle errors differently it is recommend to not match on a certain error. +pub fn that + Sized>(path: T) -> Result { + os::that(path) +} + +/// Open path with the given application. +/// +/// # Examples +/// +/// ``` +/// let path = "http://rust-lang.org"; +/// let app = "firefox"; +/// +/// match open::with(path, app) { +/// Ok(()) => println!("Opened '{}' successfully.", path), +/// Err(err) => panic!("An error occurred when opening '{}': {}", path, err), +/// } +/// ``` +/// +/// # Errors +/// +/// A [`std::io::Error`] is returned on failure. Because different operating systems +/// handle errors differently it is recommend to not match on a certain error. +pub fn with + Sized>(path: T, app: impl Into) -> Result { + os::with(path, app) +} + +/// Open path with the default application in a new thread. +/// +/// See documentation of [`that`] for more details. pub fn that_in_background + Sized>(path: T) -> thread::JoinHandle { let path = path.as_ref().to_os_string(); thread::spawn(|| that(path)) } +/// Open path with the given application in a new thread. +/// +/// See documentation of [`with`] for more details. pub fn with_in_background + Sized>( path: T, app: impl Into, From 7c9765891b86d5d6168556e8f5363641f57e130d Mon Sep 17 00:00:00 2001 From: apogeeoak <59737221+apogeeoak@users.noreply.github.com> Date: Sun, 15 Aug 2021 14:39:53 -0400 Subject: [PATCH 2/2] Add no_run to documentation examples. --- src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index b85c0b2..0b78a9a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -76,7 +76,7 @@ type Result = io::Result<()>; /// /// # Examples /// -/// ``` +/// ```no_run /// let path = "http://rust-lang.org"; /// /// match open::that(path) { @@ -97,7 +97,7 @@ pub fn that + Sized>(path: T) -> Result { /// /// # Examples /// -/// ``` +/// ```no_run /// let path = "http://rust-lang.org"; /// let app = "firefox"; ///