gdb/python: new styling argument to gdb.execute

Currently, gdb.execute emits styled output when the command is sending
its output to GDB's stdout, and produces unstyled output when the
output is going to a string.

But it is not unreasonable that a user might wish to capture styled
output from a gdb.execute call, for example, the user might want to
display the styled output are part of some larger UI output block.

At the same time, I don't think it makes sense to always produce
styled output when capturing the output in a string; if what the user
wants is to parse the output, then the style escape sequences make
this far harder.

I propose that gdb.execute gain a new argument 'styling'.  When False
we would always produce unstyled output, and when True we would
produce styled output if styling is not disabled by some other means.

For example, if GDB's 'set style enabled' is off, then I think
gdb.execute() should respect that.  My assumption here is that
gdb.execute() might be executed by some extension.  If the extension
thinks "styled output world work here", but the user hates styled
output, and has turned it off, then the extension should not be
forcing styled output on the user.

I chose 'styling' instead of 'styled' as the Python argument name
because we already use 'styling' in gdb.Value.format_string, and we
don't use 'styled' anywhere else.  This is only a little bit of
consistency, but I still think it's a good thing.

The default for 'styling' will change depending on where the output is
going.  When gdb.execute is sending the output to GDB's stdout then
the default for 'styling' is True.  When the output is going to a
string, then the default for 'styling' will be False.  Not only does
this match the existing behaviour, but I think this makes sense.  By
default we assume that output captured in a string is going to be
parsed, and therefore styling markup is unhelpful, while output going
to stdout should receive styling.

This fixes part of the problem described in PR gdb/32676.  That bug
tries to capture styled source listing in a string, which wasn't
previously possible.

There are some additional issues with capturing source code; GDB
caches the source code in the source code cache.  However, GDB doesn't
check if the cached content is styled or not.  As a consequence, if
the first time the source of a file is shown it is unstyled, then the
cached will hold the unstyled source code, and future requests will
return that unstyled source.  I'll address this issue in a separate
patch.

Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32676

Approved-By: Tom Tromey <tom@tromey.com>

1 files changed, 109 insertions, 0 deletions

diff --git a/gdb/testsuite/gdb.python/py-styled-execute.exp b/gdb/testsuite/gdb.python/py-styled-execute.exp
new file mode 100644
index 0000000..0b27c63
--- /dev/null
+++ b/gdb/testsuite/gdb.python/py-styled-execute.exp
@@ -0,0 +1,109 @@
+# Copyright (C) 2025 Free Software Foundation, Inc.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Check the the output of gdb.execute can be styled or not depending
+# on the value of the third argument passed to gdb.execute.
+
+require allow_python_tests
+
+load_lib gdb-python.exp
+
+# Use gdb.execute() to run CMD passing different argument values.  The
+# output should match either STYLED_RE or UNSTYLED_RE depending on
+# whether the 'styling' argument is True or False.
+proc do_gdb_execute { cmd styled_re unstyled_re } {
+    gdb_test "python gdb.execute('$cmd')" $styled_re
+
+    foreach from_tty { True False } {
+	gdb_test \
+	    "python gdb.execute('$cmd', $from_tty)" \
+	    $styled_re
+	gdb_test \
+	    "python gdb.execute('$cmd', $from_tty, False)" \
+	    $styled_re
+	gdb_test \
+	    "python gdb.execute('$cmd', $from_tty, False, True)" \
+	    $styled_re
+	gdb_test \
+	    "python gdb.execute('$cmd', $from_tty, False, False)" \
+	    $unstyled_re
+	gdb_test \
+	    "python print(gdb.execute('$cmd', $from_tty, True), end='')" \
+	    $unstyled_re
+	gdb_test \
+	    "python print(gdb.execute('$cmd', $from_tty, True, False), end='')" \
+	    $unstyled_re
+	gdb_test \
+	    "python print(gdb.execute('$cmd', $from_tty, True, True), end='')" \
+	    $styled_re
+    }
+}
+
+# Test that the output from gdb.execute is styled or not based on the
+# arguments passed in.
+proc test_gdb_execute_styling {} {
+    clean_restart
+
+    # Two possible outputs, BASIC_RE, the unstyled output text, or
+    # STYLED_RE, the same things, but with styling applied.
+    set text "\"version\" style"
+    set styled_text \
+	[style "\"" version][style "version" version][style "\" style" version]
+    set basic_re "The $text foreground color is: \[^\r\n\]+"
+    set styled_re "The $styled_text foreground color is: \[^\r\n\]+"
+
+    # The command we'll run.  It's output matches the above regexp.
+    set show_style_version_cmd "show style version foreground"
+
+    # Another command we'll run.  The output of this command is never
+    # styled, but we run this to check that the output doesn't change
+    # even when gdb.execute() asks for styled, or unstyled output.
+    set show_style_enabled_cmd "show style enabled"
+
+    with_test_prefix "with style enabled on" {
+	do_gdb_execute $show_style_version_cmd $styled_re $basic_re
+
+	# This time, print the value of 'show style enabled'.  This
+	# output is unstyled, so there's only one regexp.  The
+	# interesting thing here is that we don't expect the output to
+	# change, even when gdb.execute() is printing unstyled output.
+	# The "styling=False" argument to gdb.execute() is separate to
+	# the 'set style enabled on|off' setting.
+	set re "CLI output styling is enabled\\."
+	do_gdb_execute $show_style_enabled_cmd $re $re
+    }
+
+    gdb_test_no_output "set style enabled off"
+
+    with_test_prefix "with style enabled off" {
+	# With 'set style enabled off' in use, even a request to
+	# gdb.execute() to produce styled output should produce
+	# unstyled output.  The assumption is that 'set style enabled
+	# off' is done by the user, while the gdb.execute() is likely
+	# from some Python extension.  The users request for no
+	# styling overrules the extensions request for styled output.
+	do_gdb_execute $show_style_version_cmd $basic_re $basic_re
+
+	# Now check that even when we request styled output, the 'show
+	# style enabled' value is always reported as disabled.
+	set re "CLI output styling is disabled\\."
+	do_gdb_execute $show_style_enabled_cmd $re $re
+    }
+}
+
+# Run the tests.
+with_ansi_styling_terminal {
+    test_gdb_execute_styling
+}