[lldb][docs] Document new frame-format variables

[Michael137]

Documents #131836

[Michael137]

Need to reformat things a bit

[llvmbot]

@llvm/pr-subscribers-lldb

Author: Michael Buch (Michael137)

Changes

Documents #131836

---

Full diff: https://github.com/llvm/llvm-project/pull/137522.diff

1 Files Affected:

• (modified) lldb/docs/use/formatting.rst (+49-1)

diff --git a/lldb/docs/use/formatting.rst b/lldb/docs/use/formatting.rst
index 7b3f01eebc891..6063a47e279f0 100644
--- a/lldb/docs/use/formatting.rst
+++ b/lldb/docs/use/formatting.rst
@@ -85,10 +85,24 @@ A complete list of currently supported format string variables is listed below:
 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | ``function.name``                                 | The name of the current function or symbol.                                                                                                                                                                                                                                                 |
 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``function.name-with-args``                       | The name of the current function with arguments and values or the symbol name.                                                                                                                                                                                                              |
+| ``function.name-with-args``                       | The name of the current function with arguments and values or the symbol name. The name will be displayed according to the current frame's language if possible. |
 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | ``function.name-without-args``                    | The name of the current function without arguments and values (used to include a function name in-line in the ``disassembly-format``)                                                                                                                                                       |
 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``function.basename``                    | The basename of the current function depending on the frame's language. E.g., for C++ the basename for `void ns::foo<float>::bar<int>(int) const` is `bar`.                                                                                                                                                        |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``function.scope``                    |  The scope qualifiers of the current function depending on the frame's language. E.g., for C++ the scope for `void ns::foo<float>::bar<int>(int) const` is `ns::foo<float>`.                                                                                                                                                      |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``function.template-arguments``                    | The template arguments of the current function depending on the frame's language. E.g., for C++ the template arguments for `void ns::foo<float>::bar<int>(int) const` are `<float>`. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``function.formatted-arguments``                    | Arguments of the current function, formatted according to the frame's language. When debug-info is available, will apply data-formatters to each argument and include it's name if available. Otherwise prints the type of each argument according to the mangling. E.g., for C++ the pretty-printed arguments for `func(int x, const char \*str)` are `(x=10, str="Hello")`. Without debug-info it would be `(int, const char\*)`. | 
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``function.qualifiers``                    | The function CV and reference qualifiers of the current function depending on the frame's language. E.g., for C++ the qualifiers for `void ns::foo<float>::bar<int>(int) const &` are ` const &`. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``function.return-left``                    | The return type to the left of the demangled function name of the current function. This depends on the frame's language. E.g., for C++ the `function.return-left` is in most-cases the entirety of the return type. In `void ns::foo(int)` that would be `void `. However, in some cases, particularly for functions returning function pointers, part of the return type is to the right of the function name. E.g., for `void (\*ns::func(float))(int)` the `function.return-left` would be `void (\*` and the `function.return-right` would be `)(int)`. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``function.return-right``                    | The return type to the right of the demangled function name of the current function. This depends on the frame's language. In `void ns::foo(int)` there is no `function.return-right` so this would correspond to an empty string. However, in some cases, particularly for functions returning function pointers, part of the return type is to the right of the function name. E.g., for `void (\*ns::func(float))(int)` the `function.return-left` would be `void (\*` and the `function.return-right` would be `)(int)`. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | ``function.mangled-name``                         | The mangled name of the current function or symbol.                                                                                                                                                                                                                                         |
 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | ``function.pc-offset``                            | The program counter offset within the current function or symbol                                                                                                                                                                                                                            |
@@ -300,3 +314,37 @@ you would see output like:
 
    * Thread main has 21 frames
 
+Function Name Formats
+_____________________
+
+The function names displayed in backtraces/``frame info``/``thread info`` are the demangled names of functions. On some platforms (like ones using Itanium the mangling scheme), LLDB supports decomposing these names into fine-grained components. These are currently:
+* ``${function.return-left}``
+* ``${function.scope}``
+* ``${function.basename}``
+* ``${function.template-arguments}``
+* ``${function.formatted-arguments}``
+* ``${function.qualifiers}``
+* ``${function.return-right}``
+
+Each language plugin decides how to handle these variables. For C++, LLDB uses these variables to dictate how function names are formatted. This can be customized using the ``plugin.cplusplus.display.function-name-format`` LLDB setting.
+
+E.g., the following setting would reconstruct the entire function name (and is LLDB's default):
+
+::
+
+    (lldb) settings set plugin.cplusplus.dislpay.function-name-format "${function.return-left}${function.scope}${function.basename}${function.template-arguments}${function.formatted-arguments}${function.qualifiers}${function.return-right}"
+
+If a user wanted to omit the return type and template arguments of C++ function names one could do:
+
+::
+
+    (lldb) settings set plugin.cplusplus.dislpay.function-name-format "${function.scope}${function.basename}${function.formatted-arguments}${function.qualifiers}"
+
+
+Then the following would highlight just the basename in green:
+
+::
+
+    (lldb) settings set plugin.cplusplus.dislpay.function-name-format "${function.scope}${ansi.fg.yellow}${function.basename}${ansi.normal}${function.formatted-arguments}${function.qualifiers}"
+
+The ``${function.name-with-args}`` by default asks the language plugin whether it supports a language-specific ``function-name-format`` (e.g., the ``plugin.cplusplus.display.function-name-format`` for C++), and if it does, uses it. Otherwise it will display the demangled function name.

[JDevlieghere]

LGTM but please format the table before merging.