1 /* GDB parameters implemented in Python
3 Copyright (C) 2008-2018 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_ZUINTEGER", var_zuinteger
},
51 { "PARAM_ZUINTEGER_UNLIMITED", var_zuinteger_unlimited
},
52 { "PARAM_ENUM", var_enum
},
56 /* A union that can hold anything described by enum var_types. */
59 /* Hold an integer value, for boolean and integer types. */
62 /* Hold an auto_boolean. */
63 enum auto_boolean autoboolval
;
65 /* Hold an unsigned integer value, for uinteger. */
68 /* Hold a string, for the various string types. */
71 /* Hold a string, for enums. */
72 const char *cstringval
;
75 /* A GDB parameter. */
80 /* The type of the parameter. */
83 /* The value of the parameter. */
84 union parmpy_variable value
;
86 /* For an enum command, the possible values. The vector is
87 allocated with xmalloc, as is each element. It is
89 const char **enumeration
;
92 typedef struct parmpy_object parmpy_object
;
94 extern PyTypeObject parmpy_object_type
95 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("parmpy_object");
97 /* Some handy string constants. */
98 static PyObject
*set_doc_cst
;
99 static PyObject
*show_doc_cst
;
103 /* Get an attribute. */
105 get_attr (PyObject
*obj
, PyObject
*attr_name
)
107 if (PyString_Check (attr_name
)
109 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
111 && ! strcmp (PyString_AsString (attr_name
), "value"))
114 parmpy_object
*self
= (parmpy_object
*) obj
;
116 return gdbpy_parameter_value (self
->type
, &self
->value
);
119 return PyObject_GenericGetAttr (obj
, attr_name
);
122 /* Set a parameter value from a Python value. Return 0 on success. Returns
123 -1 on error, with a python exception set. */
125 set_parameter_value (parmpy_object
*self
, PyObject
*value
)
132 case var_string_noescape
:
133 case var_optional_filename
:
135 if (! gdbpy_is_string (value
)
136 && (self
->type
== var_filename
137 || value
!= Py_None
))
139 PyErr_SetString (PyExc_RuntimeError
,
140 _("String required for filename."));
144 if (value
== Py_None
)
146 xfree (self
->value
.stringval
);
147 if (self
->type
== var_optional_filename
)
148 self
->value
.stringval
= xstrdup ("");
150 self
->value
.stringval
= NULL
;
154 gdb::unique_xmalloc_ptr
<char>
155 string (python_string_to_host_string (value
));
159 xfree (self
->value
.stringval
);
160 self
->value
.stringval
= string
.release ();
168 if (! gdbpy_is_string (value
))
170 PyErr_SetString (PyExc_RuntimeError
,
171 _("ENUM arguments must be a string."));
175 gdb::unique_xmalloc_ptr
<char>
176 str (python_string_to_host_string (value
));
179 for (i
= 0; self
->enumeration
[i
]; ++i
)
180 if (! strcmp (self
->enumeration
[i
], str
.get ()))
182 if (! self
->enumeration
[i
])
184 PyErr_SetString (PyExc_RuntimeError
,
185 _("The value must be member of an enumeration."));
188 self
->value
.cstringval
= self
->enumeration
[i
];
193 if (! PyBool_Check (value
))
195 PyErr_SetString (PyExc_RuntimeError
,
196 _("A boolean argument is required."));
199 cmp
= PyObject_IsTrue (value
);
202 self
->value
.intval
= cmp
;
205 case var_auto_boolean
:
206 if (! PyBool_Check (value
) && value
!= Py_None
)
208 PyErr_SetString (PyExc_RuntimeError
,
209 _("A boolean or None is required"));
213 if (value
== Py_None
)
214 self
->value
.autoboolval
= AUTO_BOOLEAN_AUTO
;
217 cmp
= PyObject_IsTrue (value
);
221 self
->value
.autoboolval
= AUTO_BOOLEAN_TRUE
;
223 self
->value
.autoboolval
= AUTO_BOOLEAN_FALSE
;
231 case var_zuinteger_unlimited
:
236 if (! PyInt_Check (value
))
238 PyErr_SetString (PyExc_RuntimeError
,
239 _("The value must be integer."));
243 if (! gdb_py_int_as_long (value
, &l
))
253 ok
= (l
>= 0 && l
<= UINT_MAX
);
256 case var_zuinteger_unlimited
:
257 ok
= (l
>= -1 && l
<= INT_MAX
);
261 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
267 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
271 gdb_assert_not_reached ("unknown var_ constant");
276 PyErr_SetString (PyExc_RuntimeError
,
277 _("Range exceeded."));
281 if (self
->type
== var_uinteger
|| self
->type
== var_zuinteger
)
282 self
->value
.uintval
= (unsigned) l
;
284 self
->value
.intval
= (int) l
;
289 PyErr_SetString (PyExc_RuntimeError
,
290 _("Unhandled type in parameter value."));
297 /* Set an attribute. Returns -1 on error, with a python exception set. */
299 set_attr (PyObject
*obj
, PyObject
*attr_name
, PyObject
*val
)
301 if (PyString_Check (attr_name
)
303 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
305 && ! strcmp (PyString_AsString (attr_name
), "value"))
310 PyErr_SetString (PyExc_RuntimeError
,
311 _("Cannot delete a parameter's value."));
314 return set_parameter_value ((parmpy_object
*) obj
, val
);
317 return PyObject_GenericSetAttr (obj
, attr_name
, val
);
320 /* A helper function which returns a documentation string for an
323 static gdb::unique_xmalloc_ptr
<char>
324 get_doc_string (PyObject
*object
, PyObject
*attr
)
326 gdb::unique_xmalloc_ptr
<char> result
;
328 if (PyObject_HasAttr (object
, attr
))
330 gdbpy_ref
<> ds_obj (PyObject_GetAttr (object
, attr
));
332 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
334 result
= python_string_to_host_string (ds_obj
.get ());
336 gdbpy_print_stack ();
340 result
.reset (xstrdup (_("This command is not documented.")));
344 /* Helper function which will execute a METHOD in OBJ passing the
345 argument ARG. ARG can be NULL. METHOD should return a Python
346 string. If this function returns NULL, there has been an error and
347 the appropriate exception set. */
348 static gdb::unique_xmalloc_ptr
<char>
349 call_doc_function (PyObject
*obj
, PyObject
*method
, PyObject
*arg
)
351 gdb::unique_xmalloc_ptr
<char> data
;
352 gdbpy_ref
<> result (PyObject_CallMethodObjArgs (obj
, method
, arg
, NULL
));
357 if (gdbpy_is_string (result
.get ()))
359 data
= python_string_to_host_string (result
.get ());
365 PyErr_SetString (PyExc_RuntimeError
,
366 _("Parameter must return a string value."));
373 /* A callback function that is registered against the respective
374 add_setshow_* set_doc prototype. This function will either call
375 the Python function "get_set_string" or extract the Python
376 attribute "set_doc" and return the contents as a string. If
377 neither exist, insert a string indicating the Parameter is not
380 get_set_value (const char *args
, int from_tty
,
381 struct cmd_list_element
*c
)
383 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
384 gdb::unique_xmalloc_ptr
<char> set_doc_string
;
386 gdbpy_enter
enter_py (get_current_arch (), current_language
);
387 gdbpy_ref
<> set_doc_func (PyString_FromString ("get_set_string"));
389 if (set_doc_func
== NULL
)
391 gdbpy_print_stack ();
395 if (PyObject_HasAttr (obj
, set_doc_func
.get ()))
397 set_doc_string
= call_doc_function (obj
, set_doc_func
.get (), NULL
);
398 if (! set_doc_string
)
400 gdbpy_print_stack ();
406 /* We have to preserve the existing < GDB 7.3 API. If a
407 callback function does not exist, then attempt to read the
408 set_doc attribute. */
409 set_doc_string
= get_doc_string (obj
, set_doc_cst
);
412 fprintf_filtered (gdb_stdout
, "%s\n", set_doc_string
.get ());
415 /* A callback function that is registered against the respective
416 add_setshow_* show_doc prototype. This function will either call
417 the Python function "get_show_string" or extract the Python
418 attribute "show_doc" and return the contents as a string. If
419 neither exist, insert a string indicating the Parameter is not
422 get_show_value (struct ui_file
*file
, int from_tty
,
423 struct cmd_list_element
*c
,
426 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
427 gdb::unique_xmalloc_ptr
<char> show_doc_string
;
429 gdbpy_enter
enter_py (get_current_arch (), current_language
);
430 gdbpy_ref
<> show_doc_func (PyString_FromString ("get_show_string"));
432 if (show_doc_func
== NULL
)
434 gdbpy_print_stack ();
438 if (PyObject_HasAttr (obj
, show_doc_func
.get ()))
440 gdbpy_ref
<> val_obj (PyString_FromString (value
));
444 gdbpy_print_stack ();
448 show_doc_string
= call_doc_function (obj
, show_doc_func
.get (),
450 if (! show_doc_string
)
452 gdbpy_print_stack ();
456 fprintf_filtered (file
, "%s\n", show_doc_string
.get ());
460 /* We have to preserve the existing < GDB 7.3 API. If a
461 callback function does not exist, then attempt to read the
462 show_doc attribute. */
463 show_doc_string
= get_doc_string (obj
, show_doc_cst
);
464 fprintf_filtered (file
, "%s %s\n", show_doc_string
.get (), value
);
469 /* A helper function that dispatches to the appropriate add_setshow
472 add_setshow_generic (int parmclass
, enum command_class cmdclass
,
473 char *cmd_name
, parmpy_object
*self
,
474 char *set_doc
, char *show_doc
, char *help_doc
,
475 struct cmd_list_element
**set_list
,
476 struct cmd_list_element
**show_list
)
478 struct cmd_list_element
*param
= NULL
;
479 const char *tmp_name
= NULL
;
485 add_setshow_boolean_cmd (cmd_name
, cmdclass
,
486 &self
->value
.intval
, set_doc
, show_doc
,
487 help_doc
, get_set_value
, get_show_value
,
488 set_list
, show_list
);
492 case var_auto_boolean
:
493 add_setshow_auto_boolean_cmd (cmd_name
, cmdclass
,
494 &self
->value
.autoboolval
,
495 set_doc
, show_doc
, help_doc
,
496 get_set_value
, get_show_value
,
497 set_list
, show_list
);
501 add_setshow_uinteger_cmd (cmd_name
, cmdclass
,
502 &self
->value
.uintval
, set_doc
, show_doc
,
503 help_doc
, get_set_value
, get_show_value
,
504 set_list
, show_list
);
508 add_setshow_integer_cmd (cmd_name
, cmdclass
,
509 &self
->value
.intval
, set_doc
, show_doc
,
510 help_doc
, get_set_value
, get_show_value
,
511 set_list
, show_list
); break;
514 add_setshow_string_cmd (cmd_name
, cmdclass
,
515 &self
->value
.stringval
, set_doc
, show_doc
,
516 help_doc
, get_set_value
, get_show_value
,
517 set_list
, show_list
); break;
519 case var_string_noescape
:
520 add_setshow_string_noescape_cmd (cmd_name
, cmdclass
,
521 &self
->value
.stringval
,
522 set_doc
, show_doc
, help_doc
,
523 get_set_value
, get_show_value
,
524 set_list
, show_list
);
528 case var_optional_filename
:
529 add_setshow_optional_filename_cmd (cmd_name
, cmdclass
,
530 &self
->value
.stringval
, set_doc
,
531 show_doc
, help_doc
, get_set_value
,
532 get_show_value
, set_list
,
537 add_setshow_filename_cmd (cmd_name
, cmdclass
,
538 &self
->value
.stringval
, set_doc
, show_doc
,
539 help_doc
, get_set_value
, get_show_value
,
540 set_list
, show_list
); break;
543 add_setshow_zinteger_cmd (cmd_name
, cmdclass
,
544 &self
->value
.intval
, set_doc
, show_doc
,
545 help_doc
, get_set_value
, get_show_value
,
546 set_list
, show_list
);
550 add_setshow_zuinteger_cmd (cmd_name
, cmdclass
,
551 &self
->value
.uintval
, set_doc
, show_doc
,
552 help_doc
, get_set_value
, get_show_value
,
553 set_list
, show_list
);
556 case var_zuinteger_unlimited
:
557 add_setshow_zuinteger_unlimited_cmd (cmd_name
, cmdclass
,
558 &self
->value
.intval
, set_doc
,
559 show_doc
, help_doc
, get_set_value
,
561 set_list
, show_list
);
565 add_setshow_enum_cmd (cmd_name
, cmdclass
, self
->enumeration
,
566 &self
->value
.cstringval
, set_doc
, show_doc
,
567 help_doc
, get_set_value
, get_show_value
,
568 set_list
, show_list
);
569 /* Initialize the value, just in case. */
570 self
->value
.cstringval
= self
->enumeration
[0];
574 /* Lookup created parameter, and register Python object against the
575 parameter context. Perform this task against both lists. */
577 param
= lookup_cmd (&tmp_name
, *show_list
, "", 0, 1);
579 set_cmd_context (param
, self
);
582 param
= lookup_cmd (&tmp_name
, *set_list
, "", 0, 1);
584 set_cmd_context (param
, self
);
587 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
588 error, with a python exception set. */
590 compute_enum_values (parmpy_object
*self
, PyObject
*enum_values
)
596 PyErr_SetString (PyExc_RuntimeError
,
597 _("An enumeration is required for PARAM_ENUM."));
601 if (! PySequence_Check (enum_values
))
603 PyErr_SetString (PyExc_RuntimeError
,
604 _("The enumeration is not a sequence."));
608 size
= PySequence_Size (enum_values
);
613 PyErr_SetString (PyExc_RuntimeError
,
614 _("The enumeration is empty."));
618 gdb_argv
holder (XCNEWVEC (char *, size
+ 1));
619 char **enumeration
= holder
.get ();
621 for (i
= 0; i
< size
; ++i
)
623 gdbpy_ref
<> item (PySequence_GetItem (enum_values
, i
));
627 if (! gdbpy_is_string (item
.get ()))
629 PyErr_SetString (PyExc_RuntimeError
,
630 _("The enumeration item not a string."));
633 enumeration
[i
] = python_string_to_host_string (item
.get ()).release ();
634 if (enumeration
[i
] == NULL
)
638 self
->enumeration
= const_cast<const char**> (holder
.release ());
642 /* Object initializer; sets up gdb-side structures for command.
644 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
646 NAME is the name of the parameter. It may consist of multiple
647 words, in which case the final word is the name of the new command,
648 and earlier words must be prefix commands.
650 CMDCLASS is the kind of command. It should be one of the COMMAND_*
651 constants defined in the gdb module.
653 PARMCLASS is the type of the parameter. It should be one of the
654 PARAM_* constants defined in the gdb module.
656 If PARMCLASS is PARAM_ENUM, then the final argument should be a
657 collection of strings. These strings are the valid values for this
660 The documentation for the parameter is taken from the doc string
661 for the python class.
663 Returns -1 on error, with a python exception set. */
666 parmpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kwds
)
668 parmpy_object
*obj
= (parmpy_object
*) self
;
670 char *set_doc
, *show_doc
, *doc
;
672 int parmclass
, cmdtype
;
673 PyObject
*enum_values
= NULL
;
674 struct cmd_list_element
**set_list
, **show_list
;
676 if (! PyArg_ParseTuple (args
, "sii|O", &name
, &cmdtype
, &parmclass
,
680 if (cmdtype
!= no_class
&& cmdtype
!= class_run
681 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
682 && cmdtype
!= class_files
&& cmdtype
!= class_support
683 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
684 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
685 && cmdtype
!= class_maintenance
)
687 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
691 if (parmclass
!= var_boolean
/* ARI: var_boolean */
692 && parmclass
!= var_auto_boolean
693 && parmclass
!= var_uinteger
&& parmclass
!= var_integer
694 && parmclass
!= var_string
&& parmclass
!= var_string_noescape
695 && parmclass
!= var_optional_filename
&& parmclass
!= var_filename
696 && parmclass
!= var_zinteger
&& parmclass
!= var_zuinteger
697 && parmclass
!= var_zuinteger_unlimited
&& parmclass
!= var_enum
)
699 PyErr_SetString (PyExc_RuntimeError
,
700 _("Invalid parameter class argument."));
704 if (enum_values
&& parmclass
!= var_enum
)
706 PyErr_SetString (PyExc_RuntimeError
,
707 _("Only PARAM_ENUM accepts a fourth argument."));
710 if (parmclass
== var_enum
)
712 if (! compute_enum_values (obj
, enum_values
))
716 obj
->enumeration
= NULL
;
717 obj
->type
= (enum var_types
) parmclass
;
718 memset (&obj
->value
, 0, sizeof (obj
->value
));
720 cmd_name
= gdbpy_parse_command_name (name
, &set_list
,
726 cmd_name
= gdbpy_parse_command_name (name
, &show_list
,
731 set_doc
= get_doc_string (self
, set_doc_cst
).release ();
732 show_doc
= get_doc_string (self
, show_doc_cst
).release ();
733 doc
= get_doc_string (self
, gdbpy_doc_cst
).release ();
739 add_setshow_generic (parmclass
, (enum command_class
) cmdtype
,
742 doc
, set_list
, show_list
);
744 CATCH (except
, RETURN_MASK_ALL
)
751 PyErr_Format (except
.reason
== RETURN_QUIT
752 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
753 "%s", except
.message
);
763 /* Initialize the 'parameters' module. */
765 gdbpy_initialize_parameters (void)
769 parmpy_object_type
.tp_new
= PyType_GenericNew
;
770 if (PyType_Ready (&parmpy_object_type
) < 0)
773 set_doc_cst
= PyString_FromString ("set_doc");
776 show_doc_cst
= PyString_FromString ("show_doc");
780 for (i
= 0; parm_constants
[i
].name
; ++i
)
782 if (PyModule_AddIntConstant (gdb_module
,
783 parm_constants
[i
].name
,
784 parm_constants
[i
].value
) < 0)
788 return gdb_pymodule_addobject (gdb_module
, "Parameter",
789 (PyObject
*) &parmpy_object_type
);
794 PyTypeObject parmpy_object_type
=
796 PyVarObject_HEAD_INIT (NULL
, 0)
797 "gdb.Parameter", /*tp_name*/
798 sizeof (parmpy_object
), /*tp_basicsize*/
807 0, /*tp_as_sequence*/
812 get_attr
, /*tp_getattro*/
813 set_attr
, /*tp_setattro*/
815 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
816 "GDB parameter object", /* tp_doc */
819 0, /* tp_richcompare */
820 0, /* tp_weaklistoffset */
828 0, /* tp_descr_get */
829 0, /* tp_descr_set */
830 0, /* tp_dictoffset */
831 parmpy_init
, /* tp_init */