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

[matt rice <ratmice at gmail dot com>]

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