1 /* GDB parameters implemented in Python
3 Copyright (C) 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
5 This file is part of GDB.
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 3 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program. If not, see <http://www.gnu.org/licenses/>. */
23 #include "exceptions.h"
24 #include "python-internal.h"
27 #include "cli/cli-decode.h"
28 #include "completer.h"
30 #include "arch-utils.h"
32 /* Parameter constants and their values. */
39 struct parm_constant parm_constants[] =
41 { "PARAM_BOOLEAN", var_boolean }, /* ARI: var_boolean */
42 { "PARAM_AUTO_BOOLEAN", var_auto_boolean },
43 { "PARAM_UINTEGER", var_uinteger },
44 { "PARAM_INTEGER", var_integer },
45 { "PARAM_STRING", var_string },
46 { "PARAM_STRING_NOESCAPE", var_string_noescape },
47 { "PARAM_OPTIONAL_FILENAME", var_optional_filename },
48 { "PARAM_FILENAME", var_filename },
49 { "PARAM_ZINTEGER", var_zinteger },
50 { "PARAM_ENUM", var_enum },
54 /* A union that can hold anything described by enum var_types. */
57 /* Hold an integer value, for boolean and integer types. */
60 /* Hold an auto_boolean. */
61 enum auto_boolean autoboolval;
63 /* Hold an unsigned integer value, for uinteger. */
66 /* Hold a string, for the various string types. */
69 /* Hold a string, for enums. */
70 const char *cstringval;
73 /* A GDB parameter. */
78 /* The type of the parameter. */
81 /* The value of the parameter. */
82 union parmpy_variable value;
84 /* For an enum command, the possible values. The vector is
85 allocated with xmalloc, as is each element. It is
87 const char **enumeration;
90 typedef struct parmpy_object parmpy_object;
92 static PyTypeObject parmpy_object_type;
94 /* Some handy string constants. */
95 static PyObject *set_doc_cst;
96 static PyObject *show_doc_cst;
100 /* Get an attribute. */
102 get_attr (PyObject *obj, PyObject *attr_name)
104 if (PyString_Check (attr_name)
105 && ! strcmp (PyString_AsString (attr_name), "value"))
107 parmpy_object *self = (parmpy_object *) obj;
109 return gdbpy_parameter_value (self->type, &self->value);
112 return PyObject_GenericGetAttr (obj, attr_name);
115 /* Set a parameter value from a Python value. Return 0 on success. Returns
116 -1 on error, with a python exception set. */
118 set_parameter_value (parmpy_object *self, PyObject *value)
125 case var_string_noescape:
126 case var_optional_filename:
128 if (! gdbpy_is_string (value)
129 && (self->type == var_filename
130 || value != Py_None))
132 PyErr_SetString (PyExc_RuntimeError,
133 _("String required for filename."));
137 if (value == Py_None)
139 xfree (self->value.stringval);
140 if (self->type == var_optional_filename)
141 self->value.stringval = xstrdup ("");
143 self->value.stringval = NULL;
149 string = python_string_to_host_string (value);
153 xfree (self->value.stringval);
154 self->value.stringval = string;
163 if (! gdbpy_is_string (value))
165 PyErr_SetString (PyExc_RuntimeError,
166 _("ENUM arguments must be a string."));
170 str = python_string_to_host_string (value);
173 for (i = 0; self->enumeration[i]; ++i)
174 if (! strcmp (self->enumeration[i], str))
177 if (! self->enumeration[i])
179 PyErr_SetString (PyExc_RuntimeError,
180 _("The value must be member of an enumeration."));
183 self->value.cstringval = self->enumeration[i];
188 if (! PyBool_Check (value))
190 PyErr_SetString (PyExc_RuntimeError,
191 _("A boolean argument is required."));
194 cmp = PyObject_IsTrue (value);
197 self->value.intval = cmp;
200 case var_auto_boolean:
201 if (! PyBool_Check (value) && value != Py_None)
203 PyErr_SetString (PyExc_RuntimeError,
204 _("A boolean or None is required"));
208 if (value == Py_None)
209 self->value.autoboolval = AUTO_BOOLEAN_AUTO;
212 cmp = PyObject_IsTrue (value);
216 self->value.autoboolval = AUTO_BOOLEAN_TRUE;
218 self->value.autoboolval = AUTO_BOOLEAN_FALSE;
229 if (! PyInt_Check (value))
231 PyErr_SetString (PyExc_RuntimeError,
232 _("The value must be integer."));
236 if (! gdb_py_int_as_long (value, &l))
239 if (self->type == var_uinteger)
241 ok = (l >= 0 && l <= UINT_MAX);
245 else if (self->type == var_integer)
247 ok = (l >= INT_MIN && l <= INT_MAX);
252 ok = (l >= INT_MIN && l <= INT_MAX);
256 PyErr_SetString (PyExc_RuntimeError,
257 _("Range exceeded."));
261 self->value.intval = (int) l;
266 PyErr_SetString (PyExc_RuntimeError,
267 _("Unhandled type in parameter value."));
274 /* Set an attribute. Returns -1 on error, with a python exception set. */
276 set_attr (PyObject *obj, PyObject *attr_name, PyObject *val)
278 if (PyString_Check (attr_name)
279 && ! strcmp (PyString_AsString (attr_name), "value"))
283 PyErr_SetString (PyExc_RuntimeError,
284 _("Cannot delete a parameter's value."));
287 return set_parameter_value ((parmpy_object *) obj, val);
290 return PyObject_GenericSetAttr (obj, attr_name, val);
293 /* A helper function which returns a documentation string for an
297 get_doc_string (PyObject *object, PyObject *attr)
301 if (PyObject_HasAttr (object, attr))
303 PyObject *ds_obj = PyObject_GetAttr (object, attr);
305 if (ds_obj && gdbpy_is_string (ds_obj))
307 result = python_string_to_host_string (ds_obj);
309 gdbpy_print_stack ();
314 result = xstrdup (_("This command is not documented."));
318 /* Helper function which will execute a METHOD in OBJ passing the
319 argument ARG. ARG can be NULL. METHOD should return a Python
320 string. If this function returns NULL, there has been an error and
321 the appropriate exception set. */
323 call_doc_function (PyObject *obj, PyObject *method, PyObject *arg)
326 PyObject *result = PyObject_CallMethodObjArgs (obj, method, arg, NULL);
331 if (gdbpy_is_string (result))
333 data = python_string_to_host_string (result);
339 PyErr_SetString (PyExc_RuntimeError,
340 _("Parameter must return a string value."));
347 /* A callback function that is registered against the respective
348 add_setshow_* set_doc prototype. This function will either call
349 the Python function "get_set_string" or extract the Python
350 attribute "set_doc" and return the contents as a string. If
351 neither exist, insert a string indicating the Parameter is not
354 get_set_value (char *args, int from_tty,
355 struct cmd_list_element *c)
357 PyObject *obj = (PyObject *) get_cmd_context (c);
358 char *set_doc_string;
359 struct cleanup *cleanup = ensure_python_env (get_current_arch (),
361 PyObject *set_doc_func = PyString_FromString ("get_set_string");
366 make_cleanup_py_decref (set_doc_func);
368 if (PyObject_HasAttr (obj, set_doc_func))
370 set_doc_string = call_doc_function (obj, set_doc_func, NULL);
371 if (! set_doc_string)
376 /* We have to preserve the existing < GDB 7.3 API. If a
377 callback function does not exist, then attempt to read the
378 set_doc attribute. */
379 set_doc_string = get_doc_string (obj, set_doc_cst);
382 make_cleanup (xfree, set_doc_string);
383 fprintf_filtered (gdb_stdout, "%s\n", set_doc_string);
385 do_cleanups (cleanup);
389 gdbpy_print_stack ();
390 do_cleanups (cleanup);
394 /* A callback function that is registered against the respective
395 add_setshow_* show_doc prototype. This function will either call
396 the Python function "get_show_string" or extract the Python
397 attribute "show_doc" and return the contents as a string. If
398 neither exist, insert a string indicating the Parameter is not
401 get_show_value (struct ui_file *file, int from_tty,
402 struct cmd_list_element *c,
405 PyObject *obj = (PyObject *) get_cmd_context (c);
406 char *show_doc_string = NULL;
407 struct cleanup *cleanup = ensure_python_env (get_current_arch (),
409 PyObject *show_doc_func = PyString_FromString ("get_show_string");
414 make_cleanup_py_decref (show_doc_func);
416 if (PyObject_HasAttr (obj, show_doc_func))
418 PyObject *val_obj = PyString_FromString (value);
423 make_cleanup_py_decref (val_obj);
425 show_doc_string = call_doc_function (obj, show_doc_func, val_obj);
426 if (! show_doc_string)
429 make_cleanup (xfree, show_doc_string);
431 fprintf_filtered (file, "%s\n", show_doc_string);
435 /* We have to preserve the existing < GDB 7.3 API. If a
436 callback function does not exist, then attempt to read the
437 show_doc attribute. */
438 show_doc_string = get_doc_string (obj, show_doc_cst);
439 make_cleanup (xfree, show_doc_string);
440 fprintf_filtered (file, "%s %s\n", show_doc_string, value);
443 do_cleanups (cleanup);
447 gdbpy_print_stack ();
448 do_cleanups (cleanup);
453 /* A helper function that dispatches to the appropriate add_setshow
456 add_setshow_generic (int parmclass, enum command_class cmdclass,
457 char *cmd_name, parmpy_object *self,
458 char *set_doc, char *show_doc, char *help_doc,
459 struct cmd_list_element **set_list,
460 struct cmd_list_element **show_list)
462 struct cmd_list_element *param = NULL;
463 char *tmp_name = NULL;
469 add_setshow_boolean_cmd (cmd_name, cmdclass,
470 &self->value.intval, set_doc, show_doc,
471 help_doc, get_set_value, get_show_value,
472 set_list, show_list);
476 case var_auto_boolean:
477 add_setshow_auto_boolean_cmd (cmd_name, cmdclass,
478 &self->value.autoboolval,
479 set_doc, show_doc, help_doc,
480 get_set_value, get_show_value,
481 set_list, show_list);
485 add_setshow_uinteger_cmd (cmd_name, cmdclass,
486 &self->value.uintval, set_doc, show_doc,
487 help_doc, get_set_value, get_show_value,
488 set_list, show_list);
492 add_setshow_integer_cmd (cmd_name, cmdclass,
493 &self->value.intval, set_doc, show_doc,
494 help_doc, get_set_value, get_show_value,
495 set_list, show_list); break;
498 add_setshow_string_cmd (cmd_name, cmdclass,
499 &self->value.stringval, set_doc, show_doc,
500 help_doc, get_set_value, get_show_value,
501 set_list, show_list); break;
503 case var_string_noescape:
504 add_setshow_string_noescape_cmd (cmd_name, cmdclass,
505 &self->value.stringval,
506 set_doc, show_doc, help_doc,
507 get_set_value, get_show_value,
508 set_list, show_list);
512 case var_optional_filename:
513 add_setshow_optional_filename_cmd (cmd_name, cmdclass,
514 &self->value.stringval, set_doc,
515 show_doc, help_doc, get_set_value,
516 get_show_value, set_list,
521 add_setshow_filename_cmd (cmd_name, cmdclass,
522 &self->value.stringval, set_doc, show_doc,
523 help_doc, get_set_value, get_show_value,
524 set_list, show_list); break;
527 add_setshow_zinteger_cmd (cmd_name, cmdclass,
528 &self->value.intval, set_doc, show_doc,
529 help_doc, get_set_value, get_show_value,
530 set_list, show_list);
534 add_setshow_enum_cmd (cmd_name, cmdclass, self->enumeration,
535 &self->value.cstringval, set_doc, show_doc,
536 help_doc, get_set_value, get_show_value,
537 set_list, show_list);
538 /* Initialize the value, just in case. */
539 self->value.cstringval = self->enumeration[0];
543 /* Lookup created parameter, and register Python object against the
544 parameter context. Perform this task against both lists. */
546 param = lookup_cmd (&tmp_name, *show_list, "", 0, 1);
548 set_cmd_context (param, self);
551 param = lookup_cmd (&tmp_name, *set_list, "", 0, 1);
553 set_cmd_context (param, self);
556 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
557 error, with a python exception set. */
559 compute_enum_values (parmpy_object *self, PyObject *enum_values)
562 struct cleanup *back_to;
566 PyErr_SetString (PyExc_RuntimeError,
567 _("An enumeration is required for PARAM_ENUM."));
571 if (! PySequence_Check (enum_values))
573 PyErr_SetString (PyExc_RuntimeError,
574 _("The enumeration is not a sequence."));
578 size = PySequence_Size (enum_values);
583 PyErr_SetString (PyExc_RuntimeError,
584 _("The enumeration is empty."));
588 self->enumeration = xmalloc ((size + 1) * sizeof (char *));
589 back_to = make_cleanup (free_current_contents, &self->enumeration);
590 memset (self->enumeration, 0, (size + 1) * sizeof (char *));
592 for (i = 0; i < size; ++i)
594 PyObject *item = PySequence_GetItem (enum_values, i);
598 do_cleanups (back_to);
601 if (! gdbpy_is_string (item))
603 do_cleanups (back_to);
604 PyErr_SetString (PyExc_RuntimeError,
605 _("The enumeration item not a string."));
608 self->enumeration[i] = python_string_to_host_string (item);
609 if (self->enumeration[i] == NULL)
611 do_cleanups (back_to);
614 make_cleanup (xfree, (char *) self->enumeration[i]);
617 discard_cleanups (back_to);
621 /* Object initializer; sets up gdb-side structures for command.
623 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
625 NAME is the name of the parameter. It may consist of multiple
626 words, in which case the final word is the name of the new command,
627 and earlier words must be prefix commands.
629 CMDCLASS is the kind of command. It should be one of the COMMAND_*
630 constants defined in the gdb module.
632 PARMCLASS is the type of the parameter. It should be one of the
633 PARAM_* constants defined in the gdb module.
635 If PARMCLASS is PARAM_ENUM, then the final argument should be a
636 collection of strings. These strings are the valid values for this
639 The documentation for the parameter is taken from the doc string
640 for the python class.
642 Returns -1 on error, with a python exception set. */
645 parmpy_init (PyObject *self, PyObject *args, PyObject *kwds)
647 parmpy_object *obj = (parmpy_object *) self;
650 char *set_doc, *show_doc, *doc;
652 int parmclass, cmdtype;
653 PyObject *enum_values = NULL;
654 struct cmd_list_element **set_list, **show_list;
655 volatile struct gdb_exception except;
657 if (! PyArg_ParseTuple (args, "sii|O", &name, &cmdtype, &parmclass,
661 if (cmdtype != no_class && cmdtype != class_run
662 && cmdtype != class_vars && cmdtype != class_stack
663 && cmdtype != class_files && cmdtype != class_support
664 && cmdtype != class_info && cmdtype != class_breakpoint
665 && cmdtype != class_trace && cmdtype != class_obscure
666 && cmdtype != class_maintenance)
668 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
672 if (parmclass != var_boolean /* ARI: var_boolean */
673 && parmclass != var_auto_boolean
674 && parmclass != var_uinteger && parmclass != var_integer
675 && parmclass != var_string && parmclass != var_string_noescape
676 && parmclass != var_optional_filename && parmclass != var_filename
677 && parmclass != var_zinteger && parmclass != var_enum)
679 PyErr_SetString (PyExc_RuntimeError,
680 _("Invalid parameter class argument."));
684 if (enum_values && parmclass != var_enum)
686 PyErr_SetString (PyExc_RuntimeError,
687 _("Only PARAM_ENUM accepts a fourth argument."));
690 if (parmclass == var_enum)
692 if (! compute_enum_values (obj, enum_values))
696 obj->enumeration = NULL;
697 obj->type = (enum var_types) parmclass;
698 memset (&obj->value, 0, sizeof (obj->value));
700 copy = xstrdup (name);
701 cmd_name = gdbpy_parse_command_name (copy, &set_list,
710 cmd_name = gdbpy_parse_command_name (copy, &show_list,
716 set_doc = get_doc_string (self, set_doc_cst);
717 show_doc = get_doc_string (self, show_doc_cst);
718 doc = get_doc_string (self, gdbpy_doc_cst);
722 TRY_CATCH (except, RETURN_MASK_ALL)
724 add_setshow_generic (parmclass, (enum command_class) cmdtype,
727 doc, set_list, show_list);
729 if (except.reason < 0)
736 PyErr_Format (except.reason == RETURN_QUIT
737 ? PyExc_KeyboardInterrupt : PyExc_RuntimeError,
738 "%s", except.message);
746 /* Initialize the 'parameters' module. */
748 gdbpy_initialize_parameters (void)
752 parmpy_object_type.tp_new = PyType_GenericNew;
753 if (PyType_Ready (&parmpy_object_type) < 0)
756 set_doc_cst = PyString_FromString ("set_doc");
759 show_doc_cst = PyString_FromString ("show_doc");
763 for (i = 0; parm_constants[i].name; ++i)
765 if (PyModule_AddIntConstant (gdb_module,
766 parm_constants[i].name,
767 parm_constants[i].value) < 0)
771 Py_INCREF (&parmpy_object_type);
772 PyModule_AddObject (gdb_module, "Parameter",
773 (PyObject *) &parmpy_object_type);
778 static PyTypeObject parmpy_object_type =
780 PyObject_HEAD_INIT (NULL)
782 "gdb.Parameter", /*tp_name*/
783 sizeof (parmpy_object), /*tp_basicsize*/
792 0, /*tp_as_sequence*/
797 get_attr, /*tp_getattro*/
798 set_attr, /*tp_setattro*/
800 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
801 "GDB parameter object", /* tp_doc */
804 0, /* tp_richcompare */
805 0, /* tp_weaklistoffset */
813 0, /* tp_descr_get */
814 0, /* tp_descr_set */
815 0, /* tp_dictoffset */
816 parmpy_init, /* tp_init */