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
93 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("parmpy_object");
95 /* Some handy string constants. */
96 static PyObject *set_doc_cst;
97 static PyObject *show_doc_cst;
101 /* Get an attribute. */
103 get_attr (PyObject *obj, PyObject *attr_name)
105 if (PyString_Check (attr_name)
107 && ! PyUnicode_CompareWithASCIIString (attr_name, "value"))
109 && ! strcmp (PyString_AsString (attr_name), "value"))
112 parmpy_object *self = (parmpy_object *) obj;
114 return gdbpy_parameter_value (self->type, &self->value);
117 return PyObject_GenericGetAttr (obj, attr_name);
120 /* Set a parameter value from a Python value. Return 0 on success. Returns
121 -1 on error, with a python exception set. */
123 set_parameter_value (parmpy_object *self, PyObject *value)
130 case var_string_noescape:
131 case var_optional_filename:
133 if (! gdbpy_is_string (value)
134 && (self->type == var_filename
135 || value != Py_None))
137 PyErr_SetString (PyExc_RuntimeError,
138 _("String required for filename."));
142 if (value == Py_None)
144 xfree (self->value.stringval);
145 if (self->type == var_optional_filename)
146 self->value.stringval = xstrdup ("");
148 self->value.stringval = NULL;
154 string = python_string_to_host_string (value);
158 xfree (self->value.stringval);
159 self->value.stringval = string;
168 if (! gdbpy_is_string (value))
170 PyErr_SetString (PyExc_RuntimeError,
171 _("ENUM arguments must be a string."));
175 str = python_string_to_host_string (value);
178 for (i = 0; self->enumeration[i]; ++i)
179 if (! strcmp (self->enumeration[i], str))
182 if (! self->enumeration[i])
184 PyErr_SetString (PyExc_RuntimeError,
185 _("The value must be member of an enumeration."));
188 self->value.cstringval = self->enumeration[i];
193 if (! PyBool_Check (value))
195 PyErr_SetString (PyExc_RuntimeError,
196 _("A boolean argument is required."));
199 cmp = PyObject_IsTrue (value);
202 self->value.intval = cmp;
205 case var_auto_boolean:
206 if (! PyBool_Check (value) && value != Py_None)
208 PyErr_SetString (PyExc_RuntimeError,
209 _("A boolean or None is required"));
213 if (value == Py_None)
214 self->value.autoboolval = AUTO_BOOLEAN_AUTO;
217 cmp = PyObject_IsTrue (value);
221 self->value.autoboolval = AUTO_BOOLEAN_TRUE;
223 self->value.autoboolval = AUTO_BOOLEAN_FALSE;
234 if (! PyInt_Check (value))
236 PyErr_SetString (PyExc_RuntimeError,
237 _("The value must be integer."));
241 if (! gdb_py_int_as_long (value, &l))
244 if (self->type == var_uinteger)
246 ok = (l >= 0 && l <= UINT_MAX);
250 else if (self->type == var_integer)
252 ok = (l >= INT_MIN && l <= INT_MAX);
257 ok = (l >= INT_MIN && l <= INT_MAX);
261 PyErr_SetString (PyExc_RuntimeError,
262 _("Range exceeded."));
266 self->value.intval = (int) l;
271 PyErr_SetString (PyExc_RuntimeError,
272 _("Unhandled type in parameter value."));
279 /* Set an attribute. Returns -1 on error, with a python exception set. */
281 set_attr (PyObject *obj, PyObject *attr_name, PyObject *val)
283 if (PyString_Check (attr_name)
285 && ! PyUnicode_CompareWithASCIIString (attr_name, "value"))
287 && ! strcmp (PyString_AsString (attr_name), "value"))
292 PyErr_SetString (PyExc_RuntimeError,
293 _("Cannot delete a parameter's value."));
296 return set_parameter_value ((parmpy_object *) obj, val);
299 return PyObject_GenericSetAttr (obj, attr_name, val);
302 /* A helper function which returns a documentation string for an
306 get_doc_string (PyObject *object, PyObject *attr)
310 if (PyObject_HasAttr (object, attr))
312 PyObject *ds_obj = PyObject_GetAttr (object, attr);
314 if (ds_obj && gdbpy_is_string (ds_obj))
316 result = python_string_to_host_string (ds_obj);
318 gdbpy_print_stack ();
323 result = xstrdup (_("This command is not documented."));
327 /* Helper function which will execute a METHOD in OBJ passing the
328 argument ARG. ARG can be NULL. METHOD should return a Python
329 string. If this function returns NULL, there has been an error and
330 the appropriate exception set. */
332 call_doc_function (PyObject *obj, PyObject *method, PyObject *arg)
335 PyObject *result = PyObject_CallMethodObjArgs (obj, method, arg, NULL);
340 if (gdbpy_is_string (result))
342 data = python_string_to_host_string (result);
349 PyErr_SetString (PyExc_RuntimeError,
350 _("Parameter must return a string value."));
358 /* A callback function that is registered against the respective
359 add_setshow_* set_doc prototype. This function will either call
360 the Python function "get_set_string" or extract the Python
361 attribute "set_doc" and return the contents as a string. If
362 neither exist, insert a string indicating the Parameter is not
365 get_set_value (char *args, int from_tty,
366 struct cmd_list_element *c)
368 PyObject *obj = (PyObject *) get_cmd_context (c);
369 char *set_doc_string;
370 struct cleanup *cleanup = ensure_python_env (get_current_arch (),
372 PyObject *set_doc_func = PyString_FromString ("get_set_string");
377 make_cleanup_py_decref (set_doc_func);
379 if (PyObject_HasAttr (obj, set_doc_func))
381 set_doc_string = call_doc_function (obj, set_doc_func, NULL);
382 if (! set_doc_string)
387 /* We have to preserve the existing < GDB 7.3 API. If a
388 callback function does not exist, then attempt to read the
389 set_doc attribute. */
390 set_doc_string = get_doc_string (obj, set_doc_cst);
393 make_cleanup (xfree, set_doc_string);
394 fprintf_filtered (gdb_stdout, "%s\n", set_doc_string);
396 do_cleanups (cleanup);
400 gdbpy_print_stack ();
401 do_cleanups (cleanup);
405 /* A callback function that is registered against the respective
406 add_setshow_* show_doc prototype. This function will either call
407 the Python function "get_show_string" or extract the Python
408 attribute "show_doc" and return the contents as a string. If
409 neither exist, insert a string indicating the Parameter is not
412 get_show_value (struct ui_file *file, int from_tty,
413 struct cmd_list_element *c,
416 PyObject *obj = (PyObject *) get_cmd_context (c);
417 char *show_doc_string = NULL;
418 struct cleanup *cleanup = ensure_python_env (get_current_arch (),
420 PyObject *show_doc_func = PyString_FromString ("get_show_string");
425 make_cleanup_py_decref (show_doc_func);
427 if (PyObject_HasAttr (obj, show_doc_func))
429 PyObject *val_obj = PyString_FromString (value);
434 make_cleanup_py_decref (val_obj);
436 show_doc_string = call_doc_function (obj, show_doc_func, val_obj);
437 if (! show_doc_string)
440 make_cleanup (xfree, show_doc_string);
442 fprintf_filtered (file, "%s\n", show_doc_string);
446 /* We have to preserve the existing < GDB 7.3 API. If a
447 callback function does not exist, then attempt to read the
448 show_doc attribute. */
449 show_doc_string = get_doc_string (obj, show_doc_cst);
450 make_cleanup (xfree, show_doc_string);
451 fprintf_filtered (file, "%s %s\n", show_doc_string, value);
454 do_cleanups (cleanup);
458 gdbpy_print_stack ();
459 do_cleanups (cleanup);
464 /* A helper function that dispatches to the appropriate add_setshow
467 add_setshow_generic (int parmclass, enum command_class cmdclass,
468 char *cmd_name, parmpy_object *self,
469 char *set_doc, char *show_doc, char *help_doc,
470 struct cmd_list_element **set_list,
471 struct cmd_list_element **show_list)
473 struct cmd_list_element *param = NULL;
474 const char *tmp_name = NULL;
480 add_setshow_boolean_cmd (cmd_name, cmdclass,
481 &self->value.intval, set_doc, show_doc,
482 help_doc, get_set_value, get_show_value,
483 set_list, show_list);
487 case var_auto_boolean:
488 add_setshow_auto_boolean_cmd (cmd_name, cmdclass,
489 &self->value.autoboolval,
490 set_doc, show_doc, help_doc,
491 get_set_value, get_show_value,
492 set_list, show_list);
496 add_setshow_uinteger_cmd (cmd_name, cmdclass,
497 &self->value.uintval, set_doc, show_doc,
498 help_doc, get_set_value, get_show_value,
499 set_list, show_list);
503 add_setshow_integer_cmd (cmd_name, cmdclass,
504 &self->value.intval, set_doc, show_doc,
505 help_doc, get_set_value, get_show_value,
506 set_list, show_list); break;
509 add_setshow_string_cmd (cmd_name, cmdclass,
510 &self->value.stringval, set_doc, show_doc,
511 help_doc, get_set_value, get_show_value,
512 set_list, show_list); break;
514 case var_string_noescape:
515 add_setshow_string_noescape_cmd (cmd_name, cmdclass,
516 &self->value.stringval,
517 set_doc, show_doc, help_doc,
518 get_set_value, get_show_value,
519 set_list, show_list);
523 case var_optional_filename:
524 add_setshow_optional_filename_cmd (cmd_name, cmdclass,
525 &self->value.stringval, set_doc,
526 show_doc, help_doc, get_set_value,
527 get_show_value, set_list,
532 add_setshow_filename_cmd (cmd_name, cmdclass,
533 &self->value.stringval, set_doc, show_doc,
534 help_doc, get_set_value, get_show_value,
535 set_list, show_list); break;
538 add_setshow_zinteger_cmd (cmd_name, cmdclass,
539 &self->value.intval, set_doc, show_doc,
540 help_doc, get_set_value, get_show_value,
541 set_list, show_list);
545 add_setshow_enum_cmd (cmd_name, cmdclass, self->enumeration,
546 &self->value.cstringval, set_doc, show_doc,
547 help_doc, get_set_value, get_show_value,
548 set_list, show_list);
549 /* Initialize the value, just in case. */
550 self->value.cstringval = self->enumeration[0];
554 /* Lookup created parameter, and register Python object against the
555 parameter context. Perform this task against both lists. */
557 param = lookup_cmd (&tmp_name, *show_list, "", 0, 1);
559 set_cmd_context (param, self);
562 param = lookup_cmd (&tmp_name, *set_list, "", 0, 1);
564 set_cmd_context (param, self);
567 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
568 error, with a python exception set. */
570 compute_enum_values (parmpy_object *self, PyObject *enum_values)
573 struct cleanup *back_to;
577 PyErr_SetString (PyExc_RuntimeError,
578 _("An enumeration is required for PARAM_ENUM."));
582 if (! PySequence_Check (enum_values))
584 PyErr_SetString (PyExc_RuntimeError,
585 _("The enumeration is not a sequence."));
589 size = PySequence_Size (enum_values);
594 PyErr_SetString (PyExc_RuntimeError,
595 _("The enumeration is empty."));
599 self->enumeration = xmalloc ((size + 1) * sizeof (char *));
600 back_to = make_cleanup (free_current_contents, &self->enumeration);
601 memset (self->enumeration, 0, (size + 1) * sizeof (char *));
603 for (i = 0; i < size; ++i)
605 PyObject *item = PySequence_GetItem (enum_values, i);
609 do_cleanups (back_to);
612 if (! gdbpy_is_string (item))
614 do_cleanups (back_to);
615 PyErr_SetString (PyExc_RuntimeError,
616 _("The enumeration item not a string."));
619 self->enumeration[i] = python_string_to_host_string (item);
620 if (self->enumeration[i] == NULL)
622 do_cleanups (back_to);
625 make_cleanup (xfree, (char *) self->enumeration[i]);
628 discard_cleanups (back_to);
632 /* Object initializer; sets up gdb-side structures for command.
634 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
636 NAME is the name of the parameter. It may consist of multiple
637 words, in which case the final word is the name of the new command,
638 and earlier words must be prefix commands.
640 CMDCLASS is the kind of command. It should be one of the COMMAND_*
641 constants defined in the gdb module.
643 PARMCLASS is the type of the parameter. It should be one of the
644 PARAM_* constants defined in the gdb module.
646 If PARMCLASS is PARAM_ENUM, then the final argument should be a
647 collection of strings. These strings are the valid values for this
650 The documentation for the parameter is taken from the doc string
651 for the python class.
653 Returns -1 on error, with a python exception set. */
656 parmpy_init (PyObject *self, PyObject *args, PyObject *kwds)
658 parmpy_object *obj = (parmpy_object *) self;
660 char *set_doc, *show_doc, *doc;
662 int parmclass, cmdtype;
663 PyObject *enum_values = NULL;
664 struct cmd_list_element **set_list, **show_list;
665 volatile struct gdb_exception except;
667 if (! PyArg_ParseTuple (args, "sii|O", &name, &cmdtype, &parmclass,
671 if (cmdtype != no_class && cmdtype != class_run
672 && cmdtype != class_vars && cmdtype != class_stack
673 && cmdtype != class_files && cmdtype != class_support
674 && cmdtype != class_info && cmdtype != class_breakpoint
675 && cmdtype != class_trace && cmdtype != class_obscure
676 && cmdtype != class_maintenance)
678 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
682 if (parmclass != var_boolean /* ARI: var_boolean */
683 && parmclass != var_auto_boolean
684 && parmclass != var_uinteger && parmclass != var_integer
685 && parmclass != var_string && parmclass != var_string_noescape
686 && parmclass != var_optional_filename && parmclass != var_filename
687 && parmclass != var_zinteger && parmclass != var_enum)
689 PyErr_SetString (PyExc_RuntimeError,
690 _("Invalid parameter class argument."));
694 if (enum_values && parmclass != var_enum)
696 PyErr_SetString (PyExc_RuntimeError,
697 _("Only PARAM_ENUM accepts a fourth argument."));
700 if (parmclass == var_enum)
702 if (! compute_enum_values (obj, enum_values))
706 obj->enumeration = NULL;
707 obj->type = (enum var_types) parmclass;
708 memset (&obj->value, 0, sizeof (obj->value));
710 cmd_name = gdbpy_parse_command_name (name, &set_list,
716 cmd_name = gdbpy_parse_command_name (name, &show_list,
721 set_doc = get_doc_string (self, set_doc_cst);
722 show_doc = get_doc_string (self, show_doc_cst);
723 doc = get_doc_string (self, gdbpy_doc_cst);
727 TRY_CATCH (except, RETURN_MASK_ALL)
729 add_setshow_generic (parmclass, (enum command_class) cmdtype,
732 doc, set_list, show_list);
734 if (except.reason < 0)
741 PyErr_Format (except.reason == RETURN_QUIT
742 ? PyExc_KeyboardInterrupt : PyExc_RuntimeError,
743 "%s", except.message);
751 /* Initialize the 'parameters' module. */
753 gdbpy_initialize_parameters (void)
757 parmpy_object_type.tp_new = PyType_GenericNew;
758 if (PyType_Ready (&parmpy_object_type) < 0)
761 set_doc_cst = PyString_FromString ("set_doc");
764 show_doc_cst = PyString_FromString ("show_doc");
768 for (i = 0; parm_constants[i].name; ++i)
770 if (PyModule_AddIntConstant (gdb_module,
771 parm_constants[i].name,
772 parm_constants[i].value) < 0)
776 Py_INCREF (&parmpy_object_type);
777 PyModule_AddObject (gdb_module, "Parameter",
778 (PyObject *) &parmpy_object_type);
783 static PyTypeObject parmpy_object_type =
785 PyVarObject_HEAD_INIT (NULL, 0)
786 "gdb.Parameter", /*tp_name*/
787 sizeof (parmpy_object), /*tp_basicsize*/
796 0, /*tp_as_sequence*/
801 get_attr, /*tp_getattro*/
802 set_attr, /*tp_setattro*/
804 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
805 "GDB parameter object", /* tp_doc */
808 0, /* tp_richcompare */
809 0, /* tp_weaklistoffset */
817 0, /* tp_descr_get */
818 0, /* tp_descr_set */
819 0, /* tp_dictoffset */
820 parmpy_init, /* tp_init */