1 /* GDB parameters implemented in Python
3 Copyright (C) 2008-2013 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)
106 && ! PyUnicode_CompareWithASCIIString (attr_name, "value"))
108 && ! strcmp (PyString_AsString (attr_name), "value"))
111 parmpy_object *self = (parmpy_object *) obj;
113 return gdbpy_parameter_value (self->type, &self->value);
116 return PyObject_GenericGetAttr (obj, attr_name);
119 /* Set a parameter value from a Python value. Return 0 on success. Returns
120 -1 on error, with a python exception set. */
122 set_parameter_value (parmpy_object *self, PyObject *value)
129 case var_string_noescape:
130 case var_optional_filename:
132 if (! gdbpy_is_string (value)
133 && (self->type == var_filename
134 || value != Py_None))
136 PyErr_SetString (PyExc_RuntimeError,
137 _("String required for filename."));
141 if (value == Py_None)
143 xfree (self->value.stringval);
144 if (self->type == var_optional_filename)
145 self->value.stringval = xstrdup ("");
147 self->value.stringval = NULL;
153 string = python_string_to_host_string (value);
157 xfree (self->value.stringval);
158 self->value.stringval = string;
167 if (! gdbpy_is_string (value))
169 PyErr_SetString (PyExc_RuntimeError,
170 _("ENUM arguments must be a string."));
174 str = python_string_to_host_string (value);
177 for (i = 0; self->enumeration[i]; ++i)
178 if (! strcmp (self->enumeration[i], str))
181 if (! self->enumeration[i])
183 PyErr_SetString (PyExc_RuntimeError,
184 _("The value must be member of an enumeration."));
187 self->value.cstringval = self->enumeration[i];
192 if (! PyBool_Check (value))
194 PyErr_SetString (PyExc_RuntimeError,
195 _("A boolean argument is required."));
198 cmp = PyObject_IsTrue (value);
201 self->value.intval = cmp;
204 case var_auto_boolean:
205 if (! PyBool_Check (value) && value != Py_None)
207 PyErr_SetString (PyExc_RuntimeError,
208 _("A boolean or None is required"));
212 if (value == Py_None)
213 self->value.autoboolval = AUTO_BOOLEAN_AUTO;
216 cmp = PyObject_IsTrue (value);
220 self->value.autoboolval = AUTO_BOOLEAN_TRUE;
222 self->value.autoboolval = AUTO_BOOLEAN_FALSE;
233 if (! PyInt_Check (value))
235 PyErr_SetString (PyExc_RuntimeError,
236 _("The value must be integer."));
240 if (! gdb_py_int_as_long (value, &l))
243 if (self->type == var_uinteger)
245 ok = (l >= 0 && l <= UINT_MAX);
249 else if (self->type == var_integer)
251 ok = (l >= INT_MIN && l <= INT_MAX);
256 ok = (l >= INT_MIN && l <= INT_MAX);
260 PyErr_SetString (PyExc_RuntimeError,
261 _("Range exceeded."));
265 self->value.intval = (int) l;
270 PyErr_SetString (PyExc_RuntimeError,
271 _("Unhandled type in parameter value."));
278 /* Set an attribute. Returns -1 on error, with a python exception set. */
280 set_attr (PyObject *obj, PyObject *attr_name, PyObject *val)
282 if (PyString_Check (attr_name)
284 && ! PyUnicode_CompareWithASCIIString (attr_name, "value"))
286 && ! strcmp (PyString_AsString (attr_name), "value"))
291 PyErr_SetString (PyExc_RuntimeError,
292 _("Cannot delete a parameter's value."));
295 return set_parameter_value ((parmpy_object *) obj, val);
298 return PyObject_GenericSetAttr (obj, attr_name, val);
301 /* A helper function which returns a documentation string for an
305 get_doc_string (PyObject *object, PyObject *attr)
309 if (PyObject_HasAttr (object, attr))
311 PyObject *ds_obj = PyObject_GetAttr (object, attr);
313 if (ds_obj && gdbpy_is_string (ds_obj))
315 result = python_string_to_host_string (ds_obj);
317 gdbpy_print_stack ();
322 result = xstrdup (_("This command is not documented."));
326 /* Helper function which will execute a METHOD in OBJ passing the
327 argument ARG. ARG can be NULL. METHOD should return a Python
328 string. If this function returns NULL, there has been an error and
329 the appropriate exception set. */
331 call_doc_function (PyObject *obj, PyObject *method, PyObject *arg)
334 PyObject *result = PyObject_CallMethodObjArgs (obj, method, arg, NULL);
339 if (gdbpy_is_string (result))
341 data = python_string_to_host_string (result);
348 PyErr_SetString (PyExc_RuntimeError,
349 _("Parameter must return a string value."));
357 /* A callback function that is registered against the respective
358 add_setshow_* set_doc prototype. This function will either call
359 the Python function "get_set_string" or extract the Python
360 attribute "set_doc" and return the contents as a string. If
361 neither exist, insert a string indicating the Parameter is not
364 get_set_value (char *args, int from_tty,
365 struct cmd_list_element *c)
367 PyObject *obj = (PyObject *) get_cmd_context (c);
368 char *set_doc_string;
369 struct cleanup *cleanup = ensure_python_env (get_current_arch (),
371 PyObject *set_doc_func = PyString_FromString ("get_set_string");
376 make_cleanup_py_decref (set_doc_func);
378 if (PyObject_HasAttr (obj, set_doc_func))
380 set_doc_string = call_doc_function (obj, set_doc_func, NULL);
381 if (! set_doc_string)
386 /* We have to preserve the existing < GDB 7.3 API. If a
387 callback function does not exist, then attempt to read the
388 set_doc attribute. */
389 set_doc_string = get_doc_string (obj, set_doc_cst);
392 make_cleanup (xfree, set_doc_string);
393 fprintf_filtered (gdb_stdout, "%s\n", set_doc_string);
395 do_cleanups (cleanup);
399 gdbpy_print_stack ();
400 do_cleanups (cleanup);
404 /* A callback function that is registered against the respective
405 add_setshow_* show_doc prototype. This function will either call
406 the Python function "get_show_string" or extract the Python
407 attribute "show_doc" and return the contents as a string. If
408 neither exist, insert a string indicating the Parameter is not
411 get_show_value (struct ui_file *file, int from_tty,
412 struct cmd_list_element *c,
415 PyObject *obj = (PyObject *) get_cmd_context (c);
416 char *show_doc_string = NULL;
417 struct cleanup *cleanup = ensure_python_env (get_current_arch (),
419 PyObject *show_doc_func = PyString_FromString ("get_show_string");
424 make_cleanup_py_decref (show_doc_func);
426 if (PyObject_HasAttr (obj, show_doc_func))
428 PyObject *val_obj = PyString_FromString (value);
433 make_cleanup_py_decref (val_obj);
435 show_doc_string = call_doc_function (obj, show_doc_func, val_obj);
436 if (! show_doc_string)
439 make_cleanup (xfree, show_doc_string);
441 fprintf_filtered (file, "%s\n", show_doc_string);
445 /* We have to preserve the existing < GDB 7.3 API. If a
446 callback function does not exist, then attempt to read the
447 show_doc attribute. */
448 show_doc_string = get_doc_string (obj, show_doc_cst);
449 make_cleanup (xfree, show_doc_string);
450 fprintf_filtered (file, "%s %s\n", show_doc_string, value);
453 do_cleanups (cleanup);
457 gdbpy_print_stack ();
458 do_cleanups (cleanup);
463 /* A helper function that dispatches to the appropriate add_setshow
466 add_setshow_generic (int parmclass, enum command_class cmdclass,
467 char *cmd_name, parmpy_object *self,
468 char *set_doc, char *show_doc, char *help_doc,
469 struct cmd_list_element **set_list,
470 struct cmd_list_element **show_list)
472 struct cmd_list_element *param = NULL;
473 const char *tmp_name = NULL;
479 add_setshow_boolean_cmd (cmd_name, cmdclass,
480 &self->value.intval, set_doc, show_doc,
481 help_doc, get_set_value, get_show_value,
482 set_list, show_list);
486 case var_auto_boolean:
487 add_setshow_auto_boolean_cmd (cmd_name, cmdclass,
488 &self->value.autoboolval,
489 set_doc, show_doc, help_doc,
490 get_set_value, get_show_value,
491 set_list, show_list);
495 add_setshow_uinteger_cmd (cmd_name, cmdclass,
496 &self->value.uintval, set_doc, show_doc,
497 help_doc, get_set_value, get_show_value,
498 set_list, show_list);
502 add_setshow_integer_cmd (cmd_name, cmdclass,
503 &self->value.intval, set_doc, show_doc,
504 help_doc, get_set_value, get_show_value,
505 set_list, show_list); break;
508 add_setshow_string_cmd (cmd_name, cmdclass,
509 &self->value.stringval, set_doc, show_doc,
510 help_doc, get_set_value, get_show_value,
511 set_list, show_list); break;
513 case var_string_noescape:
514 add_setshow_string_noescape_cmd (cmd_name, cmdclass,
515 &self->value.stringval,
516 set_doc, show_doc, help_doc,
517 get_set_value, get_show_value,
518 set_list, show_list);
522 case var_optional_filename:
523 add_setshow_optional_filename_cmd (cmd_name, cmdclass,
524 &self->value.stringval, set_doc,
525 show_doc, help_doc, get_set_value,
526 get_show_value, set_list,
531 add_setshow_filename_cmd (cmd_name, cmdclass,
532 &self->value.stringval, set_doc, show_doc,
533 help_doc, get_set_value, get_show_value,
534 set_list, show_list); break;
537 add_setshow_zinteger_cmd (cmd_name, cmdclass,
538 &self->value.intval, set_doc, show_doc,
539 help_doc, get_set_value, get_show_value,
540 set_list, show_list);
544 add_setshow_enum_cmd (cmd_name, cmdclass, self->enumeration,
545 &self->value.cstringval, set_doc, show_doc,
546 help_doc, get_set_value, get_show_value,
547 set_list, show_list);
548 /* Initialize the value, just in case. */
549 self->value.cstringval = self->enumeration[0];
553 /* Lookup created parameter, and register Python object against the
554 parameter context. Perform this task against both lists. */
556 param = lookup_cmd (&tmp_name, *show_list, "", 0, 1);
558 set_cmd_context (param, self);
561 param = lookup_cmd (&tmp_name, *set_list, "", 0, 1);
563 set_cmd_context (param, self);
566 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
567 error, with a python exception set. */
569 compute_enum_values (parmpy_object *self, PyObject *enum_values)
572 struct cleanup *back_to;
576 PyErr_SetString (PyExc_RuntimeError,
577 _("An enumeration is required for PARAM_ENUM."));
581 if (! PySequence_Check (enum_values))
583 PyErr_SetString (PyExc_RuntimeError,
584 _("The enumeration is not a sequence."));
588 size = PySequence_Size (enum_values);
593 PyErr_SetString (PyExc_RuntimeError,
594 _("The enumeration is empty."));
598 self->enumeration = xmalloc ((size + 1) * sizeof (char *));
599 back_to = make_cleanup (free_current_contents, &self->enumeration);
600 memset (self->enumeration, 0, (size + 1) * sizeof (char *));
602 for (i = 0; i < size; ++i)
604 PyObject *item = PySequence_GetItem (enum_values, i);
608 do_cleanups (back_to);
611 if (! gdbpy_is_string (item))
613 do_cleanups (back_to);
614 PyErr_SetString (PyExc_RuntimeError,
615 _("The enumeration item not a string."));
618 self->enumeration[i] = python_string_to_host_string (item);
619 if (self->enumeration[i] == NULL)
621 do_cleanups (back_to);
624 make_cleanup (xfree, (char *) self->enumeration[i]);
627 discard_cleanups (back_to);
631 /* Object initializer; sets up gdb-side structures for command.
633 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
635 NAME is the name of the parameter. It may consist of multiple
636 words, in which case the final word is the name of the new command,
637 and earlier words must be prefix commands.
639 CMDCLASS is the kind of command. It should be one of the COMMAND_*
640 constants defined in the gdb module.
642 PARMCLASS is the type of the parameter. It should be one of the
643 PARAM_* constants defined in the gdb module.
645 If PARMCLASS is PARAM_ENUM, then the final argument should be a
646 collection of strings. These strings are the valid values for this
649 The documentation for the parameter is taken from the doc string
650 for the python class.
652 Returns -1 on error, with a python exception set. */
655 parmpy_init (PyObject *self, PyObject *args, PyObject *kwds)
657 parmpy_object *obj = (parmpy_object *) self;
659 char *set_doc, *show_doc, *doc;
661 int parmclass, cmdtype;
662 PyObject *enum_values = NULL;
663 struct cmd_list_element **set_list, **show_list;
664 volatile struct gdb_exception except;
666 if (! PyArg_ParseTuple (args, "sii|O", &name, &cmdtype, &parmclass,
670 if (cmdtype != no_class && cmdtype != class_run
671 && cmdtype != class_vars && cmdtype != class_stack
672 && cmdtype != class_files && cmdtype != class_support
673 && cmdtype != class_info && cmdtype != class_breakpoint
674 && cmdtype != class_trace && cmdtype != class_obscure
675 && cmdtype != class_maintenance)
677 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
681 if (parmclass != var_boolean /* ARI: var_boolean */
682 && parmclass != var_auto_boolean
683 && parmclass != var_uinteger && parmclass != var_integer
684 && parmclass != var_string && parmclass != var_string_noescape
685 && parmclass != var_optional_filename && parmclass != var_filename
686 && parmclass != var_zinteger && parmclass != var_enum)
688 PyErr_SetString (PyExc_RuntimeError,
689 _("Invalid parameter class argument."));
693 if (enum_values && parmclass != var_enum)
695 PyErr_SetString (PyExc_RuntimeError,
696 _("Only PARAM_ENUM accepts a fourth argument."));
699 if (parmclass == var_enum)
701 if (! compute_enum_values (obj, enum_values))
705 obj->enumeration = NULL;
706 obj->type = (enum var_types) parmclass;
707 memset (&obj->value, 0, sizeof (obj->value));
709 cmd_name = gdbpy_parse_command_name (name, &set_list,
715 cmd_name = gdbpy_parse_command_name (name, &show_list,
720 set_doc = get_doc_string (self, set_doc_cst);
721 show_doc = get_doc_string (self, show_doc_cst);
722 doc = get_doc_string (self, gdbpy_doc_cst);
726 TRY_CATCH (except, RETURN_MASK_ALL)
728 add_setshow_generic (parmclass, (enum command_class) cmdtype,
731 doc, set_list, show_list);
733 if (except.reason < 0)
740 PyErr_Format (except.reason == RETURN_QUIT
741 ? PyExc_KeyboardInterrupt : PyExc_RuntimeError,
742 "%s", except.message);
750 /* Initialize the 'parameters' module. */
752 gdbpy_initialize_parameters (void)
756 parmpy_object_type.tp_new = PyType_GenericNew;
757 if (PyType_Ready (&parmpy_object_type) < 0)
760 set_doc_cst = PyString_FromString ("set_doc");
763 show_doc_cst = PyString_FromString ("show_doc");
767 for (i = 0; parm_constants[i].name; ++i)
769 if (PyModule_AddIntConstant (gdb_module,
770 parm_constants[i].name,
771 parm_constants[i].value) < 0)
775 Py_INCREF (&parmpy_object_type);
776 PyModule_AddObject (gdb_module, "Parameter",
777 (PyObject *) &parmpy_object_type);
782 static PyTypeObject parmpy_object_type =
784 PyVarObject_HEAD_INIT (NULL, 0)
785 "gdb.Parameter", /*tp_name*/
786 sizeof (parmpy_object), /*tp_basicsize*/
795 0, /*tp_as_sequence*/
800 get_attr, /*tp_getattro*/
801 set_attr, /*tp_setattro*/
803 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
804 "GDB parameter object", /* tp_doc */
807 0, /* tp_richcompare */
808 0, /* tp_weaklistoffset */
816 0, /* tp_descr_get */
817 0, /* tp_descr_set */
818 0, /* tp_dictoffset */
819 parmpy_init, /* tp_init */