chore: docs update

Author: tao-guo

README.md

@@ -88,7 +88,7 @@ let dir = "/var/log";
 run_cmd!(du -ah $dir | sort -hr | head -n 10)?;
 
 // or a group of commands
-// if any command fails, just return Err(...)
+// if any command fails, just return Err(...), which is similar to bash's `set -euo pipefail`
 let file = "/tmp/f";
 let keyword = "rust";
 run_cmd! {
@@ -104,7 +104,7 @@ run_cmd! {
 - [`run_fun!`](https://docs.rs/cmd_lib/latest/cmd_lib/macro.run_fun.html) -> [`FunResult`](https://docs.rs/cmd_lib/latest/cmd_lib/type.FunResult.html)
 
 ```rust
-let version = run_fun!(rustc --version)?;
+let version = run_fun!(rustc --version | awk r"{print $2}")?;
 eprintln!("Your rust version is {}", version);
 
 // with pipes
@@ -347,5 +347,4 @@ That said, there are some limitations to be aware of:
 [std::env::remove_var]: https://doc.rust-lang.org/std/env/fn.remove_var.html
 [must not be called]: https://doc.rust-lang.org/nightly/edition-guide/rust-2024/newly-unsafe-functions.html#stdenvset_var-remove_var
 
-
 License: MIT OR Apache-2.0

src/lib.rs

@@ -96,7 +96,7 @@
 //! run_cmd!(du -ah $dir | sort -hr | head -n 10)?;
 //!
 //! // or a group of commands
-//! // if any command fails, just return Err(...)
+//! // if any command fails, just return Err(...), which is similar to bash's `set -euo pipefail`
 //! let file = "/tmp/f";
 //! let keyword = "rust";
 //! run_cmd! {
@@ -114,7 +114,7 @@
 //!
 //! ```
 //! # use cmd_lib::run_fun;
-//! let version = run_fun!(rustc --version)?;
+//! let version = run_fun!(rustc --version | awk r"{print $2}")?;
 //! eprintln!("Your rust version is {}", version);
 //!
 //! // with pipes
@@ -369,11 +369,13 @@
 //! - [std::env::set_var] and [std::env::remove_var] **[must not be called]** in a multi-threaded program
 //! - [`tls_init!`](https://docs.rs/cmd_lib/latest/cmd_lib/macro.tls_init.html),
 //!   [`tls_get!`](https://docs.rs/cmd_lib/latest/cmd_lib/macro.tls_get.html), and
-//!   [`tls_set!`](https://docs.rs/cmd_lib/latest/cmd_lib/macro.tls_set.html) create *thread-local* variables, which
-//!   means each thread will have its own independent version of the variable
+//!   [`tls_set!`](https://docs.rs/cmd_lib/latest/cmd_lib/macro.tls_set.html) create *thread-local* variables, which means
+//!   each thread will have its own independent version of the variable
 //! - [`set_debug`](https://docs.rs/cmd_lib/latest/cmd_lib/fn.set_debug.html) and
 //!   [`set_pipefail`](https://docs.rs/cmd_lib/latest/cmd_lib/fn.set_pipefail.html) are *global* and affect all threads;
-//!   there is currently no way to change those settings without affecting other threads
+//!   to change those settings without affecting other threads, use
+//!   [`ScopedDebug`](https://docs.rs/cmd_lib/latest/cmd_lib/struct.ScopedDebug.html) and
+//!   [`ScopedPipefail`](https://docs.rs/cmd_lib/latest/cmd_lib/struct.ScopedPipefail.html)
 //!
 //! [std::env::set_var]: https://doc.rust-lang.org/std/env/fn.set_var.html
 //! [std::env::remove_var]: https://doc.rust-lang.org/std/env/fn.remove_var.html

src/process.rs

@@ -109,6 +109,22 @@ static PIPEFAIL_ENABLED: LazyLock<AtomicBool> =
 ///
 /// Setting environment variable CMD_LIB_DEBUG=0|1 has the same effect, but the environment variable is only
 /// checked once at an unspecified time, so the only reliable way to do that is when the program is first started.
+///
+/// ## Example
+/// ```console
+/// λ  test_cmd_lib git:(master) ✗ cat src/main.rs
+/// use cmd_lib::*;
+///
+/// #[cmd_lib::main]
+/// fn main() -> CmdResult {
+///     run_cmd!(cat src/main.rs | wc -l)
+/// }
+/// λ  test_cmd_lib git:(master) ✗ RUST_LOG=debug CMD_LIB_DEBUG=1 cargo r
+///     Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s
+///      Running `target/debug/test_cmd_lib`
+/// [DEBUG] Running ["cat" "src/main.rs" | "wc" "-l"] at src/main.rs:5 ...
+/// 6
+/// ```
 pub fn set_debug(enable: bool) {
     DEBUG_ENABLED.store(enable, SeqCst);
 }
@@ -117,7 +133,7 @@ pub fn set_debug(enable: bool) {
 ///
 /// This is **global**, and affects all threads. To set it for the current thread only, use [`ScopedPipefail`].
 ///
-/// Setting environment variable CMD_LIB_DEBUG=0|1 has the same effect, but the environment variable is only
+/// Setting environment variable CMD_LIB_PIPEFAIL=0|1 has the same effect, but the environment variable is only
 /// checked once at an unspecified time, so the only reliable way to do that is when the program is first started.
 pub fn set_pipefail(enable: bool) {
     PIPEFAIL_ENABLED.store(enable, SeqCst);