1 /* GDB parameters implemented in Python
3 Copyright (C) 2008-2016 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 "python-internal.h"
26 #include "cli/cli-decode.h"
27 #include "completer.h"
29 #include "arch-utils.h"
31 /* Parameter constants and their values. */
38 struct parm_constant parm_constants
[] =
40 { "PARAM_BOOLEAN", var_boolean
}, /* ARI: var_boolean */
41 { "PARAM_AUTO_BOOLEAN", var_auto_boolean
},
42 { "PARAM_UINTEGER", var_uinteger
},
43 { "PARAM_INTEGER", var_integer
},
44 { "PARAM_STRING", var_string
},
45 { "PARAM_STRING_NOESCAPE", var_string_noescape
},
46 { "PARAM_OPTIONAL_FILENAME", var_optional_filename
},
47 { "PARAM_FILENAME", var_filename
},
48 { "PARAM_ZINTEGER", var_zinteger
},
49 { "PARAM_ENUM", var_enum
},
53 /* A union that can hold anything described by enum var_types. */
56 /* Hold an integer value, for boolean and integer types. */
59 /* Hold an auto_boolean. */
60 enum auto_boolean autoboolval
;
62 /* Hold an unsigned integer value, for uinteger. */
65 /* Hold a string, for the various string types. */
68 /* Hold a string, for enums. */
69 const char *cstringval
;
72 /* A GDB parameter. */
77 /* The type of the parameter. */
80 /* The value of the parameter. */
81 union parmpy_variable value
;
83 /* For an enum command, the possible values. The vector is
84 allocated with xmalloc, as is each element. It is
86 const char **enumeration
;
89 typedef struct parmpy_object parmpy_object
;
91 extern PyTypeObject parmpy_object_type
92 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("parmpy_object");
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
;
151 gdb::unique_xmalloc_ptr
<char>
152 string (python_string_to_host_string (value
));
156 xfree (self
->value
.stringval
);
157 self
->value
.stringval
= string
.release ();
165 if (! gdbpy_is_string (value
))
167 PyErr_SetString (PyExc_RuntimeError
,
168 _("ENUM arguments must be a string."));
172 gdb::unique_xmalloc_ptr
<char>
173 str (python_string_to_host_string (value
));
176 for (i
= 0; self
->enumeration
[i
]; ++i
)
177 if (! strcmp (self
->enumeration
[i
], str
.get ()))
179 if (! self
->enumeration
[i
])
181 PyErr_SetString (PyExc_RuntimeError
,
182 _("The value must be member of an enumeration."));
185 self
->value
.cstringval
= self
->enumeration
[i
];
190 if (! PyBool_Check (value
))
192 PyErr_SetString (PyExc_RuntimeError
,
193 _("A boolean argument is required."));
196 cmp
= PyObject_IsTrue (value
);
199 self
->value
.intval
= cmp
;
202 case var_auto_boolean
:
203 if (! PyBool_Check (value
) && value
!= Py_None
)
205 PyErr_SetString (PyExc_RuntimeError
,
206 _("A boolean or None is required"));
210 if (value
== Py_None
)
211 self
->value
.autoboolval
= AUTO_BOOLEAN_AUTO
;
214 cmp
= PyObject_IsTrue (value
);
218 self
->value
.autoboolval
= AUTO_BOOLEAN_TRUE
;
220 self
->value
.autoboolval
= AUTO_BOOLEAN_FALSE
;
231 if (! PyInt_Check (value
))
233 PyErr_SetString (PyExc_RuntimeError
,
234 _("The value must be integer."));
238 if (! gdb_py_int_as_long (value
, &l
))
241 if (self
->type
== var_uinteger
)
243 ok
= (l
>= 0 && l
<= UINT_MAX
);
247 else if (self
->type
== var_integer
)
249 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
254 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
258 PyErr_SetString (PyExc_RuntimeError
,
259 _("Range exceeded."));
263 self
->value
.intval
= (int) l
;
268 PyErr_SetString (PyExc_RuntimeError
,
269 _("Unhandled type in parameter value."));
276 /* Set an attribute. Returns -1 on error, with a python exception set. */
278 set_attr (PyObject
*obj
, PyObject
*attr_name
, PyObject
*val
)
280 if (PyString_Check (attr_name
)
282 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
284 && ! strcmp (PyString_AsString (attr_name
), "value"))
289 PyErr_SetString (PyExc_RuntimeError
,
290 _("Cannot delete a parameter's value."));
293 return set_parameter_value ((parmpy_object
*) obj
, val
);
296 return PyObject_GenericSetAttr (obj
, attr_name
, val
);
299 /* A helper function which returns a documentation string for an
302 static gdb::unique_xmalloc_ptr
<char>
303 get_doc_string (PyObject
*object
, PyObject
*attr
)
305 gdb::unique_xmalloc_ptr
<char> result
;
307 if (PyObject_HasAttr (object
, attr
))
309 PyObject
*ds_obj
= PyObject_GetAttr (object
, attr
);
311 if (ds_obj
&& gdbpy_is_string (ds_obj
))
313 result
= python_string_to_host_string (ds_obj
);
315 gdbpy_print_stack ();
320 result
.reset (xstrdup (_("This command is not documented.")));
324 /* Helper function which will execute a METHOD in OBJ passing the
325 argument ARG. ARG can be NULL. METHOD should return a Python
326 string. If this function returns NULL, there has been an error and
327 the appropriate exception set. */
328 static gdb::unique_xmalloc_ptr
<char>
329 call_doc_function (PyObject
*obj
, PyObject
*method
, PyObject
*arg
)
331 gdb::unique_xmalloc_ptr
<char> data
;
332 PyObject
*result
= PyObject_CallMethodObjArgs (obj
, method
, arg
, NULL
);
337 if (gdbpy_is_string (result
))
339 data
= python_string_to_host_string (result
);
346 PyErr_SetString (PyExc_RuntimeError
,
347 _("Parameter must return a string value."));
355 /* A callback function that is registered against the respective
356 add_setshow_* set_doc prototype. This function will either call
357 the Python function "get_set_string" or extract the Python
358 attribute "set_doc" and return the contents as a string. If
359 neither exist, insert a string indicating the Parameter is not
362 get_set_value (char *args
, int from_tty
,
363 struct cmd_list_element
*c
)
365 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
366 gdb::unique_xmalloc_ptr
<char> set_doc_string
;
367 struct cleanup
*cleanup
= ensure_python_env (get_current_arch (),
369 PyObject
*set_doc_func
= PyString_FromString ("get_set_string");
374 if (PyObject_HasAttr (obj
, set_doc_func
))
376 set_doc_string
= call_doc_function (obj
, set_doc_func
, NULL
);
377 if (! set_doc_string
)
382 /* We have to preserve the existing < GDB 7.3 API. If a
383 callback function does not exist, then attempt to read the
384 set_doc attribute. */
385 set_doc_string
= get_doc_string (obj
, set_doc_cst
);
388 fprintf_filtered (gdb_stdout
, "%s\n", set_doc_string
.get ());
390 Py_XDECREF (set_doc_func
);
391 do_cleanups (cleanup
);
395 Py_XDECREF (set_doc_func
);
396 gdbpy_print_stack ();
397 do_cleanups (cleanup
);
401 /* A callback function that is registered against the respective
402 add_setshow_* show_doc prototype. This function will either call
403 the Python function "get_show_string" or extract the Python
404 attribute "show_doc" and return the contents as a string. If
405 neither exist, insert a string indicating the Parameter is not
408 get_show_value (struct ui_file
*file
, int from_tty
,
409 struct cmd_list_element
*c
,
412 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
413 gdb::unique_xmalloc_ptr
<char> show_doc_string
;
414 struct cleanup
*cleanup
= ensure_python_env (get_current_arch (),
416 PyObject
*show_doc_func
= PyString_FromString ("get_show_string");
421 if (PyObject_HasAttr (obj
, show_doc_func
))
423 PyObject
*val_obj
= PyString_FromString (value
);
428 show_doc_string
= call_doc_function (obj
, show_doc_func
, val_obj
);
430 if (! show_doc_string
)
433 fprintf_filtered (file
, "%s\n", show_doc_string
.get ());
437 /* We have to preserve the existing < GDB 7.3 API. If a
438 callback function does not exist, then attempt to read the
439 show_doc attribute. */
440 show_doc_string
= get_doc_string (obj
, show_doc_cst
);
441 fprintf_filtered (file
, "%s %s\n", show_doc_string
.get (), value
);
444 Py_XDECREF (show_doc_func
);
445 do_cleanups (cleanup
);
449 Py_XDECREF (show_doc_func
);
450 gdbpy_print_stack ();
451 do_cleanups (cleanup
);
456 /* A helper function that dispatches to the appropriate add_setshow
459 add_setshow_generic (int parmclass
, enum command_class cmdclass
,
460 char *cmd_name
, parmpy_object
*self
,
461 char *set_doc
, char *show_doc
, char *help_doc
,
462 struct cmd_list_element
**set_list
,
463 struct cmd_list_element
**show_list
)
465 struct cmd_list_element
*param
= NULL
;
466 const char *tmp_name
= NULL
;
472 add_setshow_boolean_cmd (cmd_name
, cmdclass
,
473 &self
->value
.intval
, set_doc
, show_doc
,
474 help_doc
, get_set_value
, get_show_value
,
475 set_list
, show_list
);
479 case var_auto_boolean
:
480 add_setshow_auto_boolean_cmd (cmd_name
, cmdclass
,
481 &self
->value
.autoboolval
,
482 set_doc
, show_doc
, help_doc
,
483 get_set_value
, get_show_value
,
484 set_list
, show_list
);
488 add_setshow_uinteger_cmd (cmd_name
, cmdclass
,
489 &self
->value
.uintval
, set_doc
, show_doc
,
490 help_doc
, get_set_value
, get_show_value
,
491 set_list
, show_list
);
495 add_setshow_integer_cmd (cmd_name
, cmdclass
,
496 &self
->value
.intval
, set_doc
, show_doc
,
497 help_doc
, get_set_value
, get_show_value
,
498 set_list
, show_list
); break;
501 add_setshow_string_cmd (cmd_name
, cmdclass
,
502 &self
->value
.stringval
, set_doc
, show_doc
,
503 help_doc
, get_set_value
, get_show_value
,
504 set_list
, show_list
); break;
506 case var_string_noescape
:
507 add_setshow_string_noescape_cmd (cmd_name
, cmdclass
,
508 &self
->value
.stringval
,
509 set_doc
, show_doc
, help_doc
,
510 get_set_value
, get_show_value
,
511 set_list
, show_list
);
515 case var_optional_filename
:
516 add_setshow_optional_filename_cmd (cmd_name
, cmdclass
,
517 &self
->value
.stringval
, set_doc
,
518 show_doc
, help_doc
, get_set_value
,
519 get_show_value
, set_list
,
524 add_setshow_filename_cmd (cmd_name
, cmdclass
,
525 &self
->value
.stringval
, set_doc
, show_doc
,
526 help_doc
, get_set_value
, get_show_value
,
527 set_list
, show_list
); break;
530 add_setshow_zinteger_cmd (cmd_name
, cmdclass
,
531 &self
->value
.intval
, set_doc
, show_doc
,
532 help_doc
, get_set_value
, get_show_value
,
533 set_list
, show_list
);
537 add_setshow_enum_cmd (cmd_name
, cmdclass
, self
->enumeration
,
538 &self
->value
.cstringval
, set_doc
, show_doc
,
539 help_doc
, get_set_value
, get_show_value
,
540 set_list
, show_list
);
541 /* Initialize the value, just in case. */
542 self
->value
.cstringval
= self
->enumeration
[0];
546 /* Lookup created parameter, and register Python object against the
547 parameter context. Perform this task against both lists. */
549 param
= lookup_cmd (&tmp_name
, *show_list
, "", 0, 1);
551 set_cmd_context (param
, self
);
554 param
= lookup_cmd (&tmp_name
, *set_list
, "", 0, 1);
556 set_cmd_context (param
, self
);
559 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
560 error, with a python exception set. */
562 compute_enum_values (parmpy_object
*self
, PyObject
*enum_values
)
565 struct cleanup
*back_to
;
569 PyErr_SetString (PyExc_RuntimeError
,
570 _("An enumeration is required for PARAM_ENUM."));
574 if (! PySequence_Check (enum_values
))
576 PyErr_SetString (PyExc_RuntimeError
,
577 _("The enumeration is not a sequence."));
581 size
= PySequence_Size (enum_values
);
586 PyErr_SetString (PyExc_RuntimeError
,
587 _("The enumeration is empty."));
591 self
->enumeration
= XCNEWVEC (const char *, size
+ 1);
592 back_to
= make_cleanup (free_current_contents
, &self
->enumeration
);
594 for (i
= 0; i
< size
; ++i
)
596 PyObject
*item
= PySequence_GetItem (enum_values
, i
);
600 do_cleanups (back_to
);
603 if (! gdbpy_is_string (item
))
606 do_cleanups (back_to
);
607 PyErr_SetString (PyExc_RuntimeError
,
608 _("The enumeration item not a string."));
611 self
->enumeration
[i
] = python_string_to_host_string (item
).release ();
613 if (self
->enumeration
[i
] == NULL
)
615 do_cleanups (back_to
);
618 make_cleanup (xfree
, (char *) self
->enumeration
[i
]);
621 discard_cleanups (back_to
);
625 /* Object initializer; sets up gdb-side structures for command.
627 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
629 NAME is the name of the parameter. It may consist of multiple
630 words, in which case the final word is the name of the new command,
631 and earlier words must be prefix commands.
633 CMDCLASS is the kind of command. It should be one of the COMMAND_*
634 constants defined in the gdb module.
636 PARMCLASS is the type of the parameter. It should be one of the
637 PARAM_* constants defined in the gdb module.
639 If PARMCLASS is PARAM_ENUM, then the final argument should be a
640 collection of strings. These strings are the valid values for this
643 The documentation for the parameter is taken from the doc string
644 for the python class.
646 Returns -1 on error, with a python exception set. */
649 parmpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kwds
)
651 parmpy_object
*obj
= (parmpy_object
*) self
;
653 char *set_doc
, *show_doc
, *doc
;
655 int parmclass
, cmdtype
;
656 PyObject
*enum_values
= NULL
;
657 struct cmd_list_element
**set_list
, **show_list
;
659 if (! PyArg_ParseTuple (args
, "sii|O", &name
, &cmdtype
, &parmclass
,
663 if (cmdtype
!= no_class
&& cmdtype
!= class_run
664 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
665 && cmdtype
!= class_files
&& cmdtype
!= class_support
666 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
667 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
668 && cmdtype
!= class_maintenance
)
670 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
674 if (parmclass
!= var_boolean
/* ARI: var_boolean */
675 && parmclass
!= var_auto_boolean
676 && parmclass
!= var_uinteger
&& parmclass
!= var_integer
677 && parmclass
!= var_string
&& parmclass
!= var_string_noescape
678 && parmclass
!= var_optional_filename
&& parmclass
!= var_filename
679 && parmclass
!= var_zinteger
&& parmclass
!= var_enum
)
681 PyErr_SetString (PyExc_RuntimeError
,
682 _("Invalid parameter class argument."));
686 if (enum_values
&& parmclass
!= var_enum
)
688 PyErr_SetString (PyExc_RuntimeError
,
689 _("Only PARAM_ENUM accepts a fourth argument."));
692 if (parmclass
== var_enum
)
694 if (! compute_enum_values (obj
, enum_values
))
698 obj
->enumeration
= NULL
;
699 obj
->type
= (enum var_types
) parmclass
;
700 memset (&obj
->value
, 0, sizeof (obj
->value
));
702 cmd_name
= gdbpy_parse_command_name (name
, &set_list
,
708 cmd_name
= gdbpy_parse_command_name (name
, &show_list
,
713 set_doc
= get_doc_string (self
, set_doc_cst
).release ();
714 show_doc
= get_doc_string (self
, show_doc_cst
).release ();
715 doc
= get_doc_string (self
, gdbpy_doc_cst
).release ();
721 add_setshow_generic (parmclass
, (enum command_class
) cmdtype
,
724 doc
, set_list
, show_list
);
726 CATCH (except
, RETURN_MASK_ALL
)
733 PyErr_Format (except
.reason
== RETURN_QUIT
734 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
735 "%s", except
.message
);
745 /* Initialize the 'parameters' module. */
747 gdbpy_initialize_parameters (void)
751 parmpy_object_type
.tp_new
= PyType_GenericNew
;
752 if (PyType_Ready (&parmpy_object_type
) < 0)
755 set_doc_cst
= PyString_FromString ("set_doc");
758 show_doc_cst
= PyString_FromString ("show_doc");
762 for (i
= 0; parm_constants
[i
].name
; ++i
)
764 if (PyModule_AddIntConstant (gdb_module
,
765 parm_constants
[i
].name
,
766 parm_constants
[i
].value
) < 0)
770 return gdb_pymodule_addobject (gdb_module
, "Parameter",
771 (PyObject
*) &parmpy_object_type
);
776 PyTypeObject parmpy_object_type
=
778 PyVarObject_HEAD_INIT (NULL
, 0)
779 "gdb.Parameter", /*tp_name*/
780 sizeof (parmpy_object
), /*tp_basicsize*/
789 0, /*tp_as_sequence*/
794 get_attr
, /*tp_getattro*/
795 set_attr
, /*tp_setattro*/
797 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
798 "GDB parameter object", /* tp_doc */
801 0, /* tp_richcompare */
802 0, /* tp_weaklistoffset */
810 0, /* tp_descr_get */
811 0, /* tp_descr_set */
812 0, /* tp_dictoffset */
813 parmpy_init
, /* tp_init */