[RFA][python] Add gdb.Value.string method.

[RFA][python] Add gdb.Value.string method.

[Thiago Jung Bauermann]

Hi,

This patch adds a method to the Value python class which returns the
value as a Python Unicode string. It depends on the patch I just posted
in the "Add la_getstr member to language_defn", and assumes that the
"Fixes and improvements to gdb.Value" patch has been applied. Ok?
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center


gdb/
2009-01-03  Thiago Jung Bauermann  <bauerman@br.ibm.com>
	    Tom Tromey  <tromey@redhat.com>

	* python/python-utils.c (target_string_to_unicode): New function.
	* python/python-internal.h (target_string_to_unicode): New prototype.
	* python/python-value.c (valpy_string): New function.
	(value_object_methods): Add `string' entry.

gdb/doc/
2009-01-03  Tom Tromey  <tromey@redhat.com>
 
	* gdb.texinfo (Values From Inferior): Document Value.string.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 030d4b3..3b1cd91 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18202,6 +18202,31 @@ The result @code{bar} will be a @code{gdb.Value} object holding the
 value pointed to by @code{foo}.
 @end defmethod
 
+@defmethod Value string @r{[}encoding @r{[}errors@r{]}@r{]}
+If this @code{gdb.Value} represents a string, then this method
+converts the contents to a Python string.  Otherwise, this method will
+throw an exception.
+
+Strings are recognized in a language-specific way; whether a given
+@code{gdb.Value} represents a string is determined by the current
+language.
+
+For C-like languages, a value is a string if it is a pointer to or an
+array of characters or ints.  The string is assumed to be terminated
+by a zero of the appropriate width.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the string in the @code{gdb.Value}.  The Python
+codec machinery will be used to convert the string.  If @var{encoding}
+is not given, or if @var{encoding} is the empty string, then either
+the @code{target-charset} (@pxref{Character Sets}) will be used, or a
+language-specific encoding will be used, if the current language is
+able to supply one.
+
+The optional @var{errors} argument is the same as the corresponding
+argument to Python's @code{string.decode} method.
+@end defmethod
+
 @node Interpreters
 @chapter Command Interpreters
 @cindex command interpreters
diff --git a/gdb/python/python-internal.h b/gdb/python/python-internal.h
index bcd37e4..9c2e8c6 100644
--- a/gdb/python/python-internal.h
+++ b/gdb/python/python-internal.h
@@ -88,6 +88,7 @@ PyObject *python_string_to_unicode (PyObject *obj);
 char *unicode_to_target_string (PyObject *unicode_str);
 char *python_string_to_target_string (PyObject *obj);
 char *python_string_to_host_string (PyObject *obj);
+PyObject *target_string_to_unicode (const gdb_byte *str, int length);
 int gdbpy_is_string (PyObject *obj);
 
 #endif /* GDB_PYTHON_INTERNAL_H */
diff --git a/gdb/python/python-utils.c b/gdb/python/python-utils.c
index c27a930..1e6d952 100644
--- a/gdb/python/python-utils.c
+++ b/gdb/python/python-utils.c
@@ -160,6 +160,19 @@ python_string_to_host_string (PyObject *obj)
   return unicode_to_encoded_string (str, host_charset ());
 }
 
+/* Converts a target string of LENGTH bytes in the target's charset to a
+   Python Unicode string. If LENGTH is -1, convert until a null byte is found.
+
+   Returns NULL on error, with a python exception set.  */
+PyObject *
+target_string_to_unicode (const gdb_byte *str, int length)
+{
+  if (length == -1)
+    length = strlen (str);
+
+  return PyUnicode_Decode (str, length, target_charset (), NULL);
+}
+
 /* Return true if OBJ is a Python string or unicode object, false
    otherwise.  */
 
diff --git a/gdb/python/python-value.c b/gdb/python/python-value.c
index 4d1f864..c6775b2 100644
--- a/gdb/python/python-value.c
+++ b/gdb/python/python-value.c
@@ -148,6 +148,47 @@ valpy_address (PyObject *self, PyObject *args)
   return value_to_value_object (res_val);
 }
 
+/* Return Unicode string with value contents (assumed to be encoded in the
+   target's charset).  */
+static PyObject *
+valpy_string (PyObject *self, PyObject *args)
+{
+  int length, ret = 0;
+  gdb_byte *buffer;
+  struct value *value = ((value_object *) self)->value;
+  volatile struct gdb_exception except;
+  PyObject *unicode;
+  const char *encoding = NULL;
+  const char *errors = NULL;
+  const char *user_encoding = NULL;
+  const char *la_encoding = NULL;
+
+  if (!PyArg_ParseTuple (args, "|ss", &user_encoding, &errors))
+    return NULL;
+
+  TRY_CATCH (except, RETURN_MASK_ALL)
+    {
+      ret = LA_GET_STRING (value, &buffer, &length, &la_encoding);
+    }
+  GDB_PY_HANDLE_EXCEPTION (except);
+
+  if (ret != 0)
+    {
+      /* We may have read a partial string before the error happened, but
+         we will ignore it and throw an exception anyway.  */
+      PyErr_SetString (PyExc_RuntimeError, safe_strerror (ret));
+      xfree (buffer);
+
+      return NULL;
+    }
+
+  encoding = (user_encoding && *user_encoding) ? user_encoding : la_encoding;
+  unicode = PyUnicode_Decode (buffer, length, encoding, errors);
+  xfree (buffer);
+
+  return unicode;
+}
+
 static Py_ssize_t
 valpy_length (PyObject *self)
 {
@@ -773,6 +814,8 @@ gdbpy_initialize_values (void)
 static PyMethodDef value_object_methods[] = {
   { "address", valpy_address, METH_NOARGS, "Return the address of the value." },
   { "dereference", valpy_dereference, METH_NOARGS, "Dereferences the value." },
+  { "string", valpy_string, METH_VARARGS,
+    "Return Unicode string representation of the value." },
   {NULL}  /* Sentinel */
 };
 

Re: [RFA][python] Add gdb.Value.string method.

[Thiago Jung Bauermann]

Hi Eli,

I'm not sure if you're aware, this patch didn't get a documentation
review/approval yet.

Thanks for your speedy review on the other Python patches, by the way.
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center


El sáb, 03-01-2009 a las 00:27 -0200, Thiago Jung Bauermann escribió:
> Hi,
> 
> This patch adds a method to the Value python class which returns the
> value as a Python Unicode string. It depends on the patch I just posted
> in the "Add la_getstr member to language_defn", and assumes that the
> "Fixes and improvements to gdb.Value" patch has been applied. Ok?
> -- 
> []'s
> Thiago Jung Bauermann
> IBM Linux Technology Center
> 
> 
> gdb/
> 2009-01-03  Thiago Jung Bauermann  <bauerman@br.ibm.com>
> 	    Tom Tromey  <tromey@redhat.com>
> 
> 	* python/python-utils.c (target_string_to_unicode): New function.
> 	* python/python-internal.h (target_string_to_unicode): New prototype.
> 	* python/python-value.c (valpy_string): New function.
> 	(value_object_methods): Add `string' entry.
> 
> gdb/doc/
> 2009-01-03  Tom Tromey  <tromey@redhat.com>
>  
> 	* gdb.texinfo (Values From Inferior): Document Value.string.
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 030d4b3..3b1cd91 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -18202,6 +18202,31 @@ The result @code{bar} will be a @code{gdb.Value} object holding the
>  value pointed to by @code{foo}.
>  @end defmethod
>  
> +@defmethod Value string @r{[}encoding @r{[}errors@r{]}@r{]}
> +If this @code{gdb.Value} represents a string, then this method
> +converts the contents to a Python string.  Otherwise, this method will
> +throw an exception.
> +
> +Strings are recognized in a language-specific way; whether a given
> +@code{gdb.Value} represents a string is determined by the current
> +language.
> +
> +For C-like languages, a value is a string if it is a pointer to or an
> +array of characters or ints.  The string is assumed to be terminated
> +by a zero of the appropriate width.
> +
> +If the optional @var{encoding} argument is given, it must be a string
> +naming the encoding of the string in the @code{gdb.Value}.  The Python
> +codec machinery will be used to convert the string.  If @var{encoding}
> +is not given, or if @var{encoding} is the empty string, then either
> +the @code{target-charset} (@pxref{Character Sets}) will be used, or a
> +language-specific encoding will be used, if the current language is
> +able to supply one.
> +
> +The optional @var{errors} argument is the same as the corresponding
> +argument to Python's @code{string.decode} method.
> +@end defmethod
> +
>  @node Interpreters
>  @chapter Command Interpreters
>  @cindex command interpreters
> diff --git a/gdb/python/python-internal.h b/gdb/python/python-internal.h
> index bcd37e4..9c2e8c6 100644
> --- a/gdb/python/python-internal.h
> +++ b/gdb/python/python-internal.h
> @@ -88,6 +88,7 @@ PyObject *python_string_to_unicode (PyObject *obj);
>  char *unicode_to_target_string (PyObject *unicode_str);
>  char *python_string_to_target_string (PyObject *obj);
>  char *python_string_to_host_string (PyObject *obj);
> +PyObject *target_string_to_unicode (const gdb_byte *str, int length);
>  int gdbpy_is_string (PyObject *obj);
>  
>  #endif /* GDB_PYTHON_INTERNAL_H */
> diff --git a/gdb/python/python-utils.c b/gdb/python/python-utils.c
> index c27a930..1e6d952 100644
> --- a/gdb/python/python-utils.c
> +++ b/gdb/python/python-utils.c
> @@ -160,6 +160,19 @@ python_string_to_host_string (PyObject *obj)
>    return unicode_to_encoded_string (str, host_charset ());
>  }
>  
> +/* Converts a target string of LENGTH bytes in the target's charset to a
> +   Python Unicode string. If LENGTH is -1, convert until a null byte is found.
> +
> +   Returns NULL on error, with a python exception set.  */
> +PyObject *
> +target_string_to_unicode (const gdb_byte *str, int length)
> +{
> +  if (length == -1)
> +    length = strlen (str);
> +
> +  return PyUnicode_Decode (str, length, target_charset (), NULL);
> +}
> +
>  /* Return true if OBJ is a Python string or unicode object, false
>     otherwise.  */
>  
> diff --git a/gdb/python/python-value.c b/gdb/python/python-value.c
> index 4d1f864..c6775b2 100644
> --- a/gdb/python/python-value.c
> +++ b/gdb/python/python-value.c
> @@ -148,6 +148,47 @@ valpy_address (PyObject *self, PyObject *args)
>    return value_to_value_object (res_val);
>  }
>  
> +/* Return Unicode string with value contents (assumed to be encoded in the
> +   target's charset).  */
> +static PyObject *
> +valpy_string (PyObject *self, PyObject *args)
> +{
> +  int length, ret = 0;
> +  gdb_byte *buffer;
> +  struct value *value = ((value_object *) self)->value;
> +  volatile struct gdb_exception except;
> +  PyObject *unicode;
> +  const char *encoding = NULL;
> +  const char *errors = NULL;
> +  const char *user_encoding = NULL;
> +  const char *la_encoding = NULL;
> +
> +  if (!PyArg_ParseTuple (args, "|ss", &user_encoding, &errors))
> +    return NULL;
> +
> +  TRY_CATCH (except, RETURN_MASK_ALL)
> +    {
> +      ret = LA_GET_STRING (value, &buffer, &length, &la_encoding);
> +    }
> +  GDB_PY_HANDLE_EXCEPTION (except);
> +
> +  if (ret != 0)
> +    {
> +      /* We may have read a partial string before the error happened, but
> +         we will ignore it and throw an exception anyway.  */
> +      PyErr_SetString (PyExc_RuntimeError, safe_strerror (ret));
> +      xfree (buffer);
> +
> +      return NULL;
> +    }
> +
> +  encoding = (user_encoding && *user_encoding) ? user_encoding : la_encoding;
> +  unicode = PyUnicode_Decode (buffer, length, encoding, errors);
> +  xfree (buffer);
> +
> +  return unicode;
> +}
> +
>  static Py_ssize_t
>  valpy_length (PyObject *self)
>  {
> @@ -773,6 +814,8 @@ gdbpy_initialize_values (void)
>  static PyMethodDef value_object_methods[] = {
>    { "address", valpy_address, METH_NOARGS, "Return the address of the value." },
>    { "dereference", valpy_dereference, METH_NOARGS, "Dereferences the value." },
> +  { "string", valpy_string, METH_VARARGS,
> +    "Return Unicode string representation of the value." },
>    {NULL}  /* Sentinel */
>  };
>  
> 
> 

Re: [RFA][python] Add gdb.Value.string method.

[Eli Zaretskii]

> From: Thiago Jung Bauermann <bauerman@br.ibm.com>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Tue, 03 Feb 2009 11:56:57 -0200
> 
> I'm not sure if you're aware, this patch didn't get a documentation
> review/approval yet.

It's OK, but...

> > +If the optional @var{encoding} argument is given, it must be a string
> > +naming the encoding of the string in the @code{gdb.Value}.

Would every Python programmer know what kind of argument strings can
be given for @var{encoding}?  If not, perhaps a list or at least a
hint where to find such a list would be useful.

Also, perhaps this feature needs some @cindex index entries.  Please
consider that.

Otherwise, it can go in.  Thanks.

Re: [RFA][python] Add gdb.Value.string method.

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

>> > +If the optional @var{encoding} argument is given, it must be a string
>> > +naming the encoding of the string in the @code{gdb.Value}.

Eli> Would every Python programmer know what kind of argument strings can
Eli> be given for @var{encoding}?  If not, perhaps a list or at least a
Eli> hint where to find such a list would be useful.

We can't list the possible encodings -- not only does the list change
over time, but users can write their own codecs in Python.

I suggest just hoisting the reference to Python's "string.decode"
method to an earlier spot in the paragraph.  This should be sufficient
for anybody, use of the string module is common knowledge.

Tom

Re: [RFA][python] Add gdb.Value.string method.

[Thiago Jung Bauermann]

El mié, 04-02-2009 a las 12:45 -0700, Tom Tromey escribió:
> >>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> > +If the optional @var{encoding} argument is given, it must be a string
> >> > +naming the encoding of the string in the @code{gdb.Value}.
> 
> Eli> Would every Python programmer know what kind of argument strings can
> Eli> be given for @var{encoding}?  If not, perhaps a list or at least a
> Eli> hint where to find such a list would be useful.
> 
> We can't list the possible encodings -- not only does the list change
> over time, but users can write their own codecs in Python.
> 
> I suggest just hoisting the reference to Python's "string.decode"
> method to an earlier spot in the paragraph.  This should be sufficient
> for anybody, use of the string module is common knowledge.

What about the following, then?

"If the optional @var{encoding} argument is given, it must be a string
naming the encoding of the string in the @code{gdb.Value}.  It accepts
the same encodings as the corresponding argument to Python's
@code{string.decode} method, so the Python codec machinery will be used
to convert the string."

I left the paragraph about the errors argument untouched.
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center

Re: [RFA][python] Add gdb.Value.string method.

[Eli Zaretskii]

> From: Thiago Jung Bauermann <bauerman@br.ibm.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, gdb-patches@sourceware.org
> Date: Thu, 05 Feb 2009 11:19:04 -0200
> 
> > Eli> Would every Python programmer know what kind of argument strings can
> > Eli> be given for @var{encoding}?  If not, perhaps a list or at least a
> > Eli> hint where to find such a list would be useful.
> > 
> > We can't list the possible encodings -- not only does the list change
> > over time, but users can write their own codecs in Python.
> > 
> > I suggest just hoisting the reference to Python's "string.decode"
> > method to an earlier spot in the paragraph.  This should be sufficient
> > for anybody, use of the string module is common knowledge.
> 
> What about the following, then?
> 
> "If the optional @var{encoding} argument is given, it must be a string
> naming the encoding of the string in the @code{gdb.Value}.  It accepts
> the same encodings as the corresponding argument to Python's
> @code{string.decode} method, so the Python codec machinery will be used
> to convert the string."

I'd add an example, but if you think the above is enough, I won't
object.

Re: [RFA][python] Add gdb.Value.string method.

[Thiago Jung Bauermann]

El jue, 05-02-2009 a las 22:31 +0200, Eli Zaretskii escribió:
> > What about the following, then?
> > 
> > "If the optional @var{encoding} argument is given, it must be a string
> > naming the encoding of the string in the @code{gdb.Value}.  It accepts
> > the same encodings as the corresponding argument to Python's
> > @code{string.decode} method, so the Python codec machinery will be used
> > to convert the string."
> 
> I'd add an example, but if you think the above is enough, I won't
> object.

I added some examples, and committed the following. Thanks!
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center


gdb/
2009-02-05  Thiago Jung Bauermann  <bauerman@br.ibm.com>
	    Tom Tromey  <tromey@redhat.com>

	* python/python-utils.c (target_string_to_unicode): New function.
	* python/python-internal.h (target_string_to_unicode): New prototype.
	* python/python-value.c (valpy_string): New function.
	(value_object_methods): Add `string' entry.

gdb/doc/
2009-02-05  Tom Tromey  <tromey@redhat.com>

	* gdb.texinfo (Values From Inferior): Document Value.string.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 884f50b..ff92eb0 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18215,6 +18215,33 @@ The result @code{bar} will be a @code{gdb.Value} object holding the
 value pointed to by @code{foo}.
 @end defmethod
 
+@defmethod Value string @r{[}encoding @r{[}errors@r{]}@r{]}
+If this @code{gdb.Value} represents a string, then this method
+converts the contents to a Python string.  Otherwise, this method will
+throw an exception.
+
+Strings are recognized in a language-specific way; whether a given
+@code{gdb.Value} represents a string is determined by the current
+language.
+
+For C-like languages, a value is a string if it is a pointer to or an
+array of characters or ints.  The string is assumed to be terminated
+by a zero of the appropriate width.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the string in the @code{gdb.Value}, such as
+@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}.  It accepts
+the same encodings as the corresponding argument to Python's
+@code{string.decode} method, and the Python codec machinery will be used
+to convert the string.  If @var{encoding} is not given, or if
+@var{encoding} is the empty string, then either the @code{target-charset}
+(@pxref{Character Sets}) will be used, or a language-specific encoding
+will be used, if the current language is able to supply one.
+
+The optional @var{errors} argument is the same as the corresponding
+argument to Python's @code{string.decode} method.
+@end defmethod
+
 @node Interpreters
 @chapter Command Interpreters
 @cindex command interpreters
diff --git a/gdb/python/python-internal.h b/gdb/python/python-internal.h
index 672d8a4..1457928 100644
--- a/gdb/python/python-internal.h
+++ b/gdb/python/python-internal.h
@@ -91,6 +91,7 @@ PyObject *python_string_to_unicode (PyObject *obj);
 char *unicode_to_target_string (PyObject *unicode_str);
 char *python_string_to_target_string (PyObject *obj);
 char *python_string_to_host_string (PyObject *obj);
+PyObject *target_string_to_unicode (const gdb_byte *str, int length);
 int gdbpy_is_string (PyObject *obj);
 
 #endif /* GDB_PYTHON_INTERNAL_H */
diff --git a/gdb/python/python-utils.c b/gdb/python/python-utils.c
index 6a95939..b0ec7b3 100644
--- a/gdb/python/python-utils.c
+++ b/gdb/python/python-utils.c
@@ -160,6 +160,19 @@ python_string_to_host_string (PyObject *obj)
   return unicode_to_encoded_string (str, host_charset ());
 }
 
+/* Converts a target string of LENGTH bytes in the target's charset to a
+   Python Unicode string. If LENGTH is -1, convert until a null byte is found.
+
+   Returns NULL on error, with a python exception set.  */
+PyObject *
+target_string_to_unicode (const gdb_byte *str, int length)
+{
+  if (length == -1)
+    length = strlen (str);
+
+  return PyUnicode_Decode (str, length, target_charset (), NULL);
+}
+
 /* Return true if OBJ is a Python string or unicode object, false
    otherwise.  */
 
diff --git a/gdb/python/python-value.c b/gdb/python/python-value.c
index 420d26f..bc077b6 100644
--- a/gdb/python/python-value.c
+++ b/gdb/python/python-value.c
@@ -143,6 +143,37 @@ valpy_address (PyObject *self, PyObject *args)
   return value_to_value_object (res_val);
 }
 
+/* Return Unicode string with value contents (assumed to be encoded in the
+   target's charset).  */
+static PyObject *
+valpy_string (PyObject *self, PyObject *args)
+{
+  int length, ret = 0;
+  gdb_byte *buffer;
+  struct value *value = ((value_object *) self)->value;
+  volatile struct gdb_exception except;
+  PyObject *unicode;
+  const char *encoding = NULL;
+  const char *errors = NULL;
+  const char *user_encoding = NULL;
+  const char *la_encoding = NULL;
+
+  if (!PyArg_ParseTuple (args, "|ss", &user_encoding, &errors))
+    return NULL;
+
+  TRY_CATCH (except, RETURN_MASK_ALL)
+    {
+      LA_GET_STRING (value, &buffer, &length, &la_encoding);
+    }
+  GDB_PY_HANDLE_EXCEPTION (except);
+
+  encoding = (user_encoding && *user_encoding) ? user_encoding : la_encoding;
+  unicode = PyUnicode_Decode (buffer, length, encoding, errors);
+  xfree (buffer);
+
+  return unicode;
+}
+
 static Py_ssize_t
 valpy_length (PyObject *self)
 {
@@ -794,6 +825,8 @@ gdbpy_initialize_values (void)
 static PyMethodDef value_object_methods[] = {
   { "address", valpy_address, METH_NOARGS, "Return the address of the value." },
   { "dereference", valpy_dereference, METH_NOARGS, "Dereferences the value." },
+  { "string", valpy_string, METH_VARARGS,
+    "Return Unicode string representation of the value." },
   {NULL}  /* Sentinel */
 };