1 /* GDB parameters implemented in Python
3 Copyright (C) 2008-2017 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"
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 extern 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
;
152 gdb::unique_xmalloc_ptr
<char>
153 string (python_string_to_host_string (value
));
157 xfree (self
->value
.stringval
);
158 self
->value
.stringval
= string
.release ();
166 if (! gdbpy_is_string (value
))
168 PyErr_SetString (PyExc_RuntimeError
,
169 _("ENUM arguments must be a string."));
173 gdb::unique_xmalloc_ptr
<char>
174 str (python_string_to_host_string (value
));
177 for (i
= 0; self
->enumeration
[i
]; ++i
)
178 if (! strcmp (self
->enumeration
[i
], str
.get ()))
180 if (! self
->enumeration
[i
])
182 PyErr_SetString (PyExc_RuntimeError
,
183 _("The value must be member of an enumeration."));
186 self
->value
.cstringval
= self
->enumeration
[i
];
191 if (! PyBool_Check (value
))
193 PyErr_SetString (PyExc_RuntimeError
,
194 _("A boolean argument is required."));
197 cmp
= PyObject_IsTrue (value
);
200 self
->value
.intval
= cmp
;
203 case var_auto_boolean
:
204 if (! PyBool_Check (value
) && value
!= Py_None
)
206 PyErr_SetString (PyExc_RuntimeError
,
207 _("A boolean or None is required"));
211 if (value
== Py_None
)
212 self
->value
.autoboolval
= AUTO_BOOLEAN_AUTO
;
215 cmp
= PyObject_IsTrue (value
);
219 self
->value
.autoboolval
= AUTO_BOOLEAN_TRUE
;
221 self
->value
.autoboolval
= AUTO_BOOLEAN_FALSE
;
232 if (! PyInt_Check (value
))
234 PyErr_SetString (PyExc_RuntimeError
,
235 _("The value must be integer."));
239 if (! gdb_py_int_as_long (value
, &l
))
242 if (self
->type
== var_uinteger
)
244 ok
= (l
>= 0 && l
<= UINT_MAX
);
248 else if (self
->type
== var_integer
)
250 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
255 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
259 PyErr_SetString (PyExc_RuntimeError
,
260 _("Range exceeded."));
264 self
->value
.intval
= (int) l
;
269 PyErr_SetString (PyExc_RuntimeError
,
270 _("Unhandled type in parameter value."));
277 /* Set an attribute. Returns -1 on error, with a python exception set. */
279 set_attr (PyObject
*obj
, PyObject
*attr_name
, PyObject
*val
)
281 if (PyString_Check (attr_name
)
283 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
285 && ! strcmp (PyString_AsString (attr_name
), "value"))
290 PyErr_SetString (PyExc_RuntimeError
,
291 _("Cannot delete a parameter's value."));
294 return set_parameter_value ((parmpy_object
*) obj
, val
);
297 return PyObject_GenericSetAttr (obj
, attr_name
, val
);
300 /* A helper function which returns a documentation string for an
303 static gdb::unique_xmalloc_ptr
<char>
304 get_doc_string (PyObject
*object
, PyObject
*attr
)
306 gdb::unique_xmalloc_ptr
<char> result
;
308 if (PyObject_HasAttr (object
, attr
))
310 gdbpy_ref
<> ds_obj (PyObject_GetAttr (object
, attr
));
312 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
314 result
= python_string_to_host_string (ds_obj
.get ());
316 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 gdbpy_ref
<> result (PyObject_CallMethodObjArgs (obj
, method
, arg
, NULL
));
337 if (gdbpy_is_string (result
.get ()))
339 data
= python_string_to_host_string (result
.get ());
345 PyErr_SetString (PyExc_RuntimeError
,
346 _("Parameter must return a string value."));
353 /* A callback function that is registered against the respective
354 add_setshow_* set_doc prototype. This function will either call
355 the Python function "get_set_string" or extract the Python
356 attribute "set_doc" and return the contents as a string. If
357 neither exist, insert a string indicating the Parameter is not
360 get_set_value (char *args
, int from_tty
,
361 struct cmd_list_element
*c
)
363 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
364 gdb::unique_xmalloc_ptr
<char> set_doc_string
;
366 gdbpy_enter
enter_py (get_current_arch (), current_language
);
367 gdbpy_ref
<> set_doc_func (PyString_FromString ("get_set_string"));
369 if (set_doc_func
== NULL
)
371 gdbpy_print_stack ();
375 if (PyObject_HasAttr (obj
, set_doc_func
.get ()))
377 set_doc_string
= call_doc_function (obj
, set_doc_func
.get (), NULL
);
378 if (! set_doc_string
)
380 gdbpy_print_stack ();
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 fprintf_filtered (gdb_stdout
, "%s\n", set_doc_string
.get ());
395 /* A callback function that is registered against the respective
396 add_setshow_* show_doc prototype. This function will either call
397 the Python function "get_show_string" or extract the Python
398 attribute "show_doc" and return the contents as a string. If
399 neither exist, insert a string indicating the Parameter is not
402 get_show_value (struct ui_file
*file
, int from_tty
,
403 struct cmd_list_element
*c
,
406 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
407 gdb::unique_xmalloc_ptr
<char> show_doc_string
;
409 gdbpy_enter
enter_py (get_current_arch (), current_language
);
410 gdbpy_ref
<> show_doc_func (PyString_FromString ("get_show_string"));
412 if (show_doc_func
== NULL
)
414 gdbpy_print_stack ();
418 if (PyObject_HasAttr (obj
, show_doc_func
.get ()))
420 gdbpy_ref
<> val_obj (PyString_FromString (value
));
424 gdbpy_print_stack ();
428 show_doc_string
= call_doc_function (obj
, show_doc_func
.get (),
430 if (! show_doc_string
)
432 gdbpy_print_stack ();
436 fprintf_filtered (file
, "%s\n", show_doc_string
.get ());
440 /* We have to preserve the existing < GDB 7.3 API. If a
441 callback function does not exist, then attempt to read the
442 show_doc attribute. */
443 show_doc_string
= get_doc_string (obj
, show_doc_cst
);
444 fprintf_filtered (file
, "%s %s\n", show_doc_string
.get (), value
);
449 /* A helper function that dispatches to the appropriate add_setshow
452 add_setshow_generic (int parmclass
, enum command_class cmdclass
,
453 char *cmd_name
, parmpy_object
*self
,
454 char *set_doc
, char *show_doc
, char *help_doc
,
455 struct cmd_list_element
**set_list
,
456 struct cmd_list_element
**show_list
)
458 struct cmd_list_element
*param
= NULL
;
459 const char *tmp_name
= NULL
;
465 add_setshow_boolean_cmd (cmd_name
, cmdclass
,
466 &self
->value
.intval
, set_doc
, show_doc
,
467 help_doc
, get_set_value
, get_show_value
,
468 set_list
, show_list
);
472 case var_auto_boolean
:
473 add_setshow_auto_boolean_cmd (cmd_name
, cmdclass
,
474 &self
->value
.autoboolval
,
475 set_doc
, show_doc
, help_doc
,
476 get_set_value
, get_show_value
,
477 set_list
, show_list
);
481 add_setshow_uinteger_cmd (cmd_name
, cmdclass
,
482 &self
->value
.uintval
, set_doc
, show_doc
,
483 help_doc
, get_set_value
, get_show_value
,
484 set_list
, show_list
);
488 add_setshow_integer_cmd (cmd_name
, cmdclass
,
489 &self
->value
.intval
, set_doc
, show_doc
,
490 help_doc
, get_set_value
, get_show_value
,
491 set_list
, show_list
); break;
494 add_setshow_string_cmd (cmd_name
, cmdclass
,
495 &self
->value
.stringval
, set_doc
, show_doc
,
496 help_doc
, get_set_value
, get_show_value
,
497 set_list
, show_list
); break;
499 case var_string_noescape
:
500 add_setshow_string_noescape_cmd (cmd_name
, cmdclass
,
501 &self
->value
.stringval
,
502 set_doc
, show_doc
, help_doc
,
503 get_set_value
, get_show_value
,
504 set_list
, show_list
);
508 case var_optional_filename
:
509 add_setshow_optional_filename_cmd (cmd_name
, cmdclass
,
510 &self
->value
.stringval
, set_doc
,
511 show_doc
, help_doc
, get_set_value
,
512 get_show_value
, set_list
,
517 add_setshow_filename_cmd (cmd_name
, cmdclass
,
518 &self
->value
.stringval
, set_doc
, show_doc
,
519 help_doc
, get_set_value
, get_show_value
,
520 set_list
, show_list
); break;
523 add_setshow_zinteger_cmd (cmd_name
, cmdclass
,
524 &self
->value
.intval
, set_doc
, show_doc
,
525 help_doc
, get_set_value
, get_show_value
,
526 set_list
, show_list
);
530 add_setshow_enum_cmd (cmd_name
, cmdclass
, self
->enumeration
,
531 &self
->value
.cstringval
, set_doc
, show_doc
,
532 help_doc
, get_set_value
, get_show_value
,
533 set_list
, show_list
);
534 /* Initialize the value, just in case. */
535 self
->value
.cstringval
= self
->enumeration
[0];
539 /* Lookup created parameter, and register Python object against the
540 parameter context. Perform this task against both lists. */
542 param
= lookup_cmd (&tmp_name
, *show_list
, "", 0, 1);
544 set_cmd_context (param
, self
);
547 param
= lookup_cmd (&tmp_name
, *set_list
, "", 0, 1);
549 set_cmd_context (param
, self
);
552 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
553 error, with a python exception set. */
555 compute_enum_values (parmpy_object
*self
, PyObject
*enum_values
)
558 struct cleanup
*back_to
;
562 PyErr_SetString (PyExc_RuntimeError
,
563 _("An enumeration is required for PARAM_ENUM."));
567 if (! PySequence_Check (enum_values
))
569 PyErr_SetString (PyExc_RuntimeError
,
570 _("The enumeration is not a sequence."));
574 size
= PySequence_Size (enum_values
);
579 PyErr_SetString (PyExc_RuntimeError
,
580 _("The enumeration is empty."));
584 self
->enumeration
= XCNEWVEC (const char *, size
+ 1);
585 back_to
= make_cleanup (free_current_contents
, &self
->enumeration
);
587 for (i
= 0; i
< size
; ++i
)
589 gdbpy_ref
<> item (PySequence_GetItem (enum_values
, i
));
593 do_cleanups (back_to
);
596 if (! gdbpy_is_string (item
.get ()))
598 do_cleanups (back_to
);
599 PyErr_SetString (PyExc_RuntimeError
,
600 _("The enumeration item not a string."));
604 = python_string_to_host_string (item
.get ()).release ();
605 if (self
->enumeration
[i
] == NULL
)
607 do_cleanups (back_to
);
610 make_cleanup (xfree
, (char *) self
->enumeration
[i
]);
613 discard_cleanups (back_to
);
617 /* Object initializer; sets up gdb-side structures for command.
619 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
621 NAME is the name of the parameter. It may consist of multiple
622 words, in which case the final word is the name of the new command,
623 and earlier words must be prefix commands.
625 CMDCLASS is the kind of command. It should be one of the COMMAND_*
626 constants defined in the gdb module.
628 PARMCLASS is the type of the parameter. It should be one of the
629 PARAM_* constants defined in the gdb module.
631 If PARMCLASS is PARAM_ENUM, then the final argument should be a
632 collection of strings. These strings are the valid values for this
635 The documentation for the parameter is taken from the doc string
636 for the python class.
638 Returns -1 on error, with a python exception set. */
641 parmpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kwds
)
643 parmpy_object
*obj
= (parmpy_object
*) self
;
645 char *set_doc
, *show_doc
, *doc
;
647 int parmclass
, cmdtype
;
648 PyObject
*enum_values
= NULL
;
649 struct cmd_list_element
**set_list
, **show_list
;
651 if (! PyArg_ParseTuple (args
, "sii|O", &name
, &cmdtype
, &parmclass
,
655 if (cmdtype
!= no_class
&& cmdtype
!= class_run
656 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
657 && cmdtype
!= class_files
&& cmdtype
!= class_support
658 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
659 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
660 && cmdtype
!= class_maintenance
)
662 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
666 if (parmclass
!= var_boolean
/* ARI: var_boolean */
667 && parmclass
!= var_auto_boolean
668 && parmclass
!= var_uinteger
&& parmclass
!= var_integer
669 && parmclass
!= var_string
&& parmclass
!= var_string_noescape
670 && parmclass
!= var_optional_filename
&& parmclass
!= var_filename
671 && parmclass
!= var_zinteger
&& parmclass
!= var_enum
)
673 PyErr_SetString (PyExc_RuntimeError
,
674 _("Invalid parameter class argument."));
678 if (enum_values
&& parmclass
!= var_enum
)
680 PyErr_SetString (PyExc_RuntimeError
,
681 _("Only PARAM_ENUM accepts a fourth argument."));
684 if (parmclass
== var_enum
)
686 if (! compute_enum_values (obj
, enum_values
))
690 obj
->enumeration
= NULL
;
691 obj
->type
= (enum var_types
) parmclass
;
692 memset (&obj
->value
, 0, sizeof (obj
->value
));
694 cmd_name
= gdbpy_parse_command_name (name
, &set_list
,
700 cmd_name
= gdbpy_parse_command_name (name
, &show_list
,
705 set_doc
= get_doc_string (self
, set_doc_cst
).release ();
706 show_doc
= get_doc_string (self
, show_doc_cst
).release ();
707 doc
= get_doc_string (self
, gdbpy_doc_cst
).release ();
713 add_setshow_generic (parmclass
, (enum command_class
) cmdtype
,
716 doc
, set_list
, show_list
);
718 CATCH (except
, RETURN_MASK_ALL
)
725 PyErr_Format (except
.reason
== RETURN_QUIT
726 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
727 "%s", except
.message
);
737 /* Initialize the 'parameters' module. */
739 gdbpy_initialize_parameters (void)
743 parmpy_object_type
.tp_new
= PyType_GenericNew
;
744 if (PyType_Ready (&parmpy_object_type
) < 0)
747 set_doc_cst
= PyString_FromString ("set_doc");
750 show_doc_cst
= PyString_FromString ("show_doc");
754 for (i
= 0; parm_constants
[i
].name
; ++i
)
756 if (PyModule_AddIntConstant (gdb_module
,
757 parm_constants
[i
].name
,
758 parm_constants
[i
].value
) < 0)
762 return gdb_pymodule_addobject (gdb_module
, "Parameter",
763 (PyObject
*) &parmpy_object_type
);
768 PyTypeObject parmpy_object_type
=
770 PyVarObject_HEAD_INIT (NULL
, 0)
771 "gdb.Parameter", /*tp_name*/
772 sizeof (parmpy_object
), /*tp_basicsize*/
781 0, /*tp_as_sequence*/
786 get_attr
, /*tp_getattro*/
787 set_attr
, /*tp_setattro*/
789 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
790 "GDB parameter object", /* tp_doc */
793 0, /* tp_richcompare */
794 0, /* tp_weaklistoffset */
802 0, /* tp_descr_get */
803 0, /* tp_descr_set */
804 0, /* tp_dictoffset */
805 parmpy_init
, /* tp_init */