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
;
367 gdbpy_enter
enter_py (get_current_arch (), current_language
);
368 gdbpy_ref
set_doc_func (PyString_FromString ("get_set_string"));
370 if (set_doc_func
== NULL
)
372 gdbpy_print_stack ();
376 if (PyObject_HasAttr (obj
, set_doc_func
.get ()))
378 set_doc_string
= call_doc_function (obj
, set_doc_func
.get (), NULL
);
379 if (! set_doc_string
)
381 gdbpy_print_stack ();
387 /* We have to preserve the existing < GDB 7.3 API. If a
388 callback function does not exist, then attempt to read the
389 set_doc attribute. */
390 set_doc_string
= get_doc_string (obj
, set_doc_cst
);
393 fprintf_filtered (gdb_stdout
, "%s\n", set_doc_string
.get ());
396 /* A callback function that is registered against the respective
397 add_setshow_* show_doc prototype. This function will either call
398 the Python function "get_show_string" or extract the Python
399 attribute "show_doc" and return the contents as a string. If
400 neither exist, insert a string indicating the Parameter is not
403 get_show_value (struct ui_file
*file
, int from_tty
,
404 struct cmd_list_element
*c
,
407 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
408 gdb::unique_xmalloc_ptr
<char> show_doc_string
;
410 gdbpy_enter
enter_py (get_current_arch (), current_language
);
411 gdbpy_ref
show_doc_func (PyString_FromString ("get_show_string"));
413 if (show_doc_func
== NULL
)
415 gdbpy_print_stack ();
419 if (PyObject_HasAttr (obj
, show_doc_func
.get ()))
421 gdbpy_ref
val_obj (PyString_FromString (value
));
425 gdbpy_print_stack ();
429 show_doc_string
= call_doc_function (obj
, show_doc_func
.get (),
431 if (! show_doc_string
)
433 gdbpy_print_stack ();
437 fprintf_filtered (file
, "%s\n", show_doc_string
.get ());
441 /* We have to preserve the existing < GDB 7.3 API. If a
442 callback function does not exist, then attempt to read the
443 show_doc attribute. */
444 show_doc_string
= get_doc_string (obj
, show_doc_cst
);
445 fprintf_filtered (file
, "%s %s\n", show_doc_string
.get (), value
);
450 /* A helper function that dispatches to the appropriate add_setshow
453 add_setshow_generic (int parmclass
, enum command_class cmdclass
,
454 char *cmd_name
, parmpy_object
*self
,
455 char *set_doc
, char *show_doc
, char *help_doc
,
456 struct cmd_list_element
**set_list
,
457 struct cmd_list_element
**show_list
)
459 struct cmd_list_element
*param
= NULL
;
460 const char *tmp_name
= NULL
;
466 add_setshow_boolean_cmd (cmd_name
, cmdclass
,
467 &self
->value
.intval
, set_doc
, show_doc
,
468 help_doc
, get_set_value
, get_show_value
,
469 set_list
, show_list
);
473 case var_auto_boolean
:
474 add_setshow_auto_boolean_cmd (cmd_name
, cmdclass
,
475 &self
->value
.autoboolval
,
476 set_doc
, show_doc
, help_doc
,
477 get_set_value
, get_show_value
,
478 set_list
, show_list
);
482 add_setshow_uinteger_cmd (cmd_name
, cmdclass
,
483 &self
->value
.uintval
, set_doc
, show_doc
,
484 help_doc
, get_set_value
, get_show_value
,
485 set_list
, show_list
);
489 add_setshow_integer_cmd (cmd_name
, cmdclass
,
490 &self
->value
.intval
, set_doc
, show_doc
,
491 help_doc
, get_set_value
, get_show_value
,
492 set_list
, show_list
); break;
495 add_setshow_string_cmd (cmd_name
, cmdclass
,
496 &self
->value
.stringval
, set_doc
, show_doc
,
497 help_doc
, get_set_value
, get_show_value
,
498 set_list
, show_list
); break;
500 case var_string_noescape
:
501 add_setshow_string_noescape_cmd (cmd_name
, cmdclass
,
502 &self
->value
.stringval
,
503 set_doc
, show_doc
, help_doc
,
504 get_set_value
, get_show_value
,
505 set_list
, show_list
);
509 case var_optional_filename
:
510 add_setshow_optional_filename_cmd (cmd_name
, cmdclass
,
511 &self
->value
.stringval
, set_doc
,
512 show_doc
, help_doc
, get_set_value
,
513 get_show_value
, set_list
,
518 add_setshow_filename_cmd (cmd_name
, cmdclass
,
519 &self
->value
.stringval
, set_doc
, show_doc
,
520 help_doc
, get_set_value
, get_show_value
,
521 set_list
, show_list
); break;
524 add_setshow_zinteger_cmd (cmd_name
, cmdclass
,
525 &self
->value
.intval
, set_doc
, show_doc
,
526 help_doc
, get_set_value
, get_show_value
,
527 set_list
, show_list
);
531 add_setshow_enum_cmd (cmd_name
, cmdclass
, self
->enumeration
,
532 &self
->value
.cstringval
, set_doc
, show_doc
,
533 help_doc
, get_set_value
, get_show_value
,
534 set_list
, show_list
);
535 /* Initialize the value, just in case. */
536 self
->value
.cstringval
= self
->enumeration
[0];
540 /* Lookup created parameter, and register Python object against the
541 parameter context. Perform this task against both lists. */
543 param
= lookup_cmd (&tmp_name
, *show_list
, "", 0, 1);
545 set_cmd_context (param
, self
);
548 param
= lookup_cmd (&tmp_name
, *set_list
, "", 0, 1);
550 set_cmd_context (param
, self
);
553 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
554 error, with a python exception set. */
556 compute_enum_values (parmpy_object
*self
, PyObject
*enum_values
)
559 struct cleanup
*back_to
;
563 PyErr_SetString (PyExc_RuntimeError
,
564 _("An enumeration is required for PARAM_ENUM."));
568 if (! PySequence_Check (enum_values
))
570 PyErr_SetString (PyExc_RuntimeError
,
571 _("The enumeration is not a sequence."));
575 size
= PySequence_Size (enum_values
);
580 PyErr_SetString (PyExc_RuntimeError
,
581 _("The enumeration is empty."));
585 self
->enumeration
= XCNEWVEC (const char *, size
+ 1);
586 back_to
= make_cleanup (free_current_contents
, &self
->enumeration
);
588 for (i
= 0; i
< size
; ++i
)
590 PyObject
*item
= PySequence_GetItem (enum_values
, i
);
594 do_cleanups (back_to
);
597 if (! gdbpy_is_string (item
))
600 do_cleanups (back_to
);
601 PyErr_SetString (PyExc_RuntimeError
,
602 _("The enumeration item not a string."));
605 self
->enumeration
[i
] = python_string_to_host_string (item
).release ();
607 if (self
->enumeration
[i
] == NULL
)
609 do_cleanups (back_to
);
612 make_cleanup (xfree
, (char *) self
->enumeration
[i
]);
615 discard_cleanups (back_to
);
619 /* Object initializer; sets up gdb-side structures for command.
621 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
623 NAME is the name of the parameter. It may consist of multiple
624 words, in which case the final word is the name of the new command,
625 and earlier words must be prefix commands.
627 CMDCLASS is the kind of command. It should be one of the COMMAND_*
628 constants defined in the gdb module.
630 PARMCLASS is the type of the parameter. It should be one of the
631 PARAM_* constants defined in the gdb module.
633 If PARMCLASS is PARAM_ENUM, then the final argument should be a
634 collection of strings. These strings are the valid values for this
637 The documentation for the parameter is taken from the doc string
638 for the python class.
640 Returns -1 on error, with a python exception set. */
643 parmpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kwds
)
645 parmpy_object
*obj
= (parmpy_object
*) self
;
647 char *set_doc
, *show_doc
, *doc
;
649 int parmclass
, cmdtype
;
650 PyObject
*enum_values
= NULL
;
651 struct cmd_list_element
**set_list
, **show_list
;
653 if (! PyArg_ParseTuple (args
, "sii|O", &name
, &cmdtype
, &parmclass
,
657 if (cmdtype
!= no_class
&& cmdtype
!= class_run
658 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
659 && cmdtype
!= class_files
&& cmdtype
!= class_support
660 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
661 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
662 && cmdtype
!= class_maintenance
)
664 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
668 if (parmclass
!= var_boolean
/* ARI: var_boolean */
669 && parmclass
!= var_auto_boolean
670 && parmclass
!= var_uinteger
&& parmclass
!= var_integer
671 && parmclass
!= var_string
&& parmclass
!= var_string_noescape
672 && parmclass
!= var_optional_filename
&& parmclass
!= var_filename
673 && parmclass
!= var_zinteger
&& parmclass
!= var_enum
)
675 PyErr_SetString (PyExc_RuntimeError
,
676 _("Invalid parameter class argument."));
680 if (enum_values
&& parmclass
!= var_enum
)
682 PyErr_SetString (PyExc_RuntimeError
,
683 _("Only PARAM_ENUM accepts a fourth argument."));
686 if (parmclass
== var_enum
)
688 if (! compute_enum_values (obj
, enum_values
))
692 obj
->enumeration
= NULL
;
693 obj
->type
= (enum var_types
) parmclass
;
694 memset (&obj
->value
, 0, sizeof (obj
->value
));
696 cmd_name
= gdbpy_parse_command_name (name
, &set_list
,
702 cmd_name
= gdbpy_parse_command_name (name
, &show_list
,
707 set_doc
= get_doc_string (self
, set_doc_cst
).release ();
708 show_doc
= get_doc_string (self
, show_doc_cst
).release ();
709 doc
= get_doc_string (self
, gdbpy_doc_cst
).release ();
715 add_setshow_generic (parmclass
, (enum command_class
) cmdtype
,
718 doc
, set_list
, show_list
);
720 CATCH (except
, RETURN_MASK_ALL
)
727 PyErr_Format (except
.reason
== RETURN_QUIT
728 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
729 "%s", except
.message
);
739 /* Initialize the 'parameters' module. */
741 gdbpy_initialize_parameters (void)
745 parmpy_object_type
.tp_new
= PyType_GenericNew
;
746 if (PyType_Ready (&parmpy_object_type
) < 0)
749 set_doc_cst
= PyString_FromString ("set_doc");
752 show_doc_cst
= PyString_FromString ("show_doc");
756 for (i
= 0; parm_constants
[i
].name
; ++i
)
758 if (PyModule_AddIntConstant (gdb_module
,
759 parm_constants
[i
].name
,
760 parm_constants
[i
].value
) < 0)
764 return gdb_pymodule_addobject (gdb_module
, "Parameter",
765 (PyObject
*) &parmpy_object_type
);
770 PyTypeObject parmpy_object_type
=
772 PyVarObject_HEAD_INIT (NULL
, 0)
773 "gdb.Parameter", /*tp_name*/
774 sizeof (parmpy_object
), /*tp_basicsize*/
783 0, /*tp_as_sequence*/
788 get_attr
, /*tp_getattro*/
789 set_attr
, /*tp_setattro*/
791 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
792 "GDB parameter object", /* tp_doc */
795 0, /* tp_richcompare */
796 0, /* tp_weaklistoffset */
804 0, /* tp_descr_get */
805 0, /* tp_descr_set */
806 0, /* tp_dictoffset */
807 parmpy_init
, /* tp_init */