from gdb.FrameDecorator import FrameDecorator

— Function: FrameDecorator.elided (self)

The elided method groups frames together in a hierarchical system. An example would be an interpreter, where multiple low-level frames make up a single call in the interpreted language. In this example, the frame filter would elide the low-level frames and present a single high-level frame, representing the call in the interpreted language, to the user.

The elided function must return an iterable and this iterable must contain the frames that are being elided wrapped in a suitable frame decorator. If no frames are being elided this function may return an empty iterable, or None. Elided frames are indented from normal frames in a CLI backtrace, or in the case of GDB/MI, are placed in the children field of the eliding frame.

It is the frame filter's task to also filter out the elided frames from the source iterator. This will avoid printing the frame twice.

— Function: FrameDecorator.function (self)

This method returns the name of the function in the frame that is to be printed.

This method must return a Python string describing the function, or None.

If this function returns None, gdb will not print any data for this field.

— Function: FrameDecorator.address (self)

This method returns the address of the frame that is to be printed.

This method must return a Python numeric integer type of sufficient size to describe the address of the frame, or None.

If this function returns a None, gdb will not print any data for this field.

— Function: FrameDecorator.filename (self)

This method returns the filename and path associated with this frame.

This method must return a Python string containing the filename and the path to the object file backing the frame, or None.

If this function returns a None, gdb will not print any data for this field.

— Function: FrameDecorator.line (self):

This method returns the line number associated with the current position within the function addressed by this frame.

This method must return a Python integer type, or None.

If this function returns a None, gdb will not print any data for this field.

— Function: FrameDecorator.frame_args (self)

This method must return an iterable, or None. Returning an empty iterable, or None means frame arguments will not be printed for this frame. This iterable must contain objects that implement two methods, described here.

This object must implement a argument method which takes a single self parameter and must return a gdb.Symbol (see Symbols In Python), or a Python string. The object must also implement a value method which takes a single self parameter and must return a gdb.Value (see Values From Inferior), a Python value, or None. If the value method returns None, and the argument method returns a gdb.Symbol, gdb will look-up and print the value of the gdb.Symbol automatically.

A brief example:

          class SymValueWrapper():
          
              def __init__(self, symbol, value):
                  self.sym = symbol
                  self.val = value
          
              def value(self):
                  return self.val
          
              def symbol(self):
                  return self.sym
          
          class SomeFrameDecorator()
          ...
          ...
              def frame_args(self):
                  args = []
                  try:
                      block = self.inferior_frame.block()
                  except:
                      return None
          
                  # Iterate over all symbols in a block.  Only add
                  # symbols that are arguments.
                  for sym in block:
                      if not sym.is_argument:
                          continue
                      args.append(SymValueWrapper(sym,None))
          
                  # Add example synthetic argument.
                  args.append(SymValueWrapper(``foo'', 42))
          
                  return args

— Function: FrameDecorator.frame_locals (self)

This method must return an iterable or None. Returning an empty iterable, or None means frame local arguments will not be printed for this frame.

The object interface, the description of the various strategies for reading frame locals, and the example are largely similar to those described in the frame_args function, (see The frame filter frame_args function). Below is a modified example:

          class SomeFrameDecorator()
          ...
          ...
              def frame_locals(self):
                  vars = []
                  try:
                      block = self.inferior_frame.block()
                  except:
                      return None
          
                  # Iterate over all symbols in a block.  Add all
                  # symbols, except arguments.
                  for sym in block:
                      if sym.is_argument:
                          continue
                      vars.append(SymValueWrapper(sym,None))
          
                  # Add an example of a synthetic local variable.
                  vars.append(SymValueWrapper(``bar'', 99))
          
                  return vars

— Function: FrameDecorator.inferior_frame (self):

This method must return the underlying gdb.Frame that this frame decorator is decorating. gdb requires the underlying frame for internal frame information to determine how to print certain values when printing a frame.