[patch, doc RFA]: New python function lookup_global_symbol

[patch, doc RFA]: New python function lookup_global_symbol

[Doug Evans]

Hi.
I couldn't figure out how to lookup up a global symbol without
having a running program and without knowing the block it is in.
Plus lookup_symbol already has a specified behaviour when the
`block' argument is elided: use the current frame.

So it seemed best to add a new function.

If there's an existing way to lookup a symbol without requiring
a running program, please let me know ... I'll at least improve
the docs ... :-)

Otherwise I will check this in next week pending doc RFA.

2011-02-18  Doug Evans  <dje@google.com>

	Add gdb.lookup_global_symbol python function.
	* NEWS: Add entry.
	* python/py-symbol.c (gdbpy_lookup_global_symbol): New function.
	* python/python-internal.h (gdbpy_lookup_global_symbol): Declare it.
	* python/python.c (GdbMethods): Add entry for lookup_global_symbol.

	doc/
	* gdb.texinfo (Symbols In Python): Document lookup_global_symbol.
	Clarify behaviour of lookup_symbol when `block' argument is elided.

	testsuite/
	* gdb.python/py-symbol.exp: Test lookup_global_symbol.

Index: NEWS
===================================================================
RCS file: /cvs/src/src/gdb/NEWS,v
retrieving revision 1.426
diff -u -p -r1.426 NEWS
--- NEWS	15 Feb 2011 21:17:52 -0000	1.426
+++ NEWS	18 Feb 2011 23:48:45 -0000
@@ -38,6 +38,8 @@
 
 * Python scripting
 
+  ** New function gdb.lookup_global_symbol looks up a global symbol.
+
   ** GDB values in Python are now callable if the value represents a
      function.  For example, if 'some_value' represents a function that
      takes two integer parameters and returns a value, you can call
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.800
diff -u -p -r1.800 gdb.texinfo
--- doc/gdb.texinfo	15 Feb 2011 21:17:52 -0000	1.800
+++ doc/gdb.texinfo	18 Feb 2011 23:48:45 -0000
@@ -22831,12 +22831,24 @@ arguments.
 @var{name} is the name of the symbol.  It must be a string.  The
 optional @var{block} argument restricts the search to symbols visible
 in that @var{block}.  The @var{block} argument must be a
-@code{gdb.Block} object.  The optional @var{domain} argument restricts
+@code{gdb.Block} object.  If elided, the block for the current frame
+is used.  The optional @var{domain} argument restricts
 the search to the domain type.  The @var{domain} argument must be a
 domain constant defined in the @code{gdb} module and described later
 in this chapter.
 @end defun
 
+@findex gdb.lookup_global_symbol
+@defun lookup_symbol name [domain]
+This function searches for a global symbol by name.
+The search scope can be restricted to by the domain argument.
+
+@var{name} is the name of the symbol.  It must be a string.
+The optional @var{domain} argument restricts the search to the domain type.
+The @var{domain} argument must be a domain constant defined in the @code{gdb}
+module and described later in this chapter.
+@end defun
+
 A @code{gdb.Symbol} object has the following attributes:
 
 @table @code
Index: python/py-symbol.c
===================================================================
RCS file: /cvs/src/src/gdb/python/py-symbol.c,v
retrieving revision 1.3
diff -u -p -r1.3 py-symbol.c
--- python/py-symbol.c	6 Jan 2011 00:57:04 -0000	1.3
+++ python/py-symbol.c	18 Feb 2011 23:48:45 -0000
@@ -236,6 +236,7 @@ sympy_dealloc (PyObject *obj)
    A tuple with 2 elements is always returned.  The first is the symbol
    object or None, the second is a boolean with the value of
    is_a_field_of_this (see comment in lookup_symbol_in_language).  */
+
 PyObject *
 gdbpy_lookup_symbol (PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -294,6 +295,39 @@ gdbpy_lookup_symbol (PyObject *self, PyO
   return ret_tuple;
 }
 
+/* Implementation of
+   gdb.lookup_global_symbol (name [, domain]) -> symbol or None.  */
+
+PyObject *
+gdbpy_lookup_global_symbol (PyObject *self, PyObject *args, PyObject *kw)
+{
+  int domain = VAR_DOMAIN;
+  const char *name;
+  static char *keywords[] = { "name", "domain", NULL };
+  struct symbol *symbol;
+  PyObject *sym_obj;
+
+  if (! PyArg_ParseTupleAndKeywords (args, kw, "s|i", keywords, &name,
+				     &domain))
+    return NULL;
+
+  symbol = lookup_symbol_global (name, NULL, domain);
+
+  if (symbol)
+    {
+      sym_obj = symbol_to_symbol_object (symbol);
+      if (!sym_obj)
+	return NULL;
+    }
+  else
+    {
+      sym_obj = Py_None;
+      Py_INCREF (Py_None);
+    }
+
+  return sym_obj;
+}
+
 /* This function is called when an objfile is about to be freed.
    Invalidate the symbol as further actions on the symbol would result
    in bad data.  All access to obj->symbol should be gated by
Index: python/python-internal.h
===================================================================
RCS file: /cvs/src/src/gdb/python/python-internal.h,v
retrieving revision 1.42
diff -u -p -r1.42 python-internal.h
--- python/python-internal.h	4 Feb 2011 21:54:16 -0000	1.42
+++ python/python-internal.h	18 Feb 2011 23:48:45 -0000
@@ -136,6 +136,8 @@ PyObject *gdbpy_history (PyObject *self,
 PyObject *gdbpy_breakpoints (PyObject *, PyObject *);
 PyObject *gdbpy_frame_stop_reason_string (PyObject *, PyObject *);
 PyObject *gdbpy_lookup_symbol (PyObject *self, PyObject *args, PyObject *kw);
+PyObject *gdbpy_lookup_global_symbol (PyObject *self, PyObject *args,
+				      PyObject *kw);
 PyObject *gdbpy_newest_frame (PyObject *self, PyObject *args);
 PyObject *gdbpy_selected_frame (PyObject *self, PyObject *args);
 PyObject *gdbpy_block_for_pc (PyObject *self, PyObject *args);
Index: python/python.c
===================================================================
RCS file: /cvs/src/src/gdb/python/python.c,v
retrieving revision 1.59
diff -u -p -r1.59 python.c
--- python/python.c	4 Feb 2011 21:54:16 -0000	1.59
+++ python/python.c	18 Feb 2011 23:48:45 -0000
@@ -1145,6 +1145,10 @@ Return a Type corresponding to the given
 Return a tuple with the symbol corresponding to the given name (or None) and\n\
 a boolean indicating if name is a field of the current implied argument\n\
 `this' (when the current language is object-oriented)." },
+  { "lookup_global_symbol", (PyCFunction) gdbpy_lookup_global_symbol,
+    METH_VARARGS | METH_KEYWORDS,
+    "lookup_global_symbol (name [, domain]) -> symbol\n\
+Return the symbol corresponding to the given name (or None)." },
   { "block_for_pc", gdbpy_block_for_pc, METH_VARARGS,
     "Return the block containing the given pc value, or None." },
   { "solib_name", gdbpy_solib_name, METH_VARARGS,
Index: testsuite/gdb.python/py-symbol.exp
===================================================================
RCS file: /cvs/src/src/gdb/testsuite/gdb.python/py-symbol.exp,v
retrieving revision 1.4
diff -u -p -r1.4 py-symbol.exp
--- testsuite/gdb.python/py-symbol.exp	1 Jan 2011 15:33:49 -0000	1.4
+++ testsuite/gdb.python/py-symbol.exp	18 Feb 2011 23:48:45 -0000
@@ -39,6 +39,13 @@ gdb_load ${binfile}
 # Skip all tests if Python scripting is not enabled.
 if { [skip_python_tests] } { continue }
 
+# Test looking up a global symbol before we runto_main as this is the
+# point where we don't have a current frame, and we don't want to
+# require one.
+gdb_py_test_silent_cmd "python main_func = gdb.lookup_global_symbol(\"main\")" "Lookup main" 1
+gdb_test "python print main_func.is_function" "True" "Test main_func.is_function"
+gdb_test "python print gdb.lookup_global_symbol(\"junk\")" "None" "Test lookup_global_symbol(\"junk\")"
+
 if ![runto_main] then {
     fail "Can't run to main"
     return 0

Re: [patch, doc RFA]: New python function lookup_global_symbol

[Eli Zaretskii]

> Date: Fri, 18 Feb 2011 15:59:45 -0800 (PST)
> From: dje@google.com (Doug Evans)
> 
> --- NEWS	15 Feb 2011 21:17:52 -0000	1.426
> +++ NEWS	18 Feb 2011 23:48:45 -0000
> @@ -38,6 +38,8 @@
>  
>  * Python scripting
>  
> +  ** New function gdb.lookup_global_symbol looks up a global symbol.
> +

This part is okay.

> -@code{gdb.Block} object.  The optional @var{domain} argument restricts
> +@code{gdb.Block} object.  If elided, the block for the current frame
                                ^^^^^^
Please use "omitted" instead, it will be understood by more readers
whose first language is not English.  We use "omitted" in this context
elsewhere in the manual.

> +@defun lookup_symbol name [domain]

@defun renders its arguments in @code and @var, but you want the
brackets in the normal roman typeface.  So this should be

  @defun lookup_symbol name @r{[}domain@r{]}

> +This function searches for a global symbol by name.
> +The search scope can be restricted to by the domain argument.
> +
> +@var{name} is the name of the symbol.  It must be a string.
> +The optional @var{domain} argument restricts the search to the domain type.
> +The @var{domain} argument must be a domain constant defined in the @code{gdb}
> +module and described later in this chapter.

Should we tell what happens if the symbol is not found?

Okay with those changes.

Thanks.

Re: [patch, doc RFA]: New python function lookup_global_symbol

[Tom Tromey]

>>>>> "Doug" == Doug Evans <dje@google.com> writes:

Doug> I couldn't figure out how to lookup up a global symbol without
Doug> having a running program and without knowing the block it is in.
Doug> Plus lookup_symbol already has a specified behaviour when the
Doug> `block' argument is elided: use the current frame.

Doug> So it seemed best to add a new function.

FWIW, it seems fine to me.

Tom

Re: [patch, doc RFA]: New python function lookup_global_symbol

[Doug Evans]

[-- Attachment #1: Type: text/plain, Size: 1570 bytes --]

On Sat, Feb 19, 2011 at 12:21 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Fri, 18 Feb 2011 15:59:45 -0800 (PST)
>> From: dje@google.com (Doug Evans)
>>
>> --- NEWS      15 Feb 2011 21:17:52 -0000      1.426
>> +++ NEWS      18 Feb 2011 23:48:45 -0000
>> @@ -38,6 +38,8 @@
>>
>>  * Python scripting
>>
>> +  ** New function gdb.lookup_global_symbol looks up a global symbol.
>> +
>
> This part is okay.
>
>> -@code{gdb.Block} object.  The optional @var{domain} argument restricts
>> +@code{gdb.Block} object.  If elided, the block for the current frame
>                                ^^^^^^
> Please use "omitted" instead, it will be understood by more readers
> whose first language is not English.  We use "omitted" in this context
> elsewhere in the manual.
>
>> +@defun lookup_symbol name [domain]
>
> @defun renders its arguments in @code and @var, but you want the
> brackets in the normal roman typeface.  So this should be
>
>  @defun lookup_symbol name @r{[}domain@r{]}
>
>> +This function searches for a global symbol by name.
>> +The search scope can be restricted to by the domain argument.
>> +
>> +@var{name} is the name of the symbol.  It must be a string.
>> +The optional @var{domain} argument restricts the search to the domain type.
>> +The @var{domain} argument must be a domain constant defined in the @code{gdb}
>> +module and described later in this chapter.
>
> Should we tell what happens if the symbol is not found?
>
> Okay with those changes.
>
> Thanks.

Thanks.
Here is what I checked in.

[-- Attachment #2: gdb-110222-lookup-global-symbol.patch.txt --]
[-- Type: text/plain, Size: 7919 bytes --]

2011-02-18  Doug Evans  <dje@google.com>

	Add gdb.lookup_global_symbol python function.
	* NEWS: Add entry.
	* python/py-symbol.c (gdbpy_lookup_global_symbol): New function.
	* python/python-internal.h (gdbpy_lookup_global_symbol): Declare it.
	* python/python.c (GdbMethods): Add entry for lookup_global_symbol.

	doc/
	* gdb.texinfo (Symbols In Python): Document lookup_global_symbol.
	Clarify behaviour of lookup_symbol when `block' argument is omitted,
	add description of result, fix @defun formatting.

	testsuite/
	* gdb.python/py-symbol.exp: Test lookup_global_symbol.

Index: NEWS
===================================================================
RCS file: /cvs/src/src/gdb/NEWS,v
retrieving revision 1.426
diff -u -p -r1.426 NEWS
--- NEWS	15 Feb 2011 21:17:52 -0000	1.426
+++ NEWS	22 Feb 2011 22:38:34 -0000
@@ -38,6 +38,8 @@
 
 * Python scripting
 
+  ** New function gdb.lookup_global_symbol looks up a global symbol.
+
   ** GDB values in Python are now callable if the value represents a
      function.  For example, if 'some_value' represents a function that
      takes two integer parameters and returns a value, you can call
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.801
diff -u -p -r1.801 gdb.texinfo
--- doc/gdb.texinfo	21 Feb 2011 08:40:27 -0000	1.801
+++ doc/gdb.texinfo	22 Feb 2011 22:38:35 -0000
@@ -22829,7 +22829,7 @@ The following symbol-related functions a
 module:
 
 @findex gdb.lookup_symbol
-@defun lookup_symbol name [block] [domain]
+@defun lookup_symbol name @r{[}block@r{]} @r{[}domain@r{]}
 This function searches for a symbol by name.  The search scope can be
 restricted to the parameters defined in the optional domain and block
 arguments.
@@ -22837,10 +22837,33 @@ arguments.
 @var{name} is the name of the symbol.  It must be a string.  The
 optional @var{block} argument restricts the search to symbols visible
 in that @var{block}.  The @var{block} argument must be a
-@code{gdb.Block} object.  The optional @var{domain} argument restricts
+@code{gdb.Block} object.  If omitted, the block for the current frame
+is used.  The optional @var{domain} argument restricts
 the search to the domain type.  The @var{domain} argument must be a
 domain constant defined in the @code{gdb} module and described later
 in this chapter.
+
+The result is a tuple of two elements.
+The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
+is not found.
+If the symbol is found, the second element is @code{True} if the symbol
+is a field of a method's object (e.g., @code{this} in @code{C++}),
+otherwise it is @code{False}.
+If the symbol is not found, the second element is @code{False}.
+@end defun
+
+@findex gdb.lookup_global_symbol
+@defun lookup_global_symbol name @r{[}domain@r{]}
+This function searches for a global symbol by name.
+The search scope can be restricted to by the domain argument.
+
+@var{name} is the name of the symbol.  It must be a string.
+The optional @var{domain} argument restricts the search to the domain type.
+The @var{domain} argument must be a domain constant defined in the @code{gdb}
+module and described later in this chapter.
+
+The result is a @code{gdb.Symbol} object or @code{None} if the symbol
+is not found.
 @end defun
 
 A @code{gdb.Symbol} object has the following attributes:
Index: python/py-symbol.c
===================================================================
RCS file: /cvs/src/src/gdb/python/py-symbol.c,v
retrieving revision 1.3
diff -u -p -r1.3 py-symbol.c
--- python/py-symbol.c	6 Jan 2011 00:57:04 -0000	1.3
+++ python/py-symbol.c	22 Feb 2011 22:38:35 -0000
@@ -236,6 +236,7 @@ sympy_dealloc (PyObject *obj)
    A tuple with 2 elements is always returned.  The first is the symbol
    object or None, the second is a boolean with the value of
    is_a_field_of_this (see comment in lookup_symbol_in_language).  */
+
 PyObject *
 gdbpy_lookup_symbol (PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -294,6 +295,39 @@ gdbpy_lookup_symbol (PyObject *self, PyO
   return ret_tuple;
 }
 
+/* Implementation of
+   gdb.lookup_global_symbol (name [, domain]) -> symbol or None.  */
+
+PyObject *
+gdbpy_lookup_global_symbol (PyObject *self, PyObject *args, PyObject *kw)
+{
+  int domain = VAR_DOMAIN;
+  const char *name;
+  static char *keywords[] = { "name", "domain", NULL };
+  struct symbol *symbol;
+  PyObject *sym_obj;
+
+  if (! PyArg_ParseTupleAndKeywords (args, kw, "s|i", keywords, &name,
+				     &domain))
+    return NULL;
+
+  symbol = lookup_symbol_global (name, NULL, domain);
+
+  if (symbol)
+    {
+      sym_obj = symbol_to_symbol_object (symbol);
+      if (!sym_obj)
+	return NULL;
+    }
+  else
+    {
+      sym_obj = Py_None;
+      Py_INCREF (Py_None);
+    }
+
+  return sym_obj;
+}
+
 /* This function is called when an objfile is about to be freed.
    Invalidate the symbol as further actions on the symbol would result
    in bad data.  All access to obj->symbol should be gated by
Index: python/python-internal.h
===================================================================
RCS file: /cvs/src/src/gdb/python/python-internal.h,v
retrieving revision 1.42
diff -u -p -r1.42 python-internal.h
--- python/python-internal.h	4 Feb 2011 21:54:16 -0000	1.42
+++ python/python-internal.h	22 Feb 2011 22:38:35 -0000
@@ -136,6 +136,8 @@ PyObject *gdbpy_history (PyObject *self,
 PyObject *gdbpy_breakpoints (PyObject *, PyObject *);
 PyObject *gdbpy_frame_stop_reason_string (PyObject *, PyObject *);
 PyObject *gdbpy_lookup_symbol (PyObject *self, PyObject *args, PyObject *kw);
+PyObject *gdbpy_lookup_global_symbol (PyObject *self, PyObject *args,
+				      PyObject *kw);
 PyObject *gdbpy_newest_frame (PyObject *self, PyObject *args);
 PyObject *gdbpy_selected_frame (PyObject *self, PyObject *args);
 PyObject *gdbpy_block_for_pc (PyObject *self, PyObject *args);
Index: python/python.c
===================================================================
RCS file: /cvs/src/src/gdb/python/python.c,v
retrieving revision 1.59
diff -u -p -r1.59 python.c
--- python/python.c	4 Feb 2011 21:54:16 -0000	1.59
+++ python/python.c	22 Feb 2011 22:38:35 -0000
@@ -1145,6 +1145,10 @@ Return a Type corresponding to the given
 Return a tuple with the symbol corresponding to the given name (or None) and\n\
 a boolean indicating if name is a field of the current implied argument\n\
 `this' (when the current language is object-oriented)." },
+  { "lookup_global_symbol", (PyCFunction) gdbpy_lookup_global_symbol,
+    METH_VARARGS | METH_KEYWORDS,
+    "lookup_global_symbol (name [, domain]) -> symbol\n\
+Return the symbol corresponding to the given name (or None)." },
   { "block_for_pc", gdbpy_block_for_pc, METH_VARARGS,
     "Return the block containing the given pc value, or None." },
   { "solib_name", gdbpy_solib_name, METH_VARARGS,
Index: testsuite/gdb.python/py-symbol.exp
===================================================================
RCS file: /cvs/src/src/gdb/testsuite/gdb.python/py-symbol.exp,v
retrieving revision 1.4
diff -u -p -r1.4 py-symbol.exp
--- testsuite/gdb.python/py-symbol.exp	1 Jan 2011 15:33:49 -0000	1.4
+++ testsuite/gdb.python/py-symbol.exp	22 Feb 2011 22:38:35 -0000
@@ -39,6 +39,13 @@ gdb_load ${binfile}
 # Skip all tests if Python scripting is not enabled.
 if { [skip_python_tests] } { continue }
 
+# Test looking up a global symbol before we runto_main as this is the
+# point where we don't have a current frame, and we don't want to
+# require one.
+gdb_py_test_silent_cmd "python main_func = gdb.lookup_global_symbol(\"main\")" "Lookup main" 1
+gdb_test "python print main_func.is_function" "True" "Test main_func.is_function"
+gdb_test "python print gdb.lookup_global_symbol(\"junk\")" "None" "Test lookup_global_symbol(\"junk\")"
+
 if ![runto_main] then {
     fail "Can't run to main"
     return 0

Re: [patch, doc RFA]: New python function lookup_global_symbol

[Eli Zaretskii]

> Date: Tue, 22 Feb 2011 14:50:10 -0800
> From: Doug Evans <dje@google.com>
> Cc: gdb-patches@sourceware.org
> 
> Thanks.
> Here is what I checked in.

One comment about your commit:

> +is a field of a method's object (e.g., @code{this} in @code{C++}),

We use "C@t{++}" in the manual for the C++ language.  Putting it all
in @code is not right, because it isn't a program symbol, and it also
looks weird in the Info output, where @code is converted to `..'
quoted string.

Thanks.

Re: [patch, doc RFA]: New python function lookup_global_symbol

[Doug Evans]

On Tue, Feb 22, 2011 at 8:00 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Tue, 22 Feb 2011 14:50:10 -0800
>> From: Doug Evans <dje@google.com>
>> Cc: gdb-patches@sourceware.org
>>
>> Thanks.
>> Here is what I checked in.
>
> One comment about your commit:
>
>> +is a field of a method's object (e.g., @code{this} in @code{C++}),
>
> We use "C@t{++}" in the manual for the C++ language.  Putting it all
> in @code is not right, because it isn't a program symbol, and it also
> looks weird in the Info output, where @code is converted to `..'
> quoted string.

Ah, right.  Sorry 'bout that.  Fixed.

I grepped for C++ trying to find the right way to write `C++', but of
course such a grep fails to find C@t{++}.  I wonder how useful it
would be to have a section at the top of the file containing various
formatting hints.

Re: [patch, doc RFA]: New python function lookup_global_symbol

[Eli Zaretskii]

> Date: Wed, 23 Feb 2011 15:50:47 -0800
> From: Doug Evans <dje@google.com>
> Cc: gdb-patches@sourceware.org
> 
> I wonder how useful it would be to have a section at the top of the
> file containing various formatting hints.

It would be too long, because Texinfo is a complex language.  I would
be hard-pressed to come up with a short enough list of hints that
would still be useful by covering enough turf.