[SCM] archer-pmuldoon-python-backtrace: First draft of Frame Wrapper API, and beginning of Frame Filter/Wrapper tutorial

[SCM] archer-pmuldoon-python-backtrace: First draft of Frame Wrapper API, and beginning of Frame Filter/Wrapper tutorial

[pmuldoon]

The branch, archer-pmuldoon-python-backtrace has been updated
       via  d41e9fbcd585abcf20e26ccb449bec2b5359d081 (commit)
      from  21efb231d1aa60794b55884343e4aee5c8e8f22c (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email.

- Log -----------------------------------------------------------------
commit d41e9fbcd585abcf20e26ccb449bec2b5359d081
Author: Phil Muldoon <pmuldoon@redhat.com>
Date:   Fri Nov 9 15:05:02 2012 +0000

    First draft of Frame Wrapper API, and beginning of Frame
    Filter/Wrapper tutorial

-----------------------------------------------------------------------

Summary of changes:
 gdb/doc/gdb.texinfo |  218 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 210 insertions(+), 8 deletions(-)

First 500 lines of diff:
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 3fd2989..5ce4df4 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -22628,8 +22628,8 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
 * Selecting Pretty-Printers::   How GDB chooses a pretty-printer.
 * Writing a Pretty-Printer::    Writing a Pretty-Printer.
 * Frame Filters API::           Filtering and Wrapping Frames.
-* Writing a Frame Filter::      Writing a Frame Filter.
 * Frame Wrapper API::           Wrapping and Decorating Frames.
+* Writing a Frame Filter::      Writing a Frame Filter.
 * Managing Frame Filters::      Management of Frame Filters.
 * Writing a Frame Wrapper::     Writing a Frame Wrapper.
 * Inferiors In Python::         Python representation of inferiors (processes)
@@ -24140,21 +24140,223 @@ valid operation for frame filters that have decided not to operate on
 any frames.
 
 In this next example, the frame filter operates on all frames, and
-uses a @code{Frame Wrapper}. @xref{Frame Wrapper API}, for the API
+uses a Frame Wrapper. @xref{Frame Wrapper API}, for the API
 relating to a @code{Frame Wrapper}. Also, @xref{Writing a Frame
-Wrapper}, for a tutorial on writing a @code{Frame Wrapper}.
+Wrapper}, for a tutorial on writing a Frame Wrapper.
+
+@smallexample
+class Reverse_Function (BaseFrameWrapper):
+
+    def __init__(self, fobj):
+        super(Reverse_Function, self).__init__(fobj)
+        self.fobj = fobj
 
+    def function (self):
+        fname = str (self.fobj.function())
+        fname = fname[::-1]
+        return fname
+
+class FrameFilter ():
+
+    def __init__ (self):
+        self.name = "Reverse Filter"
+        self.priority = 100
+        self.enabled = True
+        gdb.frame_filters [self.name] = self
+
+    def filter (self, frame_iter):
+        frame_iter = itertools.imap (Reverse_Function,
+                                     frame_iter)
+        return frame_iter
+@end smallexample
+
+There are two objects in this example. A Frame Wrapper and a Frame
+Filter. The frame filter in this example uses the Python
+@code{itertool} module to operator on the iterator that was passed to
+it.  
 
 @node Frame Wrapper API 
 @subsubsection Wrapping and Decorating Frames.
 @cindex Frame Wrapper API
 
 Frame wrappers are sister objects that decorate frames affected by
-frame filters.  Frame wrappers are applied by frame filters and
-customize the printed content of each frame via an API.  A frame
-wrapper works on one frame, but a frame wrapper object can be applied
-to many different frames.  Each frame wrapper dictates the contents of
-each frame that is printed by @value{GDBN}.
+frame filters.  Frame wrappers can only be used in conjunction with
+Frame wrappers.
+
+Frame wrappers are applied by frame filters and customize the printed
+content of each frame via an API, defined here.  A frame wrapper works
+on one frame, but a frame wrapper object can be applied to many
+multiple frames.
+
+@defun FrameWrapper.elided ()
+
+The @code{elided} method groups frames together in a hierarchical
+system.  An example would be an interpreter call that occurs over many
+frames but might be better represented as a group of frames distinct
+from the other frames.
+
+The @code{elide} function must return an iterator that conforms to the
+Python iterator protocol, and contains the frames that are being
+elided, or @code{None}.  Elided frames are indented from normal frames
+in a @code{CLI} backtrace, or in the case of @code{GDB/MI} are placed
+in the @code{children} field of the eliding frame.
+
+Note that it is the frame filter that instantiated this frame
+wrapper's task to filter out the elided frames from the source
+iterator.  This will avoid the frame being printed twice. 
+
+If this function returns @code{None}, no frames will be elided.
+@end defun
+
+
+@defun FrameWrapper.function ()
+
+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
+@code{None}.
+
+If this function returns a Python None, @value{GDBN} will not print
+any data for this field.
+@end defun
+
+@defun FrameWrapper.address ()
+
+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 @code{None}.
+
+If this function returns a @code{None}, @value{GDBN} will not print
+any data for this field.
+@end defun
+
+@defun FrameWrapper.filename ()
+
+This method returns the filename associated with this frame.
+
+This method must return a Python string containing the filename, and
+optionally, the path to the filename of the frame, or @code{None}.
+
+If this function returns a @code{None}, @value{GDBN} will not print
+any data for this field.
+@end defun
+
+
+@defun FrameWrapper.line ():
+
+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 @code{None}.
+
+If this function returns a @code{None}, @value{GDBN} will not print
+any data for this field.
+@end defun
+
+@defun FrameWrapper.frame_args ()
+
+This method must return a Python iterator that conforms to the Python
+iterator protocol.  This iterator must contain objects that implement
+two methods, described here.
+
+The object must implement an @code{argument} method which takes no
+parameters and must return a @code{gdb.Symbol} or a Python string, and
+@code{value} method which takes no parameters and which must return a
+@code{gdb.Value}, a Python value, or @code{None}.  If the @code{value}
+method returns a @code{None}, and the @code{argument} method
+returns a @code{gdb.Symbol}, @value{GDBN} will read and print the value
+of the @code{gdb.Symbol} automatically.
+
+A brief example:
+
+@smallexample
+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 SomeFrameWrapper ()
+...
+...
+    def frame_args (self):
+        fvars = []
+        fvars.append (SymValueWrapper (``foo'', 42))
+        
+        return iter (fvars)
+@end smallexample
+
+Even if the @code{frame_args} method returns only a single object, it
+must be wrapped in an iterator.
+
+If this function returns a @code{None}, @value{GDBN} will not print
+locals for this frame.
+@end defun
+
+@defun FrameWrapper.frame_locals ()
+
+This method must return a Python iterator that conforms to the Python
+iterator protocol.  This iterator must contain objects that implement
+two methods, described here.
+
+The object must implement an @code{argument} method which takes no
+parameters and must return a @code{gdb.Symbol} or a Python string, and
+@code{value} method which takes no parameters and which must return a
+@code{gdb.Value}, a Python value, or @code{None}.  If the @code{value}
+method returns a @code{None}, and the @code{argument} method
+returns a @code{gdb.Symbol}, @value{GDBN} will read and print the value
+of the @code{gdb.Symbol} automatically.
+
+A brief example:
+
+@smallexample
+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 SomeFrameWrapper ()
+...
+...
+    def frame_locals (self):
+        fvars = []
+        fvars.append (SymValueWrapper (``foo'', 42))
+        
+        return iter (fvars)
+@end smallexample
+    
+Even if the @code{frame_locals} method returns only a single object, it
+must be wrapped in an iterator.
+
+If this function returns a @code{None}, @value{GDBN} will not print
+locals for this frame.
+
+@end defun
+
+@defun FrameWrapper.frame ():
+
+This method must return the underlying @code{gdb.Frame} that this
+frame wrapper is wrapping.  @value{GDBN} requires the underlying frame
+for internal frame information such as architecture so as to determine
+how to print certain values in frame printing
+@end defun
 
 @node Managing Frame Filters
 @subsubsection Management of Frame Filters.


hooks/post-receive
--
Repository for Project Archer.