[PATCH 6/7] [python] API for macros: Add docs.

matt rice
2011-08-24T15:11:57Z

2011-08-23 Matt Rice <ratmice@gmail.com>

* 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 <ratmice@gmail.com>

* 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