1 /* GDB parameters implemented in Python
3 Copyright (C) 2008-2014 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 static 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
;
153 string
= python_string_to_host_string (value
);
157 xfree (self
->value
.stringval
);
158 self
->value
.stringval
= string
;
167 if (! gdbpy_is_string (value
))
169 PyErr_SetString (PyExc_RuntimeError
,
170 _("ENUM arguments must be a string."));
174 str
= python_string_to_host_string (value
);
177 for (i
= 0; self
->enumeration
[i
]; ++i
)
178 if (! strcmp (self
->enumeration
[i
], str
))
181 if (! self
->enumeration
[i
])
183 PyErr_SetString (PyExc_RuntimeError
,
184 _("The value must be member of an enumeration."));
187 self
->value
.cstringval
= self
->enumeration
[i
];
192 if (! PyBool_Check (value
))
194 PyErr_SetString (PyExc_RuntimeError
,
195 _("A boolean argument is required."));
198 cmp
= PyObject_IsTrue (value
);
201 self
->value
.intval
= cmp
;
204 case var_auto_boolean
:
205 if (! PyBool_Check (value
) && value
!= Py_None
)
207 PyErr_SetString (PyExc_RuntimeError
,
208 _("A boolean or None is required"));
212 if (value
== Py_None
)
213 self
->value
.autoboolval
= AUTO_BOOLEAN_AUTO
;
216 cmp
= PyObject_IsTrue (value
);
220 self
->value
.autoboolval
= AUTO_BOOLEAN_TRUE
;
222 self
->value
.autoboolval
= AUTO_BOOLEAN_FALSE
;
233 if (! PyInt_Check (value
))
235 PyErr_SetString (PyExc_RuntimeError
,
236 _("The value must be integer."));
240 if (! gdb_py_int_as_long (value
, &l
))
243 if (self
->type
== var_uinteger
)
245 ok
= (l
>= 0 && l
<= UINT_MAX
);
249 else if (self
->type
== var_integer
)
251 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
256 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
260 PyErr_SetString (PyExc_RuntimeError
,
261 _("Range exceeded."));
265 self
->value
.intval
= (int) l
;
270 PyErr_SetString (PyExc_RuntimeError
,
271 _("Unhandled type in parameter value."));
278 /* Set an attribute. Returns -1 on error, with a python exception set. */
280 set_attr (PyObject
*obj
, PyObject
*attr_name
, PyObject
*val
)
282 if (PyString_Check (attr_name
)
284 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
286 && ! strcmp (PyString_AsString (attr_name
), "value"))
291 PyErr_SetString (PyExc_RuntimeError
,
292 _("Cannot delete a parameter's value."));
295 return set_parameter_value ((parmpy_object
*) obj
, val
);
298 return PyObject_GenericSetAttr (obj
, attr_name
, val
);
301 /* A helper function which returns a documentation string for an
305 get_doc_string (PyObject
*object
, PyObject
*attr
)
309 if (PyObject_HasAttr (object
, attr
))
311 PyObject
*ds_obj
= PyObject_GetAttr (object
, attr
);
313 if (ds_obj
&& gdbpy_is_string (ds_obj
))
315 result
= python_string_to_host_string (ds_obj
);
317 gdbpy_print_stack ();
322 result
= xstrdup (_("This command is not documented."));
326 /* Helper function which will execute a METHOD in OBJ passing the
327 argument ARG. ARG can be NULL. METHOD should return a Python
328 string. If this function returns NULL, there has been an error and
329 the appropriate exception set. */
331 call_doc_function (PyObject
*obj
, PyObject
*method
, PyObject
*arg
)
334 PyObject
*result
= PyObject_CallMethodObjArgs (obj
, method
, arg
, NULL
);
339 if (gdbpy_is_string (result
))
341 data
= python_string_to_host_string (result
);
348 PyErr_SetString (PyExc_RuntimeError
,
349 _("Parameter must return a string value."));
357 /* A callback function that is registered against the respective
358 add_setshow_* set_doc prototype. This function will either call
359 the Python function "get_set_string" or extract the Python
360 attribute "set_doc" and return the contents as a string. If
361 neither exist, insert a string indicating the Parameter is not
364 get_set_value (char *args
, int from_tty
,
365 struct cmd_list_element
*c
)
367 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
368 char *set_doc_string
;
369 struct cleanup
*cleanup
= ensure_python_env (get_current_arch (),
371 PyObject
*set_doc_func
= PyString_FromString ("get_set_string");
376 if (PyObject_HasAttr (obj
, set_doc_func
))
378 set_doc_string
= call_doc_function (obj
, set_doc_func
, NULL
);
379 if (! set_doc_string
)
384 /* We have to preserve the existing < GDB 7.3 API. If a
385 callback function does not exist, then attempt to read the
386 set_doc attribute. */
387 set_doc_string
= get_doc_string (obj
, set_doc_cst
);
390 make_cleanup (xfree
, set_doc_string
);
391 fprintf_filtered (gdb_stdout
, "%s\n", set_doc_string
);
393 Py_XDECREF (set_doc_func
);
394 do_cleanups (cleanup
);
398 Py_XDECREF (set_doc_func
);
399 gdbpy_print_stack ();
400 do_cleanups (cleanup
);
404 /* A callback function that is registered against the respective
405 add_setshow_* show_doc prototype. This function will either call
406 the Python function "get_show_string" or extract the Python
407 attribute "show_doc" and return the contents as a string. If
408 neither exist, insert a string indicating the Parameter is not
411 get_show_value (struct ui_file
*file
, int from_tty
,
412 struct cmd_list_element
*c
,
415 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
416 char *show_doc_string
= NULL
;
417 struct cleanup
*cleanup
= ensure_python_env (get_current_arch (),
419 PyObject
*show_doc_func
= PyString_FromString ("get_show_string");
424 if (PyObject_HasAttr (obj
, show_doc_func
))
426 PyObject
*val_obj
= PyString_FromString (value
);
431 show_doc_string
= call_doc_function (obj
, show_doc_func
, val_obj
);
433 if (! show_doc_string
)
436 make_cleanup (xfree
, show_doc_string
);
438 fprintf_filtered (file
, "%s\n", show_doc_string
);
442 /* We have to preserve the existing < GDB 7.3 API. If a
443 callback function does not exist, then attempt to read the
444 show_doc attribute. */
445 show_doc_string
= get_doc_string (obj
, show_doc_cst
);
446 make_cleanup (xfree
, show_doc_string
);
447 fprintf_filtered (file
, "%s %s\n", show_doc_string
, value
);
450 Py_XDECREF (show_doc_func
);
451 do_cleanups (cleanup
);
455 Py_XDECREF (show_doc_func
);
456 gdbpy_print_stack ();
457 do_cleanups (cleanup
);
462 /* A helper function that dispatches to the appropriate add_setshow
465 add_setshow_generic (int parmclass
, enum command_class cmdclass
,
466 char *cmd_name
, parmpy_object
*self
,
467 char *set_doc
, char *show_doc
, char *help_doc
,
468 struct cmd_list_element
**set_list
,
469 struct cmd_list_element
**show_list
)
471 struct cmd_list_element
*param
= NULL
;
472 const char *tmp_name
= NULL
;
478 add_setshow_boolean_cmd (cmd_name
, cmdclass
,
479 &self
->value
.intval
, set_doc
, show_doc
,
480 help_doc
, get_set_value
, get_show_value
,
481 set_list
, show_list
);
485 case var_auto_boolean
:
486 add_setshow_auto_boolean_cmd (cmd_name
, cmdclass
,
487 &self
->value
.autoboolval
,
488 set_doc
, show_doc
, help_doc
,
489 get_set_value
, get_show_value
,
490 set_list
, show_list
);
494 add_setshow_uinteger_cmd (cmd_name
, cmdclass
,
495 &self
->value
.uintval
, set_doc
, show_doc
,
496 help_doc
, get_set_value
, get_show_value
,
497 set_list
, show_list
);
501 add_setshow_integer_cmd (cmd_name
, cmdclass
,
502 &self
->value
.intval
, set_doc
, show_doc
,
503 help_doc
, get_set_value
, get_show_value
,
504 set_list
, show_list
); break;
507 add_setshow_string_cmd (cmd_name
, cmdclass
,
508 &self
->value
.stringval
, set_doc
, show_doc
,
509 help_doc
, get_set_value
, get_show_value
,
510 set_list
, show_list
); break;
512 case var_string_noescape
:
513 add_setshow_string_noescape_cmd (cmd_name
, cmdclass
,
514 &self
->value
.stringval
,
515 set_doc
, show_doc
, help_doc
,
516 get_set_value
, get_show_value
,
517 set_list
, show_list
);
521 case var_optional_filename
:
522 add_setshow_optional_filename_cmd (cmd_name
, cmdclass
,
523 &self
->value
.stringval
, set_doc
,
524 show_doc
, help_doc
, get_set_value
,
525 get_show_value
, set_list
,
530 add_setshow_filename_cmd (cmd_name
, cmdclass
,
531 &self
->value
.stringval
, set_doc
, show_doc
,
532 help_doc
, get_set_value
, get_show_value
,
533 set_list
, show_list
); break;
536 add_setshow_zinteger_cmd (cmd_name
, cmdclass
,
537 &self
->value
.intval
, set_doc
, show_doc
,
538 help_doc
, get_set_value
, get_show_value
,
539 set_list
, show_list
);
543 add_setshow_enum_cmd (cmd_name
, cmdclass
, self
->enumeration
,
544 &self
->value
.cstringval
, set_doc
, show_doc
,
545 help_doc
, get_set_value
, get_show_value
,
546 set_list
, show_list
);
547 /* Initialize the value, just in case. */
548 self
->value
.cstringval
= self
->enumeration
[0];
552 /* Lookup created parameter, and register Python object against the
553 parameter context. Perform this task against both lists. */
555 param
= lookup_cmd (&tmp_name
, *show_list
, "", 0, 1);
557 set_cmd_context (param
, self
);
560 param
= lookup_cmd (&tmp_name
, *set_list
, "", 0, 1);
562 set_cmd_context (param
, self
);
565 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
566 error, with a python exception set. */
568 compute_enum_values (parmpy_object
*self
, PyObject
*enum_values
)
571 struct cleanup
*back_to
;
575 PyErr_SetString (PyExc_RuntimeError
,
576 _("An enumeration is required for PARAM_ENUM."));
580 if (! PySequence_Check (enum_values
))
582 PyErr_SetString (PyExc_RuntimeError
,
583 _("The enumeration is not a sequence."));
587 size
= PySequence_Size (enum_values
);
592 PyErr_SetString (PyExc_RuntimeError
,
593 _("The enumeration is empty."));
597 self
->enumeration
= xmalloc ((size
+ 1) * sizeof (char *));
598 back_to
= make_cleanup (free_current_contents
, &self
->enumeration
);
599 memset (self
->enumeration
, 0, (size
+ 1) * sizeof (char *));
601 for (i
= 0; i
< size
; ++i
)
603 PyObject
*item
= PySequence_GetItem (enum_values
, i
);
607 do_cleanups (back_to
);
610 if (! gdbpy_is_string (item
))
613 do_cleanups (back_to
);
614 PyErr_SetString (PyExc_RuntimeError
,
615 _("The enumeration item not a string."));
618 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 return gdb_pymodule_addobject (gdb_module
, "Parameter",
777 (PyObject
*) &parmpy_object_type
);
782 static PyTypeObject parmpy_object_type
=
784 PyVarObject_HEAD_INIT (NULL
, 0)
785 "gdb.Parameter", /*tp_name*/
786 sizeof (parmpy_object
), /*tp_basicsize*/
795 0, /*tp_as_sequence*/
800 get_attr
, /*tp_getattro*/
801 set_attr
, /*tp_setattro*/
803 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
804 "GDB parameter object", /* tp_doc */
807 0, /* tp_richcompare */
808 0, /* tp_weaklistoffset */
816 0, /* tp_descr_get */
817 0, /* tp_descr_set */
818 0, /* tp_dictoffset */
819 parmpy_init
, /* tp_init */