1 /* GDB parameters implemented in Python
3 Copyright (C) 2008-2013 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 "exceptions.h"
24 #include "python-internal.h"
27 #include "cli/cli-decode.h"
28 #include "completer.h"
30 #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 static 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
;
154 string
= python_string_to_host_string (value
);
158 xfree (self
->value
.stringval
);
159 self
->value
.stringval
= string
;
168 if (! gdbpy_is_string (value
))
170 PyErr_SetString (PyExc_RuntimeError
,
171 _("ENUM arguments must be a string."));
175 str
= python_string_to_host_string (value
);
178 for (i
= 0; self
->enumeration
[i
]; ++i
)
179 if (! strcmp (self
->enumeration
[i
], str
))
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
;
234 if (! PyInt_Check (value
))
236 PyErr_SetString (PyExc_RuntimeError
,
237 _("The value must be integer."));
241 if (! gdb_py_int_as_long (value
, &l
))
244 if (self
->type
== var_uinteger
)
246 ok
= (l
>= 0 && l
<= UINT_MAX
);
250 else if (self
->type
== var_integer
)
252 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
257 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
261 PyErr_SetString (PyExc_RuntimeError
,
262 _("Range exceeded."));
266 self
->value
.intval
= (int) l
;
271 PyErr_SetString (PyExc_RuntimeError
,
272 _("Unhandled type in parameter value."));
279 /* Set an attribute. Returns -1 on error, with a python exception set. */
281 set_attr (PyObject
*obj
, PyObject
*attr_name
, PyObject
*val
)
283 if (PyString_Check (attr_name
)
285 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
287 && ! strcmp (PyString_AsString (attr_name
), "value"))
292 PyErr_SetString (PyExc_RuntimeError
,
293 _("Cannot delete a parameter's value."));
296 return set_parameter_value ((parmpy_object
*) obj
, val
);
299 return PyObject_GenericSetAttr (obj
, attr_name
, val
);
302 /* A helper function which returns a documentation string for an
306 get_doc_string (PyObject
*object
, PyObject
*attr
)
310 if (PyObject_HasAttr (object
, attr
))
312 PyObject
*ds_obj
= PyObject_GetAttr (object
, attr
);
314 if (ds_obj
&& gdbpy_is_string (ds_obj
))
316 result
= python_string_to_host_string (ds_obj
);
318 gdbpy_print_stack ();
323 result
= xstrdup (_("This command is not documented."));
327 /* Helper function which will execute a METHOD in OBJ passing the
328 argument ARG. ARG can be NULL. METHOD should return a Python
329 string. If this function returns NULL, there has been an error and
330 the appropriate exception set. */
332 call_doc_function (PyObject
*obj
, PyObject
*method
, PyObject
*arg
)
335 PyObject
*result
= PyObject_CallMethodObjArgs (obj
, method
, arg
, NULL
);
340 if (gdbpy_is_string (result
))
342 data
= python_string_to_host_string (result
);
349 PyErr_SetString (PyExc_RuntimeError
,
350 _("Parameter must return a string value."));
358 /* A callback function that is registered against the respective
359 add_setshow_* set_doc prototype. This function will either call
360 the Python function "get_set_string" or extract the Python
361 attribute "set_doc" and return the contents as a string. If
362 neither exist, insert a string indicating the Parameter is not
365 get_set_value (char *args
, int from_tty
,
366 struct cmd_list_element
*c
)
368 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
369 char *set_doc_string
;
370 struct cleanup
*cleanup
= ensure_python_env (get_current_arch (),
372 PyObject
*set_doc_func
= PyString_FromString ("get_set_string");
377 if (PyObject_HasAttr (obj
, set_doc_func
))
379 set_doc_string
= call_doc_function (obj
, set_doc_func
, NULL
);
380 if (! set_doc_string
)
385 /* We have to preserve the existing < GDB 7.3 API. If a
386 callback function does not exist, then attempt to read the
387 set_doc attribute. */
388 set_doc_string
= get_doc_string (obj
, set_doc_cst
);
391 make_cleanup (xfree
, set_doc_string
);
392 fprintf_filtered (gdb_stdout
, "%s\n", set_doc_string
);
394 Py_XDECREF (set_doc_func
);
395 do_cleanups (cleanup
);
399 Py_XDECREF (set_doc_func
);
400 gdbpy_print_stack ();
401 do_cleanups (cleanup
);
405 /* A callback function that is registered against the respective
406 add_setshow_* show_doc prototype. This function will either call
407 the Python function "get_show_string" or extract the Python
408 attribute "show_doc" and return the contents as a string. If
409 neither exist, insert a string indicating the Parameter is not
412 get_show_value (struct ui_file
*file
, int from_tty
,
413 struct cmd_list_element
*c
,
416 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
417 char *show_doc_string
= NULL
;
418 struct cleanup
*cleanup
= ensure_python_env (get_current_arch (),
420 PyObject
*show_doc_func
= PyString_FromString ("get_show_string");
425 if (PyObject_HasAttr (obj
, show_doc_func
))
427 PyObject
*val_obj
= PyString_FromString (value
);
432 show_doc_string
= call_doc_function (obj
, show_doc_func
, val_obj
);
434 if (! show_doc_string
)
437 make_cleanup (xfree
, show_doc_string
);
439 fprintf_filtered (file
, "%s\n", show_doc_string
);
443 /* We have to preserve the existing < GDB 7.3 API. If a
444 callback function does not exist, then attempt to read the
445 show_doc attribute. */
446 show_doc_string
= get_doc_string (obj
, show_doc_cst
);
447 make_cleanup (xfree
, show_doc_string
);
448 fprintf_filtered (file
, "%s %s\n", show_doc_string
, value
);
451 Py_XDECREF (show_doc_func
);
452 do_cleanups (cleanup
);
456 Py_XDECREF (show_doc_func
);
457 gdbpy_print_stack ();
458 do_cleanups (cleanup
);
463 /* A helper function that dispatches to the appropriate add_setshow
466 add_setshow_generic (int parmclass
, enum command_class cmdclass
,
467 char *cmd_name
, parmpy_object
*self
,
468 char *set_doc
, char *show_doc
, char *help_doc
,
469 struct cmd_list_element
**set_list
,
470 struct cmd_list_element
**show_list
)
472 struct cmd_list_element
*param
= NULL
;
473 const char *tmp_name
= NULL
;
479 add_setshow_boolean_cmd (cmd_name
, cmdclass
,
480 &self
->value
.intval
, set_doc
, show_doc
,
481 help_doc
, get_set_value
, get_show_value
,
482 set_list
, show_list
);
486 case var_auto_boolean
:
487 add_setshow_auto_boolean_cmd (cmd_name
, cmdclass
,
488 &self
->value
.autoboolval
,
489 set_doc
, show_doc
, help_doc
,
490 get_set_value
, get_show_value
,
491 set_list
, show_list
);
495 add_setshow_uinteger_cmd (cmd_name
, cmdclass
,
496 &self
->value
.uintval
, set_doc
, show_doc
,
497 help_doc
, get_set_value
, get_show_value
,
498 set_list
, show_list
);
502 add_setshow_integer_cmd (cmd_name
, cmdclass
,
503 &self
->value
.intval
, set_doc
, show_doc
,
504 help_doc
, get_set_value
, get_show_value
,
505 set_list
, show_list
); break;
508 add_setshow_string_cmd (cmd_name
, cmdclass
,
509 &self
->value
.stringval
, set_doc
, show_doc
,
510 help_doc
, get_set_value
, get_show_value
,
511 set_list
, show_list
); break;
513 case var_string_noescape
:
514 add_setshow_string_noescape_cmd (cmd_name
, cmdclass
,
515 &self
->value
.stringval
,
516 set_doc
, show_doc
, help_doc
,
517 get_set_value
, get_show_value
,
518 set_list
, show_list
);
522 case var_optional_filename
:
523 add_setshow_optional_filename_cmd (cmd_name
, cmdclass
,
524 &self
->value
.stringval
, set_doc
,
525 show_doc
, help_doc
, get_set_value
,
526 get_show_value
, set_list
,
531 add_setshow_filename_cmd (cmd_name
, cmdclass
,
532 &self
->value
.stringval
, set_doc
, show_doc
,
533 help_doc
, get_set_value
, get_show_value
,
534 set_list
, show_list
); break;
537 add_setshow_zinteger_cmd (cmd_name
, cmdclass
,
538 &self
->value
.intval
, set_doc
, show_doc
,
539 help_doc
, get_set_value
, get_show_value
,
540 set_list
, show_list
);
544 add_setshow_enum_cmd (cmd_name
, cmdclass
, self
->enumeration
,
545 &self
->value
.cstringval
, set_doc
, show_doc
,
546 help_doc
, get_set_value
, get_show_value
,
547 set_list
, show_list
);
548 /* Initialize the value, just in case. */
549 self
->value
.cstringval
= self
->enumeration
[0];
553 /* Lookup created parameter, and register Python object against the
554 parameter context. Perform this task against both lists. */
556 param
= lookup_cmd (&tmp_name
, *show_list
, "", 0, 1);
558 set_cmd_context (param
, self
);
561 param
= lookup_cmd (&tmp_name
, *set_list
, "", 0, 1);
563 set_cmd_context (param
, self
);
566 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
567 error, with a python exception set. */
569 compute_enum_values (parmpy_object
*self
, PyObject
*enum_values
)
572 struct cleanup
*back_to
;
576 PyErr_SetString (PyExc_RuntimeError
,
577 _("An enumeration is required for PARAM_ENUM."));
581 if (! PySequence_Check (enum_values
))
583 PyErr_SetString (PyExc_RuntimeError
,
584 _("The enumeration is not a sequence."));
588 size
= PySequence_Size (enum_values
);
593 PyErr_SetString (PyExc_RuntimeError
,
594 _("The enumeration is empty."));
598 self
->enumeration
= xmalloc ((size
+ 1) * sizeof (char *));
599 back_to
= make_cleanup (free_current_contents
, &self
->enumeration
);
600 memset (self
->enumeration
, 0, (size
+ 1) * sizeof (char *));
602 for (i
= 0; i
< size
; ++i
)
604 PyObject
*item
= PySequence_GetItem (enum_values
, i
);
608 do_cleanups (back_to
);
611 if (! gdbpy_is_string (item
))
614 do_cleanups (back_to
);
615 PyErr_SetString (PyExc_RuntimeError
,
616 _("The enumeration item not a string."));
619 self
->enumeration
[i
] = python_string_to_host_string (item
);
621 if (self
->enumeration
[i
] == NULL
)
623 do_cleanups (back_to
);
626 make_cleanup (xfree
, (char *) self
->enumeration
[i
]);
629 discard_cleanups (back_to
);
633 /* Object initializer; sets up gdb-side structures for command.
635 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
637 NAME is the name of the parameter. It may consist of multiple
638 words, in which case the final word is the name of the new command,
639 and earlier words must be prefix commands.
641 CMDCLASS is the kind of command. It should be one of the COMMAND_*
642 constants defined in the gdb module.
644 PARMCLASS is the type of the parameter. It should be one of the
645 PARAM_* constants defined in the gdb module.
647 If PARMCLASS is PARAM_ENUM, then the final argument should be a
648 collection of strings. These strings are the valid values for this
651 The documentation for the parameter is taken from the doc string
652 for the python class.
654 Returns -1 on error, with a python exception set. */
657 parmpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kwds
)
659 parmpy_object
*obj
= (parmpy_object
*) self
;
661 char *set_doc
, *show_doc
, *doc
;
663 int parmclass
, cmdtype
;
664 PyObject
*enum_values
= NULL
;
665 struct cmd_list_element
**set_list
, **show_list
;
666 volatile struct gdb_exception except
;
668 if (! PyArg_ParseTuple (args
, "sii|O", &name
, &cmdtype
, &parmclass
,
672 if (cmdtype
!= no_class
&& cmdtype
!= class_run
673 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
674 && cmdtype
!= class_files
&& cmdtype
!= class_support
675 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
676 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
677 && cmdtype
!= class_maintenance
)
679 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
683 if (parmclass
!= var_boolean
/* ARI: var_boolean */
684 && parmclass
!= var_auto_boolean
685 && parmclass
!= var_uinteger
&& parmclass
!= var_integer
686 && parmclass
!= var_string
&& parmclass
!= var_string_noescape
687 && parmclass
!= var_optional_filename
&& parmclass
!= var_filename
688 && parmclass
!= var_zinteger
&& parmclass
!= var_enum
)
690 PyErr_SetString (PyExc_RuntimeError
,
691 _("Invalid parameter class argument."));
695 if (enum_values
&& parmclass
!= var_enum
)
697 PyErr_SetString (PyExc_RuntimeError
,
698 _("Only PARAM_ENUM accepts a fourth argument."));
701 if (parmclass
== var_enum
)
703 if (! compute_enum_values (obj
, enum_values
))
707 obj
->enumeration
= NULL
;
708 obj
->type
= (enum var_types
) parmclass
;
709 memset (&obj
->value
, 0, sizeof (obj
->value
));
711 cmd_name
= gdbpy_parse_command_name (name
, &set_list
,
717 cmd_name
= gdbpy_parse_command_name (name
, &show_list
,
722 set_doc
= get_doc_string (self
, set_doc_cst
);
723 show_doc
= get_doc_string (self
, show_doc_cst
);
724 doc
= get_doc_string (self
, gdbpy_doc_cst
);
728 TRY_CATCH (except
, RETURN_MASK_ALL
)
730 add_setshow_generic (parmclass
, (enum command_class
) cmdtype
,
733 doc
, set_list
, show_list
);
735 if (except
.reason
< 0)
742 PyErr_Format (except
.reason
== RETURN_QUIT
743 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
744 "%s", except
.message
);
752 /* Initialize the 'parameters' module. */
754 gdbpy_initialize_parameters (void)
758 parmpy_object_type
.tp_new
= PyType_GenericNew
;
759 if (PyType_Ready (&parmpy_object_type
) < 0)
762 set_doc_cst
= PyString_FromString ("set_doc");
765 show_doc_cst
= PyString_FromString ("show_doc");
769 for (i
= 0; parm_constants
[i
].name
; ++i
)
771 if (PyModule_AddIntConstant (gdb_module
,
772 parm_constants
[i
].name
,
773 parm_constants
[i
].value
) < 0)
777 return gdb_pymodule_addobject (gdb_module
, "Parameter",
778 (PyObject
*) &parmpy_object_type
);
783 static PyTypeObject parmpy_object_type
=
785 PyVarObject_HEAD_INIT (NULL
, 0)
786 "gdb.Parameter", /*tp_name*/
787 sizeof (parmpy_object
), /*tp_basicsize*/
796 0, /*tp_as_sequence*/
801 get_attr
, /*tp_getattro*/
802 set_attr
, /*tp_setattro*/
804 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
805 "GDB parameter object", /* tp_doc */
808 0, /* tp_richcompare */
809 0, /* tp_weaklistoffset */
817 0, /* tp_descr_get */
818 0, /* tp_descr_set */
819 0, /* tp_dictoffset */
820 parmpy_init
, /* tp_init */