1.. _module-pw_log-tokenized-args: 2 3----------------------- 4Tokenized log arguments 5----------------------- 6.. pigweed-module-subpage:: 7 :name: pw_log 8 9The ``pw_log`` facade is intended to make the logging backend invisible to the 10user, but some backend features require additional frontend support, 11necessitating a break in the abstraction. One of these features is the logging 12of nested token arguments in tokenized logs, because only the user is able to 13know which log arguments can be tokens (see :ref:`module-pw_tokenizer` for 14context on tokenization, and :ref:`module-pw_log_tokenized` for an example of 15a tokenized logging backend). Arguments that have already been tokenized are 16just unsigned integers, and not all strings can be compile-time constants, so 17users must be provided with a way of manually marking token arguments. 18 19To this end, ``pw_log/tokenized_args.h`` aliases macros from ``pw_tokenizer`` 20to enable logging nested tokens when the active backend uses tokenization. 21These alias macros revert to plain string logging otherwise, allowing projects 22to take advantage of nested token logging without breaking readable logs when 23the project is built with a different logging backend. To support logging 24nested token arguments, a ``pw_log`` backend must add an empty file 25``log_backend_uses_pw_tokenizer.h`` under ``public_overrides/pw_log_backend/``. 26 27Although the detokenizing backend accepts several different numeric bases, the 28macros currently only support formatting nested tokens in hexadecimal, which 29affects how the arguments appear in final logs if they cannot be detokenized 30for any reason. Undetokenized tokens will appear inline as hex integers 31prefixed with ``$#``, e.g. ``$#34d16466``. 32 33.. doxygendefine:: PW_LOG_TOKEN_TYPE 34.. doxygendefine:: PW_LOG_TOKEN 35.. doxygendefine:: PW_LOG_TOKEN_EXPR 36.. doxygendefine:: PW_LOG_TOKEN_FMT 37 38Example usage with inline string arguments: 39 40.. code-block:: cpp 41 42 #include "pw_log/log.h" 43 #include "pw_log/tokenized_args.h" 44 45 // bool active_ 46 PW_LOG_INFO("Component is " PW_LOG_TOKEN_FMT(), 47 active_ ? PW_LOG_TOKEN_EXPR("active") 48 : PW_LOG_TOKEN_EXPR("idle")); 49 50Example usage with enums: 51 52.. code-block:: cpp 53 54 #include "pw_log/log.h" 55 #include "pw_log/tokenized_args.h" 56 57 namespace foo { 58 59 enum class Color { kRed, kGreen, kBlue }; 60 61 PW_LOG_TOKEN_TYPE ColorToToken(Color color) { 62 switch (color) { 63 case Color::kRed: 64 return PW_LOG_TOKEN_EXPR("kRed"); 65 case Color::kGreen: 66 return PW_LOG_TOKEN_EXPR("kGreen"); 67 case Color::kBlue: 68 return PW_LOG_TOKEN_EXPR("kBlue"); 69 default: 70 return PW_LOG_TOKEN_EXPR("kUnknown"); 71 } 72 } 73 74 } // namespace foo 75 76 void LogColor(foo::Color color) { 77 PW_LOG("Color: [" PW_LOG_TOKEN_FMT() "]", color) 78 } 79