Merge branch 'master' into feat/build-script-log

Author: tao-guo

Cargo.toml

@@ -8,21 +8,22 @@ documentation = "https://docs.rs/cmd_lib"
 keywords = ["shell", "script", "cli", "process", "pipe"]
 categories = ["command-line-interface", "command-line-utilities"]
 readme = "README.md"
-version = "1.9.5"
+version = "1.9.6"
 authors = ["rust-shell-script <[email protected]>"]
 edition = "2018"
 
 [workspace]
 members = ["macros"]
 
 [dependencies]
-cmd_lib_macros = { version = "1.9.5", path = "./macros" }
+cmd_lib_macros = { version = "1.9.6", path = "./macros" }
 lazy_static = "1.4.0"
 log = "0.4.20"
 faccess = "0.2.4"
 os_pipe = "1.1.4"
 env_logger = "0.10.0"
-build-print = { version = "0.1.1", optional = true }
+build-print = { version = "1.0", optional = true }
+tracing = { version = "0.1.41", optional = true }
 
 [dev-dependencies]
 rayon = "1.8.0"
@@ -31,3 +32,9 @@ byte-unit = "4.0.19"
 
 [features]
 build-print = ["dep:build-print"]
+tracing = "0.1.41"
+tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
+
+[[example]]
+name = "tracing"
+required-features = ["tracing"]

README.md

@@ -304,11 +304,10 @@ You can use [std::env::var](https://doc.rust-lang.org/std/env/fn.var.html) to fe
 key from the current process. It will report error if the environment variable is not present, and it also
 includes other checks to avoid silent failures.
 
-To set environment variables, you can use [std::env::set_var](https://doc.rust-lang.org/std/env/fn.set_var.html).
-There are also other related APIs in the [std::env](https://doc.rust-lang.org/std/env/index.html) module.
+To set environment variables in **single-threaded programs**, you can use [std::env::set_var] and
+[std::env::remove_var]. While those functions **[must not be called]** if any other threads might be running, you can
+always set environment variables for one command at a time, by putting the assignments before the command:
 
-To set environment variables for the command only, you can put the assignments before the command.
-Like this:
 ```rust
 run_cmd!(FOO=100 /tmp/test_run_cmd_lib.sh)?;
 ```
@@ -330,9 +329,23 @@ You can use the [glob](https://github.com/rust-lang-nursery/glob) package instea
 
 #### Thread Safety
 
-This library tries very hard to not set global states, so parallel `cargo test` can be executed just fine.
-The only known APIs not supported in multi-thread environment are the
-[`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)/[`tls_set!`](https://docs.rs/cmd_lib/latest/cmd_lib/macro.tls_set.html) macros, and you should only use them for *thread local* variables.
+This library tries very hard to not set global state, so parallel `cargo test` can be executed just fine.
+That said, there are some limitations to be aware of:
+
+- [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
+- [`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;
+  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
+[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

examples/dd_test.rs

@@ -15,10 +15,10 @@
 //! [INFO ] Total bandwidth: 1.11 GiB/s
 //! ```
 use byte_unit::Byte;
+use clap::Parser;
 use cmd_lib::*;
 use rayon::prelude::*;
 use std::time::Instant;
-use clap::Parser;
 
 const DATA_SIZE: u64 = 10 * 1024 * 1024 * 1024; // 10GB data
 

examples/progress.rs

@@ -0,0 +1,8 @@
+use cmd_lib::{run_cmd, CmdResult};
+
+#[cmd_lib::main]
+fn main() -> CmdResult {
+    run_cmd!(dd if=/dev/urandom of=/dev/null bs=1M status=progress)?;
+
+    Ok(())
+}

examples/tracing.rs

@@ -0,0 +1,27 @@
+use cmd_lib::{run_cmd, CmdResult};
+use tracing::level_filters::LevelFilter;
+use tracing_subscriber::{layer::SubscriberExt as _, util::SubscriberInitExt as _, EnvFilter};
+
+#[cmd_lib::main]
+fn main() -> CmdResult {
+    tracing_subscriber::registry()
+        .with(tracing_subscriber::fmt::layer().with_writer(std::io::stderr))
+        .with(
+            EnvFilter::builder()
+                .with_default_directive(LevelFilter::INFO.into())
+                .from_env_lossy(),
+        )
+        .init();
+
+    copy_thing()?;
+
+    Ok(())
+}
+
+#[tracing::instrument]
+fn copy_thing() -> CmdResult {
+    // Log output from stderr inherits the `copy_thing` span from this function
+    run_cmd!(dd if=/dev/urandom of=/dev/null bs=1M count=1000)?;
+
+    Ok(())
+}

macros/Cargo.toml

@@ -5,7 +5,7 @@ license = "MIT OR Apache-2.0"
 homepage = "https://github.com/rust-shell-script/rust_cmd_lib"
 repository = "https://github.com/rust-shell-script/rust_cmd_lib"
 keywords = ["shell", "script", "cli", "process", "pipe"]
-version = "1.9.5"
+version = "1.9.6"
 authors = ["Tao Guo <[email protected]>"]
 edition = "2018"
 

macros/src/lexer.rs

@@ -2,80 +2,136 @@ use crate::parser::{ParseArg, Parser};
 use proc_macro2::{token_stream, Delimiter, Ident, Literal, Span, TokenStream, TokenTree};
 use proc_macro_error2::abort;
 use quote::quote;
-use std::ffi::OsString;
 use std::iter::Peekable;
+use std::str::Chars;
 
-// Scan string literal to tokenstream, used by most of the macros
-//
-// - support ${var} or $var for interpolation
-//   - to escape '$' itself, use "$$"
-// - support normal rust character escapes:
-//   https://doc.rust-lang.org/reference/tokens.html#ascii-escapes
+/// Scan string literal to tokenstream, used by most of the macros
+///
+/// - support $var, ${var} or ${var:fmt} for interpolation, where `fmt` can be any
+///   of the standard Rust formatting specifiers (e.g., `?`, `x`, `X`, `o`, `b`, `p`, `e`, `E`).
+///   - to escape '$' itself, use "$$"
+/// - support normal rust character escapes:
+///   https://doc.rust-lang.org/reference/tokens.html#ascii-escapes
 pub fn scan_str_lit(lit: &Literal) -> TokenStream {
     let s = lit.to_string();
+
+    // If the literal is not a string (e.g., a number literal), treat it as a direct CmdString.
     if !s.starts_with('\"') {
         return quote!(::cmd_lib::CmdString::from(#lit));
     }
-    let mut iter = s[1..s.len() - 1] // To trim outside ""
-        .chars()
-        .peekable();
+
+    // Extract the inner string by trimming the surrounding quotes.
+    let inner_str = &s[1..s.len() - 1];
+    let mut chars = inner_str.chars().peekable();
     let mut output = quote!(::cmd_lib::CmdString::default());
-    let mut last_part = OsString::new();
-    fn seal_last_part(last_part: &mut OsString, output: &mut TokenStream) {
+    let mut current_literal_part = String::new();
+
+    // Helper function to append the accumulated literal part to the output TokenStream
+    // and clear the current_literal_part.
+    let seal_current_literal_part = |output: &mut TokenStream, last_part: &mut String| {
         if !last_part.is_empty() {
-            let lit_str = format!("\"{}\"", last_part.to_str().unwrap());
-            let l = syn::parse_str::<Literal>(&lit_str).unwrap();
-            output.extend(quote!(.append(#l)));
+            let lit_str = format!("\"{}\"", last_part);
+            // It's safe to unwrap parse_str because we are constructing a valid string literal.
+            let literal_token = syn::parse_str::<Literal>(&lit_str).unwrap();
+            output.extend(quote!(.append(#literal_token)));
             last_part.clear();
         }
-    }
+    };
 
-    while let Some(ch) = iter.next() {
+    while let Some(ch) = chars.next() {
         if ch == '$' {
-            if iter.peek() == Some(&'$') {
-                iter.next();
-                last_part.push("$");
+            // Handle "$$" for escaping '$'
+            if chars.peek() == Some(&'$') {
+                chars.next(); // Consume the second '$'
+                current_literal_part.push('$');
                 continue;
             }
 
-            seal_last_part(&mut last_part, &mut output);
-            let mut with_brace = false;
-            if iter.peek() == Some(&'{') {
-                with_brace = true;
-                iter.next();
+            // Before handling a variable, append any accumulated literal part.
+            seal_current_literal_part(&mut output, &mut current_literal_part);
+
+            let mut format_specifier = String::new(); // To store the fmt specifier (e.g., "?", "x", "#x")
+            let mut is_braced_interpolation = false;
+
+            // Check for '{' to start a braced interpolation
+            if chars.peek() == Some(&'{') {
+                is_braced_interpolation = true;
+                chars.next(); // Consume '{'
             }
-            let mut var = String::new();
-            while let Some(&c) = iter.peek() {
-                if !c.is_ascii_alphanumeric() && c != '_' {
-                    break;
+
+            let var_name = parse_variable_name(&mut chars);
+
+            if is_braced_interpolation {
+                // If it's braced, we might have a format specifier or it might just be empty braces.
+                if chars.peek() == Some(&':') {
+                    chars.next(); // Consume ':'
+                                  // Read the format specifier until '}'
+                    while let Some(&c) = chars.peek() {
+                        if c == '}' {
+                            break;
+                        }
+                        format_specifier.push(c);
+                        chars.next(); // Consume the character of the specifier
+                    }
                 }
-                if var.is_empty() && c.is_ascii_digit() {
-                    break;
+
+                // Expect '}' to close the braced interpolation
+                if chars.next() != Some('}') {
+                    abort!(lit.span(), "bad substitution: expected '}'");
                 }
-                var.push(c);
-                iter.next();
             }
-            if with_brace {
-                if iter.peek() != Some(&'}') {
-                    abort!(lit.span(), "bad substitution");
+
+            if !var_name.is_empty() {
+                let var_ident = syn::parse_str::<Ident>(&var_name).unwrap();
+
+                // To correctly handle all format specifiers (like {:02X}), we need to insert the
+                // entire format string *as a literal* into the format! macro.
+                // The `format_specifier` string itself needs to be embedded.
+                let format_macro_call = if format_specifier.is_empty() {
+                    quote! {
+                        .append(format!("{}", #var_ident))
+                    }
                 } else {
-                    iter.next();
-                }
-            }
-            if !var.is_empty() {
-                let var = syn::parse_str::<Ident>(&var).unwrap();
-                output.extend(quote!(.append(#var.as_os_str())));
+                    let format_literal_str = format!("{{:{}}}", format_specifier);
+                    let format_literal_token = Literal::string(&format_literal_str);
+                    quote! {
+                        .append(format!(#format_literal_token, #var_ident))
+                    }
+                };
+                output.extend(format_macro_call);
             } else {
+                // This covers cases like "${}" or "${:?}" with empty variable name
                 output.extend(quote!(.append("$")));
             }
         } else {
-            last_part.push(ch.to_string());
+            current_literal_part.push(ch);
         }
     }
-    seal_last_part(&mut last_part, &mut output);
+
+    // Append any remaining literal part after the loop finishes.
+    seal_current_literal_part(&mut output, &mut current_literal_part);
     output
 }
 
+/// Parses a variable name from the character iterator.
+/// A variable name consists of alphanumeric characters and underscores,
+/// and cannot start with a digit.
+fn parse_variable_name(chars: &mut Peekable<Chars<'_>>) -> String {
+    let mut var = String::new();
+    while let Some(&c) = chars.peek() {
+        if !(c.is_ascii_alphanumeric() || c == '_') {
+            break;
+        }
+        if var.is_empty() && c.is_ascii_digit() {
+            // Variable names cannot start with a digit
+            break;
+        }
+        var.push(c);
+        chars.next(); // Consume the character
+    }
+    var
+}
+
 enum SepToken {
     Space,
     SemiColon,