1 // Copyright 2025 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #![no_std] 15 16 pub use pw_log_backend_api::LogLevel; 17 18 // Re-export dependencies of `pw_log` macros to be accessed via `$crate::__private`. 19 #[doc(hidden)] 20 pub mod __private { 21 pub use crate::*; 22 pub use pw_log_backend::{pw_log_backend, pw_logf_backend}; 23 } 24 25 /// Emit a log message using `core::fmt` format string semantics if condition is true. 26 /// 27 /// `log_if` takes an `expr` condition, a [`LogLevel`], a `core::fmt` style format string, 28 /// and necessary arguments to that string and emits a log message to the logging backend. 29 /// 30 /// ``` 31 /// use pw_log::LogLevel; 32 /// use log_if::log_if; 33 /// 34 /// const LOG_FACTS: bool = true; 35 /// log_if!(LOG_FACTS, LogLevel::Info, "Log fact: A {} log has a Janka hardness of {} lbf.", 36 /// "Spruce Pine" as &str, 700 as i32); 37 /// ``` 38 #[macro_export] 39 macro_rules! log_if { 40 ($condition:expr, $log_level:expr, $format_string:literal) => {{ 41 if $condition { 42 use $crate::__private as __pw_log_crate; 43 $crate::__private::pw_log_backend!($log_level, $format_string) 44 } 45 }}; 46 47 ($condition:expr, $log_level:expr, $format_string:literal, $($args:expr),*) => {{ 48 if $condition { 49 use $crate::__private as __pw_log_crate; 50 $crate::__private::pw_log_backend!($log_level, $format_string, $($args),*) 51 } 52 }}; 53 } 54 55 /// Emit a log message using `printf` format string semantics if condition is true. 56 /// 57 /// `logf_if` takes an `expr` condition, a [`LogLevel`], a `printf` style format string, 58 /// and necessary arguments to that string and emits a log message to the logging backend. 59 /// 60 /// ``` 61 /// use pw_log::LogLevel; 62 /// use log_if::logf_if; 63 /// 64 /// const LOG_FACTS: bool = true; 65 /// logf_if!(LOG_FACTS, LogLevel::Info, "Log fact: A %s log has a Janka hardness of %d lbf.", 66 /// "Spruce Pine", 700); 67 /// ``` 68 #[macro_export] 69 macro_rules! logf_if { 70 ($condition:expr, $log_level:expr, $format_string:literal) => {{ 71 if $condition { 72 use $crate::__private as __pw_log_crate; 73 $crate::__private::pw_logf_backend!($log_level, $format_string) 74 } 75 }}; 76 77 ($condition:expr, $log_level:expr, $format_string:literal, $($args:expr), *) => {{ 78 if $condition { 79 use $crate::__private as __pw_log_crate; 80 $crate::__private::pw_logf_backend!($log_level, $format_string, $($args), *) 81 } 82 }}; 83 } 84 85 /// Emit a debug level log message using `core:fmt` format string semantics if condition 86 /// is true. 87 /// 88 /// ``` 89 /// use log_if::debug_if; 90 /// 91 /// const LOG_FACTS: bool = true; 92 /// debug_if!(LOG_FACTS, "Log Fact: The American toy Lincoln Logs were inspired by the {} in {}.", 93 /// "Imperial Hotel" as &str, "Tokyo" as &str); 94 /// ``` 95 #[macro_export] 96 macro_rules! debug_if { 97 ($condition:expr, $($args:expr), *) => {{ 98 use $crate::__private as __pw_log_crate; 99 __pw_log_crate::log_if!($condition, __pw_log_crate::LogLevel::Debug, $($args), *) 100 }}; 101 } 102 103 /// Emit a debug level log message using `printf` format string semantics if condition 104 /// is true. 105 /// 106 /// ``` 107 /// use log_if::debugf_if; 108 /// 109 /// const LOG_FACTS: bool = true; 110 /// debugf_if!(LOG_FACTS, "Log Fact: The American toy Lincoln Logs were inspired by the %s in %s.", 111 /// "Imperial Hotel", "Tokyo"); 112 /// ``` 113 #[macro_export] 114 macro_rules! debugf_if { 115 ($condition:expr, $($args:expr), *) => {{ 116 use $crate::__private as __pw_log_crate; 117 __pw_log_crate::logf_if!($condition, __pw_log_crate::LogLevel::Debug, $($args), *) 118 }}; 119 } 120 121 /// Emit an info level log message using `core:fmt` format string semantics if condition is true. 122 /// 123 /// ``` 124 /// use log_if::info_if; 125 /// 126 /// const LOG_FACTS: bool = true; 127 /// info_if!( 128 /// LOG_FACTS, 129 /// "Log Fact: The American president Abraham Lincoln (born {:x}) once lived in a log cabin.", 130 /// 0x1809 as u32); 131 /// ``` 132 #[macro_export] 133 macro_rules! info_if { 134 ($condition:expr, $($args:expr), *) => {{ 135 use $crate::__private as __pw_log_crate; 136 __pw_log_crate::log_if!($condition, __pw_log_crate::LogLevel::Info, $($args), *) 137 }}; 138 } 139 140 /// Emit an info level log message using `printf` format string semantics if condition is true. 141 /// 142 /// ``` 143 /// use log_if::infof_if; 144 /// 145 /// const LOG_FACTS: bool = true; 146 /// infof_if!( 147 /// LOG_FACTS, 148 /// "Log Fact: The American president Abraham Lincoln (born %x) once lived in a log cabin.", 149 /// 0x1809); 150 /// ``` 151 #[macro_export] 152 macro_rules! infof_if { 153 ($condition:expr, $($args:expr), *) => {{ 154 use $crate::__private as __pw_log_crate; 155 __pw_log_crate::logf_if!($condition, __pw_log_crate::LogLevel::Info, $($args), *) 156 }}; 157 } 158 159 /// Emit a warn level log message using `core::fmt` format string semantics if condition is true. 160 /// 161 /// ``` 162 /// use log_if::warn_if; 163 /// 164 /// const LOG_FACTS: bool = true; 165 /// warn_if!( 166 /// LOG_FACTS, 167 /// "Log Fact: Made from a log, an {} year old dugout canoe is the oldest discovered boat in {}.", 168 /// 8000 as i32, "Africa" as &str); 169 /// ``` 170 #[macro_export] 171 macro_rules! warn_if { 172 ($condition:expr, $($args:expr), *) => {{ 173 use $crate::__private as __pw_log_crate; 174 __pw_log_crate::log_if!($condition, __pw_log_crate::LogLevel::Warn, $($args), *) 175 }}; 176 } 177 178 /// Emit a warn level log message using `printf` format string semantics if condition is true. 179 /// 180 /// ``` 181 /// use log_if::warnf_if; 182 /// 183 /// const LOG_FACTS: bool = true; 184 /// warnf_if!( 185 /// LOG_FACTS, 186 /// "Log Fact: Made from a log, an %d year old dugout canoe is the oldest discovered boat in %s.", 187 /// 8000, "Africa"); 188 /// ``` 189 #[macro_export] 190 macro_rules! warnf_if { 191 ($condition:expr, $($args:expr), *) => {{ 192 use $crate::__private as __pw_log_crate; 193 __pw_log_crate::logf_if!($condition, __pw_log_crate::LogLevel::Warn, $($args), *) 194 }}; 195 } 196 197 /// Emit an error level log message using `core::fmt` format string semantics if 198 /// condition is true. 199 /// 200 /// ``` 201 /// use log_if::error_if; 202 /// 203 /// const LOG_FACTS: bool = true; 204 /// error_if!( 205 /// LOG_FACTS, 206 /// "Log Fact: Before saws were invented, the {} was used prepare logs for use.", 207 /// "adze" as &str); 208 /// ``` 209 #[macro_export] 210 macro_rules! error_if { 211 ($condition:expr, $($args:expr), *) => {{ 212 use $crate::__private as __pw_log_crate; 213 __pw_log_crate::log_if!($condition, __pw_log_crate::LogLevel::Error, $($args), *) 214 }}; 215 } 216 217 /// Emit an error level log message using `printf` format string semantics if condition 218 /// is true. 219 /// 220 /// ``` 221 /// use log_if::errorf_if; 222 /// 223 /// const LOG_FACTS: bool = true; 224 /// errorf_if!( 225 /// LOG_FACTS, 226 /// "Log Fact: Before saws were invented, the %s was used prepare logs for use.", 227 /// "adze"); 228 /// ``` 229 #[macro_export] 230 macro_rules! errorf_if { 231 ($condition:expr, $($args:expr), *) => {{ 232 use $crate::__private as __pw_log_crate; 233 __pw_log_crate::logf_if!($condition, __pw_log_crate::LogLevel::Error, $($args), *) 234 }}; 235 } 236 237 /// Emit a critical level log message using `core::fmt` format string semantics if condition 238 /// is true. 239 /// 240 /// ``` 241 /// use log_if::critical_if; 242 /// 243 /// const LOG_FACTS: bool = true; 244 /// critical_if!( 245 /// LOG_FACTS, 246 /// "Log Fact: Until the {}th century, all ships' masts were made from a single log.", 247 /// 19 as u32); 248 /// ``` 249 #[macro_export] 250 macro_rules! critical_if { 251 ($condition:expr, $($args:expr), *) => {{ 252 use $crate::__private as __pw_log_crate; 253 __pw_log_crate::log_if!($condition, __pw_log_crate::LogLevel::Critical, $($args), *) 254 }}; 255 } 256 257 /// Emit a critical level log message using `printf` format string semantics if condition 258 /// is true. 259 /// 260 /// ``` 261 /// use log_if::criticalf_if; 262 /// 263 /// const LOG_FACTS: bool = true; 264 /// criticalf_if!( 265 /// LOG_FACTS, 266 /// "Log Fact: Until the %dth century, all ships' masts were made from a single log.", 267 /// 19); 268 /// ``` 269 #[macro_export] 270 macro_rules! criticalf_if { 271 ($condition:expr, $($args:expr), *) => {{ 272 use $crate::__private as __pw_log_crate; 273 __pw_log_crate::logf_if!($condition, __pw_log_crate::LogLevel::Critical, $($args), *) 274 }}; 275 } 276 277 /// Emit a fatal level log message using `core::fmt` format string semantics if 278 /// condition is true. 279 /// 280 /// *Note*: `fatal` only emits a log message and does not cause a `panic!()` 281 /// 282 /// ``` 283 /// use log_if::fatal_if; 284 /// 285 /// const LOG_FACTS: bool = true; 286 /// fatal_if!(LOG_FACTS, "Log Fact: All out of log facts! Timber!"); 287 /// ``` 288 #[macro_export] 289 macro_rules! fatal_if { 290 ($condition:expr, $($args:expr), *) => {{ 291 use $crate::__private as __pw_log_crate; 292 __pw_log_crate::log_if!($condition, __pw_log_crate::LogLevel::Fatal, $($args), *) 293 }}; 294 } 295 296 /// Emit a fatal level log message using `printf` format string semantics if 297 /// condition is true. 298 /// 299 /// *Note*: `fatalf` only emits a log message and does not cause a `panic!()` 300 /// 301 /// ``` 302 /// use log_if::fatalf_if; 303 /// 304 /// const LOG_FACTS: bool = true; 305 /// fatalf_if!(LOG_FACTS, "Log Fact: All out of log facts! Timber!"); 306 /// ``` 307 #[macro_export] 308 macro_rules! fatalf_if { 309 ($condition:expr, $($args:expr), *) => {{ 310 use $crate::__private as __pw_log_crate; 311 __pw_log_crate::logf_if!($condition, __pw_log_crate::LogLevel::Fatal, $($args), *) 312 }}; 313 } 314