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 PyObject
*ds_obj
= PyObject_GetAttr (object
, attr
);
312 if (ds_obj
&& gdbpy_is_string (ds_obj
))
314 result
= python_string_to_host_string (ds_obj
);
316 gdbpy_print_stack ();
321 result
.reset (xstrdup (_("This command is not documented.")));
325 /* Helper function which will execute a METHOD in OBJ passing the
326 argument ARG. ARG can be NULL. METHOD should return a Python
327 string. If this function returns NULL, there has been an error and
328 the appropriate exception set. */
329 static gdb::unique_xmalloc_ptr
<char>
330 call_doc_function (PyObject
*obj
, PyObject
*method
, PyObject
*arg
)
332 gdb::unique_xmalloc_ptr
<char> data
;
333 gdbpy_ref
result (PyObject_CallMethodObjArgs (obj
, method
, arg
, NULL
));
338 if (gdbpy_is_string (result
.get ()))
340 data
= python_string_to_host_string (result
.get ());
346 PyErr_SetString (PyExc_RuntimeError
,
347 _("Parameter must return a string value."));
354 /* A callback function that is registered against the respective
355 add_setshow_* set_doc prototype. This function will either call
356 the Python function "get_set_string" or extract the Python
357 attribute "set_doc" and return the contents as a string. If
358 neither exist, insert a string indicating the Parameter is not
361 get_set_value (char *args
, int from_tty
,
362 struct cmd_list_element
*c
)
364 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
365 gdb::unique_xmalloc_ptr
<char> set_doc_string
;
366 struct cleanup
*cleanup
= ensure_python_env (get_current_arch (),
368 PyObject
*set_doc_func
= PyString_FromString ("get_set_string");
373 if (PyObject_HasAttr (obj
, set_doc_func
))
375 set_doc_string
= call_doc_function (obj
, set_doc_func
, NULL
);
376 if (! set_doc_string
)
381 /* We have to preserve the existing < GDB 7.3 API. If a
382 callback function does not exist, then attempt to read the
383 set_doc attribute. */
384 set_doc_string
= get_doc_string (obj
, set_doc_cst
);
387 fprintf_filtered (gdb_stdout
, "%s\n", set_doc_string
.get ());
389 Py_XDECREF (set_doc_func
);
390 do_cleanups (cleanup
);
394 Py_XDECREF (set_doc_func
);
395 gdbpy_print_stack ();
396 do_cleanups (cleanup
);
400 /* A callback function that is registered against the respective
401 add_setshow_* show_doc prototype. This function will either call
402 the Python function "get_show_string" or extract the Python
403 attribute "show_doc" and return the contents as a string. If
404 neither exist, insert a string indicating the Parameter is not
407 get_show_value (struct ui_file
*file
, int from_tty
,
408 struct cmd_list_element
*c
,
411 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
412 gdb::unique_xmalloc_ptr
<char> show_doc_string
;
413 struct cleanup
*cleanup
= ensure_python_env (get_current_arch (),
415 PyObject
*show_doc_func
= PyString_FromString ("get_show_string");
420 if (PyObject_HasAttr (obj
, show_doc_func
))
422 PyObject
*val_obj
= PyString_FromString (value
);
427 show_doc_string
= call_doc_function (obj
, show_doc_func
, val_obj
);
429 if (! show_doc_string
)
432 fprintf_filtered (file
, "%s\n", show_doc_string
.get ());
436 /* We have to preserve the existing < GDB 7.3 API. If a
437 callback function does not exist, then attempt to read the
438 show_doc attribute. */
439 show_doc_string
= get_doc_string (obj
, show_doc_cst
);
440 fprintf_filtered (file
, "%s %s\n", show_doc_string
.get (), value
);
443 Py_XDECREF (show_doc_func
);
444 do_cleanups (cleanup
);
448 Py_XDECREF (show_doc_func
);
449 gdbpy_print_stack ();
450 do_cleanups (cleanup
);
455 /* A helper function that dispatches to the appropriate add_setshow
458 add_setshow_generic (int parmclass
, enum command_class cmdclass
,
459 char *cmd_name
, parmpy_object
*self
,
460 char *set_doc
, char *show_doc
, char *help_doc
,
461 struct cmd_list_element
**set_list
,
462 struct cmd_list_element
**show_list
)
464 struct cmd_list_element
*param
= NULL
;
465 const char *tmp_name
= NULL
;
471 add_setshow_boolean_cmd (cmd_name
, cmdclass
,
472 &self
->value
.intval
, set_doc
, show_doc
,
473 help_doc
, get_set_value
, get_show_value
,
474 set_list
, show_list
);
478 case var_auto_boolean
:
479 add_setshow_auto_boolean_cmd (cmd_name
, cmdclass
,
480 &self
->value
.autoboolval
,
481 set_doc
, show_doc
, help_doc
,
482 get_set_value
, get_show_value
,
483 set_list
, show_list
);
487 add_setshow_uinteger_cmd (cmd_name
, cmdclass
,
488 &self
->value
.uintval
, set_doc
, show_doc
,
489 help_doc
, get_set_value
, get_show_value
,
490 set_list
, show_list
);
494 add_setshow_integer_cmd (cmd_name
, cmdclass
,
495 &self
->value
.intval
, set_doc
, show_doc
,
496 help_doc
, get_set_value
, get_show_value
,
497 set_list
, show_list
); break;
500 add_setshow_string_cmd (cmd_name
, cmdclass
,
501 &self
->value
.stringval
, set_doc
, show_doc
,
502 help_doc
, get_set_value
, get_show_value
,
503 set_list
, show_list
); break;
505 case var_string_noescape
:
506 add_setshow_string_noescape_cmd (cmd_name
, cmdclass
,
507 &self
->value
.stringval
,
508 set_doc
, show_doc
, help_doc
,
509 get_set_value
, get_show_value
,
510 set_list
, show_list
);
514 case var_optional_filename
:
515 add_setshow_optional_filename_cmd (cmd_name
, cmdclass
,
516 &self
->value
.stringval
, set_doc
,
517 show_doc
, help_doc
, get_set_value
,
518 get_show_value
, set_list
,
523 add_setshow_filename_cmd (cmd_name
, cmdclass
,
524 &self
->value
.stringval
, set_doc
, show_doc
,
525 help_doc
, get_set_value
, get_show_value
,
526 set_list
, show_list
); break;
529 add_setshow_zinteger_cmd (cmd_name
, cmdclass
,
530 &self
->value
.intval
, set_doc
, show_doc
,
531 help_doc
, get_set_value
, get_show_value
,
532 set_list
, show_list
);
536 add_setshow_enum_cmd (cmd_name
, cmdclass
, self
->enumeration
,
537 &self
->value
.cstringval
, set_doc
, show_doc
,
538 help_doc
, get_set_value
, get_show_value
,
539 set_list
, show_list
);
540 /* Initialize the value, just in case. */
541 self
->value
.cstringval
= self
->enumeration
[0];
545 /* Lookup created parameter, and register Python object against the
546 parameter context. Perform this task against both lists. */
548 param
= lookup_cmd (&tmp_name
, *show_list
, "", 0, 1);
550 set_cmd_context (param
, self
);
553 param
= lookup_cmd (&tmp_name
, *set_list
, "", 0, 1);
555 set_cmd_context (param
, self
);
558 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
559 error, with a python exception set. */
561 compute_enum_values (parmpy_object
*self
, PyObject
*enum_values
)
564 struct cleanup
*back_to
;
568 PyErr_SetString (PyExc_RuntimeError
,
569 _("An enumeration is required for PARAM_ENUM."));
573 if (! PySequence_Check (enum_values
))
575 PyErr_SetString (PyExc_RuntimeError
,
576 _("The enumeration is not a sequence."));
580 size
= PySequence_Size (enum_values
);
585 PyErr_SetString (PyExc_RuntimeError
,
586 _("The enumeration is empty."));
590 self
->enumeration
= XCNEWVEC (const char *, size
+ 1);
591 back_to
= make_cleanup (free_current_contents
, &self
->enumeration
);
593 for (i
= 0; i
< size
; ++i
)
595 PyObject
*item
= PySequence_GetItem (enum_values
, i
);
599 do_cleanups (back_to
);
602 if (! gdbpy_is_string (item
))
605 do_cleanups (back_to
);
606 PyErr_SetString (PyExc_RuntimeError
,
607 _("The enumeration item not a string."));
610 self
->enumeration
[i
] = python_string_to_host_string (item
).release ();
612 if (self
->enumeration
[i
] == NULL
)
614 do_cleanups (back_to
);
617 make_cleanup (xfree
, (char *) self
->enumeration
[i
]);
620 discard_cleanups (back_to
);
624 /* Object initializer; sets up gdb-side structures for command.
626 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
628 NAME is the name of the parameter. It may consist of multiple
629 words, in which case the final word is the name of the new command,
630 and earlier words must be prefix commands.
632 CMDCLASS is the kind of command. It should be one of the COMMAND_*
633 constants defined in the gdb module.
635 PARMCLASS is the type of the parameter. It should be one of the
636 PARAM_* constants defined in the gdb module.
638 If PARMCLASS is PARAM_ENUM, then the final argument should be a
639 collection of strings. These strings are the valid values for this
642 The documentation for the parameter is taken from the doc string
643 for the python class.
645 Returns -1 on error, with a python exception set. */
648 parmpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kwds
)
650 parmpy_object
*obj
= (parmpy_object
*) self
;
652 char *set_doc
, *show_doc
, *doc
;
654 int parmclass
, cmdtype
;
655 PyObject
*enum_values
= NULL
;
656 struct cmd_list_element
**set_list
, **show_list
;
658 if (! PyArg_ParseTuple (args
, "sii|O", &name
, &cmdtype
, &parmclass
,
662 if (cmdtype
!= no_class
&& cmdtype
!= class_run
663 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
664 && cmdtype
!= class_files
&& cmdtype
!= class_support
665 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
666 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
667 && cmdtype
!= class_maintenance
)
669 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
673 if (parmclass
!= var_boolean
/* ARI: var_boolean */
674 && parmclass
!= var_auto_boolean
675 && parmclass
!= var_uinteger
&& parmclass
!= var_integer
676 && parmclass
!= var_string
&& parmclass
!= var_string_noescape
677 && parmclass
!= var_optional_filename
&& parmclass
!= var_filename
678 && parmclass
!= var_zinteger
&& parmclass
!= var_enum
)
680 PyErr_SetString (PyExc_RuntimeError
,
681 _("Invalid parameter class argument."));
685 if (enum_values
&& parmclass
!= var_enum
)
687 PyErr_SetString (PyExc_RuntimeError
,
688 _("Only PARAM_ENUM accepts a fourth argument."));
691 if (parmclass
== var_enum
)
693 if (! compute_enum_values (obj
, enum_values
))
697 obj
->enumeration
= NULL
;
698 obj
->type
= (enum var_types
) parmclass
;
699 memset (&obj
->value
, 0, sizeof (obj
->value
));
701 cmd_name
= gdbpy_parse_command_name (name
, &set_list
,
707 cmd_name
= gdbpy_parse_command_name (name
, &show_list
,
712 set_doc
= get_doc_string (self
, set_doc_cst
).release ();
713 show_doc
= get_doc_string (self
, show_doc_cst
).release ();
714 doc
= get_doc_string (self
, gdbpy_doc_cst
).release ();
720 add_setshow_generic (parmclass
, (enum command_class
) cmdtype
,
723 doc
, set_list
, show_list
);
725 CATCH (except
, RETURN_MASK_ALL
)
732 PyErr_Format (except
.reason
== RETURN_QUIT
733 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
734 "%s", except
.message
);
744 /* Initialize the 'parameters' module. */
746 gdbpy_initialize_parameters (void)
750 parmpy_object_type
.tp_new
= PyType_GenericNew
;
751 if (PyType_Ready (&parmpy_object_type
) < 0)
754 set_doc_cst
= PyString_FromString ("set_doc");
757 show_doc_cst
= PyString_FromString ("show_doc");
761 for (i
= 0; parm_constants
[i
].name
; ++i
)
763 if (PyModule_AddIntConstant (gdb_module
,
764 parm_constants
[i
].name
,
765 parm_constants
[i
].value
) < 0)
769 return gdb_pymodule_addobject (gdb_module
, "Parameter",
770 (PyObject
*) &parmpy_object_type
);
775 PyTypeObject parmpy_object_type
=
777 PyVarObject_HEAD_INIT (NULL
, 0)
778 "gdb.Parameter", /*tp_name*/
779 sizeof (parmpy_object
), /*tp_basicsize*/
788 0, /*tp_as_sequence*/
793 get_attr
, /*tp_getattro*/
794 set_attr
, /*tp_setattro*/
796 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
797 "GDB parameter object", /* tp_doc */
800 0, /* tp_richcompare */
801 0, /* tp_weaklistoffset */
809 0, /* tp_descr_get */
810 0, /* tp_descr_set */
811 0, /* tp_dictoffset */
812 parmpy_init
, /* tp_init */