From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 25437 invoked by alias); 24 Aug 2011 15:11:57 -0000 Received: (qmail 25310 invoked by uid 22791); 24 Aug 2011 15:11:47 -0000 X-SWARE-Spam-Status: No, hits=-2.6 required=5.0 tests=AWL,BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW,TW_BJ,TW_RG,T_TO_NO_BRKTS_FREEMAIL X-Spam-Check-By: sourceware.org Received: from mail-yw0-f41.google.com (HELO mail-yw0-f41.google.com) (209.85.213.41) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Wed, 24 Aug 2011 15:11:21 +0000 Received: by ywm13 with SMTP id 13so997955ywm.0 for ; Wed, 24 Aug 2011 08:11:20 -0700 (PDT) Received: by 10.91.55.38 with SMTP id h38mr4951206agk.198.1314198680555; Wed, 24 Aug 2011 08:11:20 -0700 (PDT) Received: from localhost.localdomain (c-98-232-221-4.hsd1.or.comcast.net [98.232.221.4]) by mx.google.com with ESMTPS id d7sm968071anb.40.2011.08.24.08.11.19 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 24 Aug 2011 08:11:20 -0700 (PDT) From: matt rice To: gdb-patches@sourceware.org Cc: matt rice Subject: [PATCH 6/7] [python] API for macros: Add docs. Date: Wed, 24 Aug 2011 15:12:00 -0000 Message-Id: <1314198654-9008-7-git-send-email-ratmice@gmail.com> In-Reply-To: <1314198654-9008-1-git-send-email-ratmice@gmail.com> References: <1314198654-9008-1-git-send-email-ratmice@gmail.com> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2011-08/txt/msg00446.txt.bz2 2011-08-23 Matt Rice * gdb.texinfo (Symbol Tables In Python): Add macros and macro_named methods. (Objfiles In Python): Add symtabs method. (Macros In Python): Add new section. 2011-08-23 Matt Rice * NEWS: Add macros API, and Objfiles symtabs method. --- gdb/NEWS | 7 ++++ gdb/doc/gdb.texinfo | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 0 deletions(-) diff --git a/gdb/NEWS b/gdb/NEWS index 255a22e..a719b07 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -38,6 +38,13 @@ ** Symbols now provide the "type" attribute, the type of the symbol. + ** Objfiles now provide a "symtabs" method. + + ** The Macro object is now available for representing preprocessor macros. + The following objects now have methods for obtaining macro objects. + - Symtab_and_line now has a "macro_named" method + - Symtab now has a "macros" method. + * libthread-db-search-path now supports two special values: $sdir and $pdir. $sdir specifies the default system locations of shared libraries. $pdir specifies the directory where the libpthread used by the application diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 6e7bf52..1073a2e 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -20984,6 +20984,7 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. * Blocks In Python:: Accessing frame blocks from Python. * Symbols In Python:: Python representation of symbols. * Symbol Tables In Python:: Python representation of symbol tables. +* Macros In Python:: Python representation of preprocessor macros. * Lazy Strings In Python:: Python representation of lazy strings. * Breakpoints In Python:: Manipulating breakpoints using Python. @end menu @@ -22986,6 +22987,11 @@ longer. All other @code{gdb.Objfile} methods will throw an exception if it is invalid at the time the method is called. @end defmethod +@defmethod Objfile symtabs +Returns a @code{List} containing the valid @code{gdb.Symtab} objects +for this @code{gdb.Objfile}. +@end defmethod + @node Frames In Python @subsubsection Accessing inferior stack frames from Python. @@ -23446,6 +23452,17 @@ exist in @value{GDBN} any longer. All other @code{gdb.Symtab_and_line} methods will throw an exception if it is invalid at the time the method is called. @end defmethod + +@defmethod Symtab_and_line macro_named @r{[}name@r{]} +Returns a @code{gdb.Macro} object, for the macro +with the given name. +@end defmethod + +@defmethod Symtab_and_line macros +Returns all of the macros which are defined and not undefined or redefined, +prior to the the @code{gdb.Symtab_and_line}'s line attribute. +Thus, all the macros which would be validly usable at that line. +@end defmethod @end table A @code{gdb.Symtab} object has the following attributes: @@ -23475,6 +23492,66 @@ if it is invalid at the time the method is called. @defmethod Symtab fullname Return the symbol table's source absolute file name. @end defmethod + +@defmethod Symtab macros +Return all of the macros contained in the symbol table. +@end defmethod +@end table + +@node Macros In Python +@subsubsection Python representation of preprocessor macros. + +@cindex macros in python +@tindex gdb.macro + +Python code can query information about preprocessor macros using the +@code{gdb.Macro} class. For obtaining a @code{gdb.Macro} object see +@xref{Symbol Tables In Python}. + +@code{gdb.Macro} methods may produce a lazily created python copy from +gdb's internal representation possibly returning different copies +that contain same value when called multiple times. + +The @code{gdb.Macro} class should be considered an abstract class, +instances possibly being of different types. Thus, you should always call +its functions directly from an instance, And never reference a method +through the @code{gdb.Macro} class object. For example you should use +@code{map(lambda macro: macro.name(), macros)} instead of +@code{map(gdb.Macro.name, macros)}. + +@table @code +@defmethod Macro argv +Returns a list of the macros arguments if the macro is function like. +If the macro is not function like, returns @code{None} +@end defmethod + +@defmethod Macro definition +Returns a string containing the definition of the macro. +@end defmethod + +@defmethod Macro include_trail +Returns a list of tuples containing the filenames, and line numbers +of header and source files that correspond to the include directives, +and location of definition. The list is sorted starting with the place +of definition, and ending with the first include directive. +@end defmethod + +@defmethod Macro is_function_like +Returns @code{True} If the macro is function like. +@end defmethod + +@defmethod Macro is_valid +Returns @code{True} if the macro is valid. +All other @code{gdb.Macro} methods will throw an exception if the object is +invalid at the time the method is called. +A macro which becomes invalid will never be valid again +without looking up the macro again to create a new @code{gdb.Macro} +object. +@end defmethod + +@defmethod Macro name +Returns the name of the macro. +@end defmethod @end table @node Breakpoints In Python -- 1.7.4.4