gdb/python: add gdb.Style class

This commit adds a new gdb.Style class.  This class represents a
complete style within GDB.  A complete style is a collection of
foreground color, background color, and an intensity.

A gdb.Style comes in two flavours, named, and unnamed.

A named style is one that is based on an existing style within GDB.
For example, we have 'set style filename ...', the name of this style
is 'filename'.  We also have 'set style disassembler mnemonic ...',
the name of this style is 'disassembler mnemonic'.  A named style is
created by passing the name of the style, like this:

  (gdb) python s1 = gdb.Style("filename")
  (gdb) python s2 = gdb.Style("disassembler mnemonic")

The other type of style is an unnamed style.  An unnamed style is
created using a foreground and background color, along with an
intensity.  Colors are specified using gdb.Color objects.  An example
of creating an unnamed style is:

  (gdb) python s3 = gdb.Style(foreground=gdb.Color('red'),
                              background=gdb.Color('green'),
			      intensity=gdb.INTENSITY_BOLD)

We can see here an example of the new intensity constants that have
been added in this commit, there is gdb.INTENSITY_NORMAL,
gdb.INTENSITY_BOLD, and gdb.INTENSITY_DIM.  All of the arguments are
optional, the default for the colors is gdb.Color(), which will apply
the terminal default, and the default intensity is
gdb.INTENSITY_NORMAL.

Having created a gdb.Style object there are two ways that it can be
used to style GDB's output.  The Style.escape_sequence() method
returns the escape sequence needed to apply this style, this can be
used as in:

  (gdb) python print(s1.escape_sequence() + "Filename Style")

The problem with this approach is that it is the users responsibility
to restore the style to the default when they are done.  In the above
example, all output after the escape sequence is printed, including
the next GDB prompt, will be in the s1 (filename) style.  Which is why
the Style.apply method exists.  This method takes a string and returns
the same string with escape sequences added before and after.  The
before sequence switches to the style, while the after escape sequence
restores the terminal default style.  This can be used like:

  (gdb) python print(s1.apply("Filename Style"))

Now only the 'Filename Style' text will be styled.  The next GDB
prompt will be in the default terminal style.  Personally, I think the
apply method is the more useful, but having 'escape_sequence' matches
what gdb.Color offers, though if/when this patch is merged, I might
propose a similar 'apply' type method for the gdb.Color class.

The gdb.Style class has 'foreground', 'background', and 'intensity'
attributes which, when read, return the obvious values.  These
attributes can also be written too.

When writing to an attribute of an unnamed Style object then the Style
object itself is updated, as you might expect.

When writing to an attribute of a named Style then the style setting
itself is updated as the following example shows:

  (gdb) python s1 = gdb.Style("filename")
  (gdb) python print(s1.foreground)
  green
  (gdb) show style filename foreground
  The "filename" style foreground color is: green
  (gdb) python s1.foreground=gdb.Color("red")
  (gdb) python print(s1.foreground)
  red
  (gdb) show style filename foreground
  The "filename" style foreground color is: red
  (gdb)

We can see that a gdb.Style object is connected to the underlying
style settings, it doesn't take a copy of the style settings at
creation time.  And the relationship works both ways.  Continuing the
above example:

  (gdb) set style filename foreground blue
  (gdb) python print(s1.foreground)
  blue
  (gdb)

Here we see that changing the setting value causes the gdb.Style
object to update.  And this is what you would want.  I imagine this
being used in a Python extension to GDB, where a user might create
global objects for some named styles, and then use these globals to
format output from some custom commands.  If a user of an extension
changes a style setting then the extension wants to adapt to that
change.

Both the Style.escape_sequence and Style.apply methods take the global
style enabled setting into consideration.  If styling is disabled then
Style.escape_sequence will return an empty string, and Style.apply
will return an unmodified copy of the original string object (actually
the input object with Py_INCREF applied).

There is also support for representing a gdb.Style as a string:

  (gdb) python s1 = gdb.Style("filename")
  (gdb) python print(s1)
  <gdb.Style name='filename', fg=green, bg=none, intensity=normal>
  (gdb)

Unnamed styles are similar, but don't have a 'name' field.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>

0 files changed, 0 insertions, 0 deletions