1 /* gdb commands implemented in Python
3 Copyright (C) 2008-2021 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/>. */
22 #include "arch-utils.h"
24 #include "python-internal.h"
27 #include "cli/cli-decode.h"
28 #include "completer.h"
31 /* Struct representing built-in completion types. */
32 struct cmdpy_completer
34 /* Python symbol name. */
36 /* Completion function. */
37 completer_ftype
*completer
;
40 static const struct cmdpy_completer completers
[] =
42 { "COMPLETE_NONE", noop_completer
},
43 { "COMPLETE_FILENAME", filename_completer
},
44 { "COMPLETE_LOCATION", location_completer
},
45 { "COMPLETE_COMMAND", command_completer
},
46 { "COMPLETE_SYMBOL", symbol_completer
},
47 { "COMPLETE_EXPRESSION", expression_completer
},
50 #define N_COMPLETERS (sizeof (completers) / sizeof (completers[0]))
52 /* A gdb command. For the time being only ordinary commands (not
53 set/show commands) are allowed. */
58 /* The corresponding gdb command object, or NULL if the command is
59 no longer installed. */
60 struct cmd_list_element
*command
;
62 /* A prefix command requires storage for a list of its sub-commands.
63 A pointer to this is passed to add_prefix_command, and to add_cmd
64 for sub-commands of that prefix. If this Command is not a prefix
65 command, then this field is unused. */
66 struct cmd_list_element
*sub_list
;
69 extern PyTypeObject cmdpy_object_type
70 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("cmdpy_object");
72 /* Constants used by this module. */
73 static PyObject
*invoke_cst
;
74 static PyObject
*complete_cst
;
78 /* Python function which wraps dont_repeat. */
80 cmdpy_dont_repeat (PyObject
*self
, PyObject
*args
)
88 /* Called if the gdb cmd_list_element is destroyed. */
91 cmdpy_destroyer (struct cmd_list_element
*self
, void *context
)
93 gdbpy_enter
enter_py (get_current_arch (), current_language
);
95 /* Release our hold on the command object. */
96 gdbpy_ref
<cmdpy_object
> cmd ((cmdpy_object
*) context
);
100 /* Called by gdb to invoke the command. */
103 cmdpy_function (struct cmd_list_element
*command
,
104 const char *args
, int from_tty
)
106 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
108 gdbpy_enter
enter_py (get_current_arch (), current_language
);
111 error (_("Invalid invocation of Python command object."));
112 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
114 if (obj
->command
->is_prefix ())
116 /* A prefix command does not need an invoke method. */
119 error (_("Python command object missing 'invoke' method."));
124 gdbpy_ref
<> argobj (PyUnicode_Decode (args
, strlen (args
), host_charset (),
128 gdbpy_print_stack ();
129 error (_("Could not convert arguments to Python string."));
133 = gdbpy_ref
<>::new_reference (from_tty
? Py_True
: Py_False
);
134 gdbpy_ref
<> result (PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
,
135 argobj
.get (), ttyobj
.get (),
139 gdbpy_handle_exception ();
142 /* Helper function for the Python command completers (both "pure"
143 completer and brkchar handler). This function takes COMMAND, TEXT
144 and WORD and tries to call the Python method for completion with
147 This function is usually called twice: once when we are figuring out
148 the break characters to be used, and another to perform the real
149 completion itself. The reason for this two step dance is that we
150 need to know the set of "brkchars" to use early on, before we
151 actually try to perform the completion. But if a Python command
152 supplies a "complete" method then we have to call that method
153 first: it may return as its result the kind of completion to
154 perform and that will in turn specify which brkchars to use. IOW,
155 we need the result of the "complete" method before we actually
156 perform the completion. The only situation when this function is
157 not called twice is when the user uses the "complete" command: in
158 this scenario, there is no call to determine the "brkchars".
160 Ideally, it would be nice to cache the result of the first call (to
161 determine the "brkchars") and return this value directly in the
162 second call (to perform the actual completion). However, due to
163 the peculiarity of the "complete" command mentioned above, it is
164 possible to put GDB in a bad state if you perform a TAB-completion
165 and then a "complete"-completion sequentially. Therefore, we just
166 recalculate everything twice for TAB-completions.
168 This function returns a reference to the PyObject representing the
169 Python method call. */
172 cmdpy_completer_helper (struct cmd_list_element
*command
,
173 const char *text
, const char *word
)
175 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
178 error (_("Invalid invocation of Python command object."));
179 if (!PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
181 /* If there is no complete method, don't error. */
185 gdbpy_ref
<> textobj (PyUnicode_Decode (text
, strlen (text
), host_charset (),
188 error (_("Could not convert argument to Python string."));
193 /* "brkchars" phase. */
194 wordobj
= gdbpy_ref
<>::new_reference (Py_None
);
198 wordobj
.reset (PyUnicode_Decode (word
, strlen (word
), host_charset (),
201 error (_("Could not convert argument to Python string."));
204 gdbpy_ref
<> resultobj (PyObject_CallMethodObjArgs ((PyObject
*) obj
,
207 wordobj
.get (), NULL
));
208 if (resultobj
== NULL
)
210 /* Just swallow errors here. */
217 /* Python function called to determine the break characters of a
218 certain completer. We are only interested in knowing if the
219 completer registered by the user will return one of the integer
220 codes (see COMPLETER_* symbols). */
223 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
224 completion_tracker
&tracker
,
225 const char *text
, const char *word
)
227 gdbpy_enter
enter_py (get_current_arch (), current_language
);
229 /* Calling our helper to obtain a reference to the PyObject of the Python
231 gdbpy_ref
<> resultobj
= cmdpy_completer_helper (command
, text
, word
);
233 /* Check if there was an error. */
234 if (resultobj
== NULL
)
237 if (PyInt_Check (resultobj
.get ()))
239 /* User code may also return one of the completion constants,
240 thus requesting that sort of completion. We are only
241 interested in this kind of return. */
244 if (!gdb_py_int_as_long (resultobj
.get (), &value
))
249 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
251 completer_handle_brkchars_ftype
*brkchars_fn
;
253 /* This is the core of this function. Depending on which
254 completer type the Python function returns, we have to
255 adjust the break characters accordingly. */
256 brkchars_fn
= (completer_handle_brkchars_func_for_completer
257 (completers
[value
].completer
));
258 brkchars_fn (command
, tracker
, text
, word
);
263 /* Called by gdb for command completion. */
266 cmdpy_completer (struct cmd_list_element
*command
,
267 completion_tracker
&tracker
,
268 const char *text
, const char *word
)
270 gdbpy_enter
enter_py (get_current_arch (), current_language
);
272 /* Calling our helper to obtain a reference to the PyObject of the Python
274 gdbpy_ref
<> resultobj
= cmdpy_completer_helper (command
, text
, word
);
276 /* If the result object of calling the Python function is NULL, it
277 means that there was an error. In this case, just give up. */
278 if (resultobj
== NULL
)
281 if (PyInt_Check (resultobj
.get ()))
283 /* User code may also return one of the completion constants,
284 thus requesting that sort of completion. */
287 if (! gdb_py_int_as_long (resultobj
.get (), &value
))
292 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
293 completers
[value
].completer (command
, tracker
, text
, word
);
297 gdbpy_ref
<> iter (PyObject_GetIter (resultobj
.get ()));
302 bool got_matches
= false;
305 gdbpy_ref
<> elt (PyIter_Next (iter
.get ()));
309 if (! gdbpy_is_string (elt
.get ()))
311 /* Skip problem elements. */
314 gdb::unique_xmalloc_ptr
<char>
315 item (python_string_to_host_string (elt
.get ()));
318 /* Skip problem elements. */
322 tracker
.add_completion (std::move (item
));
326 /* If we got some results, ignore problems. Otherwise, report
328 if (got_matches
&& PyErr_Occurred ())
333 /* Helper for cmdpy_init which locates the command list to use and
334 pulls out the command name.
336 NAME is the command name list. The final word in the list is the
337 name of the new command. All earlier words must be existing prefix
340 *BASE_LIST is set to the final prefix command's list of
343 START_LIST is the list in which the search starts.
345 This function returns the name of the new command. On error sets the Python
346 error and returns NULL. */
348 gdb::unique_xmalloc_ptr
<char>
349 gdbpy_parse_command_name (const char *name
,
350 struct cmd_list_element
***base_list
,
351 struct cmd_list_element
**start_list
)
353 struct cmd_list_element
*elt
;
354 int len
= strlen (name
);
356 const char *prefix_text2
;
358 /* Skip trailing whitespace. */
359 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
363 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
368 /* Find first character of the final word. */
369 for (; i
> 0 && valid_cmd_char_p (name
[i
- 1]); --i
)
372 gdb::unique_xmalloc_ptr
<char> result ((char *) xmalloc (lastchar
- i
+ 2));
373 memcpy (result
.get (), &name
[i
], lastchar
- i
+ 1);
374 result
.get ()[lastchar
- i
+ 1] = '\0';
376 /* Skip whitespace again. */
377 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
381 *base_list
= start_list
;
385 std::string
prefix_text (name
, i
+ 1);
387 prefix_text2
= prefix_text
.c_str ();
388 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, NULL
, 1);
389 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
391 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
392 prefix_text
.c_str ());
396 if (elt
->is_prefix ())
398 *base_list
= elt
->subcommands
;
402 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
403 prefix_text
.c_str ());
407 /* Object initializer; sets up gdb-side structures for command.
409 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
411 NAME is the name of the command. It may consist of multiple words,
412 in which case the final word is the name of the new command, and
413 earlier words must be prefix commands.
415 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
416 constants defined in the gdb module.
418 COMPLETER_CLASS is the kind of completer. If not given, the
419 "complete" method will be used. Otherwise, it should be one of the
420 COMPLETE_* constants defined in the gdb module.
422 If PREFIX is True, then this command is a prefix command.
424 The documentation for the command is taken from the doc string for
428 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
430 cmdpy_object
*obj
= (cmdpy_object
*) self
;
433 int completetype
= -1;
434 char *docstring
= NULL
;
435 struct cmd_list_element
**cmd_list
;
436 static const char *keywords
[] = { "name", "command_class", "completer_class",
438 PyObject
*is_prefix_obj
= NULL
;
439 bool is_prefix
= false;
443 /* Note: this is apparently not documented in Python. We return
444 0 for success, -1 for failure. */
445 PyErr_Format (PyExc_RuntimeError
,
446 _("Command object already initialized."));
450 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
451 keywords
, &name
, &cmdtype
,
452 &completetype
, &is_prefix_obj
))
455 if (cmdtype
!= no_class
&& cmdtype
!= class_run
456 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
457 && cmdtype
!= class_files
&& cmdtype
!= class_support
458 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
459 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
460 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
461 && cmdtype
!= class_tui
)
463 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
467 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
469 PyErr_Format (PyExc_RuntimeError
,
470 _("Invalid completion type argument."));
474 gdb::unique_xmalloc_ptr
<char> cmd_name
475 = gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
476 if (cmd_name
== nullptr)
479 if (is_prefix_obj
!= NULL
)
481 int cmp
= PyObject_IsTrue (is_prefix_obj
);
488 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
490 gdbpy_ref
<> ds_obj (PyObject_GetAttr (self
, gdbpy_doc_cst
));
492 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
494 docstring
= python_string_to_host_string (ds_obj
.get ()).release ();
495 if (docstring
== NULL
)
500 docstring
= xstrdup (_("This command is not documented."));
502 gdbpy_ref
<> self_ref
= gdbpy_ref
<>::new_reference (self
);
506 struct cmd_list_element
*cmd
;
512 /* If we have our own "invoke" method, then allow unknown
514 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
515 cmd
= add_prefix_cmd (cmd_name
.get (),
516 (enum command_class
) cmdtype
,
517 NULL
, docstring
, &obj
->sub_list
,
518 allow_unknown
, cmd_list
);
521 cmd
= add_cmd (cmd_name
.get (), (enum command_class
) cmdtype
,
522 docstring
, cmd_list
);
524 /* If successful, the above takes ownership of the name, since we set
525 name_allocated, so release it. */
528 /* There appears to be no API to set this. */
529 cmd
->func
= cmdpy_function
;
530 cmd
->destroyer
= cmdpy_destroyer
;
531 cmd
->doc_allocated
= 1;
532 cmd
->name_allocated
= 1;
535 set_cmd_context (cmd
, self_ref
.release ());
536 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
537 : completers
[completetype
].completer
));
538 if (completetype
== -1)
539 set_cmd_completer_handle_brkchars (cmd
,
540 cmdpy_completer_handle_brkchars
);
542 catch (const gdb_exception
&except
)
545 gdbpy_convert_exception (except
);
554 /* Initialize the 'commands' code. */
557 gdbpy_initialize_commands (void)
561 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
562 if (PyType_Ready (&cmdpy_object_type
) < 0)
565 /* Note: alias and user are special. */
566 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
567 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
568 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
569 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
570 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
571 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
573 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
574 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
575 class_breakpoint
) < 0
576 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
578 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
580 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
581 class_maintenance
) < 0
582 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0
583 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TUI", class_tui
) < 0)
586 for (i
= 0; i
< N_COMPLETERS
; ++i
)
588 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
592 if (gdb_pymodule_addobject (gdb_module
, "Command",
593 (PyObject
*) &cmdpy_object_type
) < 0)
596 invoke_cst
= PyString_FromString ("invoke");
597 if (invoke_cst
== NULL
)
599 complete_cst
= PyString_FromString ("complete");
600 if (complete_cst
== NULL
)
608 static PyMethodDef cmdpy_object_methods
[] =
610 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
611 "Prevent command repetition when user enters empty line." },
616 PyTypeObject cmdpy_object_type
=
618 PyVarObject_HEAD_INIT (NULL
, 0)
619 "gdb.Command", /*tp_name*/
620 sizeof (cmdpy_object
), /*tp_basicsize*/
629 0, /*tp_as_sequence*/
637 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
638 "GDB command object", /* tp_doc */
641 0, /* tp_richcompare */
642 0, /* tp_weaklistoffset */
645 cmdpy_object_methods
, /* tp_methods */
650 0, /* tp_descr_get */
651 0, /* tp_descr_set */
652 0, /* tp_dictoffset */
653 cmdpy_init
, /* tp_init */
659 /* Utility to build a buildargv-like result from ARGS.
660 This intentionally parses arguments the way libiberty/argv.c:buildargv
661 does. It splits up arguments in a reasonable way, and we want a standard
662 way of parsing arguments. Several gdb commands use buildargv to parse their
663 arguments. Plus we want to be able to write compatible python
664 implementations of gdb commands. */
667 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
671 if (!PyArg_ParseTuple (args
, "s", &input
))
674 gdbpy_ref
<> py_argv (PyList_New (0));
678 /* buildargv uses NULL to represent an empty argument list, but we can't use
679 that in Python. Instead, if ARGS is "" then return an empty list.
680 This undoes the NULL -> "" conversion that cmdpy_function does. */
684 gdb_argv
c_argv (input
);
686 for (char *arg
: c_argv
)
688 gdbpy_ref
<> argp (PyString_FromString (arg
));
691 || PyList_Append (py_argv
.get (), argp
.get ()) < 0)
696 return py_argv
.release ();