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
)
561 PyErr_SetString (PyExc_RuntimeError
,
562 _("An enumeration is required for PARAM_ENUM."));
566 if (! PySequence_Check (enum_values
))
568 PyErr_SetString (PyExc_RuntimeError
,
569 _("The enumeration is not a sequence."));
573 size
= PySequence_Size (enum_values
);
578 PyErr_SetString (PyExc_RuntimeError
,
579 _("The enumeration is empty."));
583 gdb_argv
holder (XCNEWVEC (char *, size
+ 1));
584 char **enumeration
= holder
.get ();
586 for (i
= 0; i
< size
; ++i
)
588 gdbpy_ref
<> item (PySequence_GetItem (enum_values
, i
));
592 if (! gdbpy_is_string (item
.get ()))
594 PyErr_SetString (PyExc_RuntimeError
,
595 _("The enumeration item not a string."));
598 enumeration
[i
] = python_string_to_host_string (item
.get ()).release ();
599 if (enumeration
[i
] == NULL
)
603 self
->enumeration
= const_cast<const char**> (holder
.release ());
607 /* Object initializer; sets up gdb-side structures for command.
609 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
611 NAME is the name of the parameter. It may consist of multiple
612 words, in which case the final word is the name of the new command,
613 and earlier words must be prefix commands.
615 CMDCLASS is the kind of command. It should be one of the COMMAND_*
616 constants defined in the gdb module.
618 PARMCLASS is the type of the parameter. It should be one of the
619 PARAM_* constants defined in the gdb module.
621 If PARMCLASS is PARAM_ENUM, then the final argument should be a
622 collection of strings. These strings are the valid values for this
625 The documentation for the parameter is taken from the doc string
626 for the python class.
628 Returns -1 on error, with a python exception set. */
631 parmpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kwds
)
633 parmpy_object
*obj
= (parmpy_object
*) self
;
635 char *set_doc
, *show_doc
, *doc
;
637 int parmclass
, cmdtype
;
638 PyObject
*enum_values
= NULL
;
639 struct cmd_list_element
**set_list
, **show_list
;
641 if (! PyArg_ParseTuple (args
, "sii|O", &name
, &cmdtype
, &parmclass
,
645 if (cmdtype
!= no_class
&& cmdtype
!= class_run
646 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
647 && cmdtype
!= class_files
&& cmdtype
!= class_support
648 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
649 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
650 && cmdtype
!= class_maintenance
)
652 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
656 if (parmclass
!= var_boolean
/* ARI: var_boolean */
657 && parmclass
!= var_auto_boolean
658 && parmclass
!= var_uinteger
&& parmclass
!= var_integer
659 && parmclass
!= var_string
&& parmclass
!= var_string_noescape
660 && parmclass
!= var_optional_filename
&& parmclass
!= var_filename
661 && parmclass
!= var_zinteger
&& parmclass
!= var_enum
)
663 PyErr_SetString (PyExc_RuntimeError
,
664 _("Invalid parameter class argument."));
668 if (enum_values
&& parmclass
!= var_enum
)
670 PyErr_SetString (PyExc_RuntimeError
,
671 _("Only PARAM_ENUM accepts a fourth argument."));
674 if (parmclass
== var_enum
)
676 if (! compute_enum_values (obj
, enum_values
))
680 obj
->enumeration
= NULL
;
681 obj
->type
= (enum var_types
) parmclass
;
682 memset (&obj
->value
, 0, sizeof (obj
->value
));
684 cmd_name
= gdbpy_parse_command_name (name
, &set_list
,
690 cmd_name
= gdbpy_parse_command_name (name
, &show_list
,
695 set_doc
= get_doc_string (self
, set_doc_cst
).release ();
696 show_doc
= get_doc_string (self
, show_doc_cst
).release ();
697 doc
= get_doc_string (self
, gdbpy_doc_cst
).release ();
703 add_setshow_generic (parmclass
, (enum command_class
) cmdtype
,
706 doc
, set_list
, show_list
);
708 CATCH (except
, RETURN_MASK_ALL
)
715 PyErr_Format (except
.reason
== RETURN_QUIT
716 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
717 "%s", except
.message
);
727 /* Initialize the 'parameters' module. */
729 gdbpy_initialize_parameters (void)
733 parmpy_object_type
.tp_new
= PyType_GenericNew
;
734 if (PyType_Ready (&parmpy_object_type
) < 0)
737 set_doc_cst
= PyString_FromString ("set_doc");
740 show_doc_cst
= PyString_FromString ("show_doc");
744 for (i
= 0; parm_constants
[i
].name
; ++i
)
746 if (PyModule_AddIntConstant (gdb_module
,
747 parm_constants
[i
].name
,
748 parm_constants
[i
].value
) < 0)
752 return gdb_pymodule_addobject (gdb_module
, "Parameter",
753 (PyObject
*) &parmpy_object_type
);
758 PyTypeObject parmpy_object_type
=
760 PyVarObject_HEAD_INIT (NULL
, 0)
761 "gdb.Parameter", /*tp_name*/
762 sizeof (parmpy_object
), /*tp_basicsize*/
771 0, /*tp_as_sequence*/
776 get_attr
, /*tp_getattro*/
777 set_attr
, /*tp_setattro*/
779 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
780 "GDB parameter object", /* tp_doc */
783 0, /* tp_richcompare */
784 0, /* tp_weaklistoffset */
792 0, /* tp_descr_get */
793 0, /* tp_descr_set */
794 0, /* tp_dictoffset */
795 parmpy_init
, /* tp_init */