Merge pull request #1279 from cppalliance/pretty_printers

Add LLDB pretty printers and doc page on how to use them

Author: mborland

doc/modules/ROOT/images/dec32_debug.png

@@ -15,6 +15,7 @@
 * xref:financial_examples.adoc[]
 ** xref:financial_examples.adoc#examples_money_parsing[Parsing Pricing Data from File]
 ** xref:financial_examples.adoc#examples_boost_math[Boost.Math Integration]
+* xref:debugger.adoc[]
 * xref:api_reference.adoc[]
 ** xref:api_reference.adoc#api_ref_types[Types]
 ** xref:api_reference.adoc#api_ref_structs[Structs]

doc/modules/ROOT/images/dec32_fast_debug.png

@@ -0,0 +1,41 @@
+////
+Copyright 2025 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#debug]
+= Debugger Support
+:idprefix: debug_
+
+Currently, Boost.Decimal supports pretty printing with LLDB.
+To load the pretty printer, add the following line to your `.lldbinit`:
+
+[source]
+----
+command script import /path/to/decimal/extra/decimal_printer.py
+----
+
+Once you have loaded `decimal_printer.py` you can run the following example to see how different values are represented with the pretty printer.
+
+.The following example can be run with the debugger to show a variety of values
+====
+
+[source,c++]
+----
+include::example$debugger.cpp[]
+----
+
+*_Expected Output for T = decimal32_t:_*
+
+image::dec32_debug.png[]
+
+*_Expected Output for T = decimal_fast32_t:_*
+
+image::dec32_fast_debug.png[]
+====
+
+The reason for the difference in how `decimal32_t` and `decimal_fast32_t` is displayed is due to xref:cohorts.adoc[Cohorts and Normalization]
+
+. `decimal32_t`, `decimal64_t` and `decimal128_t` debuggers are cohort preserving
+. `decimal_fast32_t`, `decimal_fast64_t` and `decimal_fast128_t` debuggers are always normalized

doc/modules/ROOT/nav.adoc

@@ -0,0 +1,59 @@
+// Copyright 2025 Matt Borland
+// Distributed under the Boost Software License, Version 1.0.
+// https://www.boost.org/LICENSE_1_0.txt
+//
+// This example, when run with the pretty printers, shows how various values are represented
+
+#include <boost/decimal/decimal32_t.hpp>        // For type decimal32_t
+#include <boost/decimal/decimal64_t.hpp>        // For type decimal64_t
+#include <boost/decimal/decimal128_t.hpp>       // For type decimal128_t
+#include <boost/decimal/decimal_fast32_t.hpp>   // For type decimal_fast32_t
+#include <boost/decimal/cmath.hpp>              // For nan function to write payload to nans
+#include <limits>
+
+template <typename T>
+void debug_values()
+{
+    // Displays the maximum and minimum values that the type can hold
+    // from numeric_limits
+    const T max {std::numeric_limits<T>::max()};
+    const T min {std::numeric_limits<T>::min()};
+
+    // A number whose representation will change based on IEEE vs fast type
+    // In the IEEE case 3.140e+00 will be displayed as the pretty printer is cohort preserving
+    const T short_num {"3.140"};
+
+    // Shows how infinities will be displayed
+    const T pos_inf {std::numeric_limits<T>::infinity()};
+    const T neg_inf {-std::numeric_limits<T>::infinity()};
+
+    // Shows how the different kinds of NANs will be displayed
+    const T qnan {std::numeric_limits<T>::quiet_NaN()};
+    const T snan {std::numeric_limits<T>::signaling_NaN()};
+
+    // Shows how a payload added to a QNAN will be displayed
+    const T payload_nan {boost::decimal::nan<T>("7")};
+
+    // Break Here:
+    static_cast<void>(max);
+    static_cast<void>(min);
+    static_cast<void>(short_num);
+    static_cast<void>(pos_inf);
+    static_cast<void>(neg_inf);
+    static_cast<void>(qnan);
+    static_cast<void>(snan);
+    static_cast<void>(payload_nan);
+}
+
+int main()
+{
+    debug_values<boost::decimal::decimal32_t>();
+    debug_values<boost::decimal::decimal64_t>();
+    debug_values<boost::decimal::decimal128_t>();
+
+    debug_values<boost::decimal::decimal_fast32_t>();
+    debug_values<boost::decimal::decimal_fast64_t>();
+    debug_values<boost::decimal::decimal_fast128_t>();
+
+    return 0;
+}

doc/modules/ROOT/pages/debugger.adoc

@@ -0,0 +1,230 @@
+# Copyright 2025 Matt Borland
+# Distributed under the Boost Software License, Version 1.0.
+# https://www.boost.org/LICENSE_1_0.txt
+
+from detail.decode_ieee_type import decode_decimal32
+from detail.decode_ieee_type import decode_decimal64
+from detail.decode_ieee_type import decode_decimal128
+from detail.decode_fast_type import decode_decimal_fast32
+from detail.decode_fast_type import decode_decimal_fast64
+from detail.decode_fast_type import decode_decimal_fast128
+
+import lldb
+
+def decimal32_summary(valobj, internal_dict):
+    """
+    Custom summary for decimal32_t type
+    Displays in scientific notation with cohort preservation
+    """
+
+    try:
+        val = valobj.GetNonSyntheticValue()
+        bits = val.GetChildMemberWithName("bits_").GetValueAsUnsigned()
+        return decode_decimal32(bits)
+
+    except Exception as e:
+        return f"<invalid decimal32_t: {e}>"
+
+def decimal64_summary(valobj, internal_dict):
+    """
+    Custom summary for decimal64_t type
+    Displays in scientific notation with cohort preservation
+    """
+
+    try:
+        val = valobj.GetNonSyntheticValue()
+        bits = val.GetChildMemberWithName("bits_").GetValueAsUnsigned()
+        return decode_decimal64(bits)
+
+    except Exception as e:
+        return f"<invalid decimal64_t: {e}>"
+
+def decimal128_summary(valobj, internal_dict):
+    """
+    Custom summary for decimal128_t type
+    Displays in scientific notation with cohort preservation
+    """
+
+    try:
+        val = valobj.GetNonSyntheticValue()
+        bits = val.GetChildMemberWithName("bits_")
+        bits_high = bits.GetChildMemberWithName("high").GetValueAsUnsigned()
+        bits_low = bits.GetChildMemberWithName("low").GetValueAsUnsigned()
+        combined_bits = (bits_high << 64) | bits_low
+        return decode_decimal128(combined_bits)
+
+    except Exception as e:
+        return f"<invalid decimal128_t: {e}>"
+
+def decimal_fast32_summary(valobj, internal_dict):
+    """
+    Custom summary for decimal_fast32_t type
+    Displays in scientific notation
+    """
+
+    try:
+        val = valobj.GetNonSyntheticValue()
+        significand = val.GetChildMemberWithName("significand_").GetValueAsUnsigned()
+        exp = val.GetChildMemberWithName("exponent_").GetValueAsUnsigned()
+        sign = val.GetChildMemberWithName("sign_").GetValueAsUnsigned()
+        return decode_decimal_fast32(significand, exp, sign)
+
+    except Exception as e:
+        return f"<invalid decimal_fast32_t: {e}>"
+
+def decimal_fast64_summary(valobj, internal_dict):
+    """
+    Custom summary for decimal_fast64_t type
+    Displays in scientific notation
+    """
+
+    try:
+        val = valobj.GetNonSyntheticValue()
+        significand = val.GetChildMemberWithName("significand_").GetValueAsUnsigned()
+        exp = val.GetChildMemberWithName("exponent_").GetValueAsUnsigned()
+        sign = val.GetChildMemberWithName("sign_").GetValueAsUnsigned()
+        return decode_decimal_fast64(significand, exp, sign)
+
+    except Exception as e:
+        return f"<invalid decimal_fast64_t: {e}>"
+def decimal_fast128_summary(valobj, internal_dict):
+    """
+    Custom summary for decimal_fast128_t type
+    Displays in scientific notation
+    """
+
+    try:
+        val = valobj.GetNonSyntheticValue()
+
+        significand = val.GetChildMemberWithName("significand_")
+        bits_high = significand.GetChildMemberWithName("high").GetValueAsUnsigned()
+        bits_low = significand.GetChildMemberWithName("low").GetValueAsUnsigned()
+        combined_bits = (bits_high << 64) | bits_low
+
+        exp = val.GetChildMemberWithName("exponent_").GetValueAsUnsigned()
+        sign = val.GetChildMemberWithName("sign_").GetValueAsUnsigned()
+
+        return decode_decimal_fast128(combined_bits, exp, sign)
+
+    except Exception as e:
+        return f"<invalid decimal_fast128_t: {e}>"
+
+def __lldb_init_module(debugger, internal_dict):
+    decimal32_pattern = r"^(const )?(boost::decimal::decimal32_t|(\w+::)*decimal32_t)( &| \*)?$"
+    decimal64_pattern = r"^(const )?(boost::decimal::decimal64_t|(\w+::)*decimal64_t)( &| \*)?$"
+    decimal128_pattern = r"^(const )?(boost::decimal::decimal128_t|(\w+::)*decimal128_t)( &| \*)?$"
+
+    decimal_fast32_pattern = r"^(const )?(boost::decimal::decimal_fast32_t|(\w+::)*decimal_fast32_t)( &| \*)?$"
+    decimal_fast64_pattern = r"^(const )?(boost::decimal::decimal_fast64_t|(\w+::)*decimal_fast64_t)( &| \*)?$"
+    decimal_fast128_pattern = r"^(const )?(boost::decimal::decimal_fast128_t|(\w+::)*decimal_fast128_t)( &| \*)?$"
+
+    debugger.HandleCommand(
+        f'type summary add -x "{decimal32_pattern}" -e -F decimal_printer.decimal32_summary'
+    )
+    debugger.HandleCommand(
+        f'type synthetic add -x "{decimal32_pattern}" -l decimal_printer.DecimalSyntheticProvider'
+    )
+
+    print("decimal32_t printer loaded successfully")
+
+    debugger.HandleCommand(
+        f'type summary add -x "{decimal64_pattern}" -e -F decimal_printer.decimal64_summary'
+    )
+    debugger.HandleCommand(
+        f'type synthetic add -x "{decimal64_pattern}" -l decimal_printer.DecimalSyntheticProvider'
+    )
+
+    print("decimal64_t printer loaded successfully")
+
+    debugger.HandleCommand(
+        f'type summary add -x "{decimal128_pattern}" -e -F decimal_printer.decimal128_summary'
+    )
+    debugger.HandleCommand(
+        f'type synthetic add -x "{decimal128_pattern}" -l decimal_printer.DecimalSyntheticProvider'
+    )
+
+    print("decimal128_t printer loaded successfully")
+
+    debugger.HandleCommand(
+        f'type summary add -x "{decimal_fast32_pattern}" -e -F decimal_printer.decimal_fast32_summary'
+    )
+    debugger.HandleCommand(
+        f'type synthetic add -x "{decimal_fast32_pattern}" -l decimal_printer.DecimalFastSyntheticProvider'
+    )
+
+    print("decimal_fast32_t printer loaded successfully")
+
+    debugger.HandleCommand(
+        f'type summary add -x "{decimal_fast64_pattern}" -e -F decimal_printer.decimal_fast64_summary'
+    )
+    debugger.HandleCommand(
+        f'type synthetic add -x "{decimal_fast64_pattern}" -l decimal_printer.DecimalFastSyntheticProvider'
+    )
+
+    print("decimal_fast64_t printer loaded successfully")
+
+    debugger.HandleCommand(
+        f'type summary add -x "{decimal_fast128_pattern}" -e -F decimal_printer.decimal_fast128_summary'
+    )
+    debugger.HandleCommand(
+        f'type synthetic add -x "{decimal_fast128_pattern}" -l decimal_printer.DecimalFastSyntheticProvider'
+    )
+
+    print("decimal_fast128_t printer loaded successfully")
+
+class DecimalSyntheticProvider:
+    def __init__(self, valobj, internal_dict):
+        self.valobj = valobj
+
+    def num_children(self):
+        return 1
+
+    def get_child_index(self, name):
+        if name == "bits_":
+            return 0
+        return -1
+
+    def get_child_at_index(self, index):
+        if index == 0:
+            return self.valobj.GetChildMemberWithName("bits_")
+        return None
+
+    def update(self):
+        pass
+
+    def has_children(self):
+        return True
+
+class DecimalFastSyntheticProvider:
+    def __init__(self, valobj, internal_dict):
+        self.valobj = valobj
+
+    def num_children(self):
+        return 3
+
+    def get_child_index(self, name):
+        if name == "significand_":
+            return 0
+        elif name == "exponent_":
+            return 1
+        elif name == "sign_":
+            return 2
+        else:
+            return -1
+
+    def get_child_at_index(self, index):
+        if index == 0:
+            return self.valobj.GetChildMemberWithName("significand_")
+        elif index == 1:
+            return self.valobj.GetChildMemberWithName("exponent_")
+        elif index == 2:
+            return self.valobj.GetChildMemberWithName("sign_")
+        else:
+            return None
+
+    def update(self):
+        pass
+
+    def has_children(self):
+        return True
+