1 /* gdb commands implemented in Python
3 Copyright (C) 2008-2020 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 typedef struct cmdpy_object cmdpy_object
;
71 extern PyTypeObject cmdpy_object_type
72 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("cmdpy_object");
74 /* Constants used by this module. */
75 static PyObject
*invoke_cst
;
76 static PyObject
*complete_cst
;
80 /* Python function which wraps dont_repeat. */
82 cmdpy_dont_repeat (PyObject
*self
, PyObject
*args
)
90 /* Called if the gdb cmd_list_element is destroyed. */
93 cmdpy_destroyer (struct cmd_list_element
*self
, void *context
)
95 gdbpy_enter
enter_py (get_current_arch (), current_language
);
97 /* Release our hold on the command object. */
98 gdbpy_ref
<cmdpy_object
> cmd ((cmdpy_object
*) context
);
101 /* We may have allocated the prefix name. */
102 xfree ((char *) self
->prefixname
);
105 /* Called by gdb to invoke the command. */
108 cmdpy_function (struct cmd_list_element
*command
,
109 const char *args
, int from_tty
)
111 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
113 gdbpy_enter
enter_py (get_current_arch (), current_language
);
116 error (_("Invalid invocation of Python command object."));
117 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
119 if (obj
->command
->prefixname
)
121 /* A prefix command does not need an invoke method. */
124 error (_("Python command object missing 'invoke' method."));
129 gdbpy_ref
<> argobj (PyUnicode_Decode (args
, strlen (args
), host_charset (),
133 gdbpy_print_stack ();
134 error (_("Could not convert arguments to Python string."));
138 = gdbpy_ref
<>::new_reference (from_tty
? Py_True
: Py_False
);
139 gdbpy_ref
<> result (PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
,
140 argobj
.get (), ttyobj
.get (),
144 gdbpy_handle_exception ();
147 /* Helper function for the Python command completers (both "pure"
148 completer and brkchar handler). This function takes COMMAND, TEXT
149 and WORD and tries to call the Python method for completion with
152 This function is usually called twice: once when we are figuring out
153 the break characters to be used, and another to perform the real
154 completion itself. The reason for this two step dance is that we
155 need to know the set of "brkchars" to use early on, before we
156 actually try to perform the completion. But if a Python command
157 supplies a "complete" method then we have to call that method
158 first: it may return as its result the kind of completion to
159 perform and that will in turn specify which brkchars to use. IOW,
160 we need the result of the "complete" method before we actually
161 perform the completion. The only situation when this function is
162 not called twice is when the user uses the "complete" command: in
163 this scenario, there is no call to determine the "brkchars".
165 Ideally, it would be nice to cache the result of the first call (to
166 determine the "brkchars") and return this value directly in the
167 second call (to perform the actual completion). However, due to
168 the peculiarity of the "complete" command mentioned above, it is
169 possible to put GDB in a bad state if you perform a TAB-completion
170 and then a "complete"-completion sequentially. Therefore, we just
171 recalculate everything twice for TAB-completions.
173 This function returns a reference to the PyObject representing the
174 Python method call. */
177 cmdpy_completer_helper (struct cmd_list_element
*command
,
178 const char *text
, const char *word
)
180 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
183 error (_("Invalid invocation of Python command object."));
184 if (!PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
186 /* If there is no complete method, don't error. */
190 gdbpy_ref
<> textobj (PyUnicode_Decode (text
, strlen (text
), host_charset (),
193 error (_("Could not convert argument to Python string."));
198 /* "brkchars" phase. */
199 wordobj
= gdbpy_ref
<>::new_reference (Py_None
);
203 wordobj
.reset (PyUnicode_Decode (word
, strlen (word
), host_charset (),
206 error (_("Could not convert argument to Python string."));
209 gdbpy_ref
<> resultobj (PyObject_CallMethodObjArgs ((PyObject
*) obj
,
212 wordobj
.get (), NULL
));
213 if (resultobj
== NULL
)
215 /* Just swallow errors here. */
222 /* Python function called to determine the break characters of a
223 certain completer. We are only interested in knowing if the
224 completer registered by the user will return one of the integer
225 codes (see COMPLETER_* symbols). */
228 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
229 completion_tracker
&tracker
,
230 const char *text
, const char *word
)
232 gdbpy_enter
enter_py (get_current_arch (), current_language
);
234 /* Calling our helper to obtain a reference to the PyObject of the Python
236 gdbpy_ref
<> resultobj
= cmdpy_completer_helper (command
, text
, word
);
238 /* Check if there was an error. */
239 if (resultobj
== NULL
)
242 if (PyInt_Check (resultobj
.get ()))
244 /* User code may also return one of the completion constants,
245 thus requesting that sort of completion. We are only
246 interested in this kind of return. */
249 if (!gdb_py_int_as_long (resultobj
.get (), &value
))
254 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
256 completer_handle_brkchars_ftype
*brkchars_fn
;
258 /* This is the core of this function. Depending on which
259 completer type the Python function returns, we have to
260 adjust the break characters accordingly. */
261 brkchars_fn
= (completer_handle_brkchars_func_for_completer
262 (completers
[value
].completer
));
263 brkchars_fn (command
, tracker
, text
, word
);
268 /* Called by gdb for command completion. */
271 cmdpy_completer (struct cmd_list_element
*command
,
272 completion_tracker
&tracker
,
273 const char *text
, const char *word
)
275 gdbpy_enter
enter_py (get_current_arch (), current_language
);
277 /* Calling our helper to obtain a reference to the PyObject of the Python
279 gdbpy_ref
<> resultobj
= cmdpy_completer_helper (command
, text
, word
);
281 /* If the result object of calling the Python function is NULL, it
282 means that there was an error. In this case, just give up. */
283 if (resultobj
== NULL
)
286 if (PyInt_Check (resultobj
.get ()))
288 /* User code may also return one of the completion constants,
289 thus requesting that sort of completion. */
292 if (! gdb_py_int_as_long (resultobj
.get (), &value
))
297 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
298 completers
[value
].completer (command
, tracker
, text
, word
);
302 gdbpy_ref
<> iter (PyObject_GetIter (resultobj
.get ()));
307 bool got_matches
= false;
310 gdbpy_ref
<> elt (PyIter_Next (iter
.get ()));
314 if (! gdbpy_is_string (elt
.get ()))
316 /* Skip problem elements. */
319 gdb::unique_xmalloc_ptr
<char>
320 item (python_string_to_host_string (elt
.get ()));
323 /* Skip problem elements. */
327 tracker
.add_completion (std::move (item
));
331 /* If we got some results, ignore problems. Otherwise, report
333 if (got_matches
&& PyErr_Occurred ())
338 /* Helper for cmdpy_init which locates the command list to use and
339 pulls out the command name.
341 NAME is the command name list. The final word in the list is the
342 name of the new command. All earlier words must be existing prefix
345 *BASE_LIST is set to the final prefix command's list of
348 START_LIST is the list in which the search starts.
350 This function returns the xmalloc()d name of the new command. On
351 error sets the Python error and returns NULL. */
354 gdbpy_parse_command_name (const char *name
,
355 struct cmd_list_element
***base_list
,
356 struct cmd_list_element
**start_list
)
358 struct cmd_list_element
*elt
;
359 int len
= strlen (name
);
361 const char *prefix_text2
;
364 /* Skip trailing whitespace. */
365 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
369 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
374 /* Find first character of the final word. */
375 for (; i
> 0 && valid_cmd_char_p (name
[i
- 1]); --i
)
377 result
= (char *) xmalloc (lastchar
- i
+ 2);
378 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
379 result
[lastchar
- i
+ 1] = '\0';
381 /* Skip whitespace again. */
382 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
386 *base_list
= start_list
;
390 std::string
prefix_text (name
, i
+ 1);
392 prefix_text2
= prefix_text
.c_str ();
393 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, NULL
, 1);
394 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
396 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
397 prefix_text
.c_str ());
404 *base_list
= elt
->prefixlist
;
408 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
409 prefix_text
.c_str ());
414 /* Object initializer; sets up gdb-side structures for command.
416 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
418 NAME is the name of the command. It may consist of multiple words,
419 in which case the final word is the name of the new command, and
420 earlier words must be prefix commands.
422 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
423 constants defined in the gdb module.
425 COMPLETER_CLASS is the kind of completer. If not given, the
426 "complete" method will be used. Otherwise, it should be one of the
427 COMPLETE_* constants defined in the gdb module.
429 If PREFIX is True, then this command is a prefix command.
431 The documentation for the command is taken from the doc string for
435 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
437 cmdpy_object
*obj
= (cmdpy_object
*) self
;
440 int completetype
= -1;
441 char *docstring
= NULL
;
442 struct cmd_list_element
**cmd_list
;
443 char *cmd_name
, *pfx_name
;
444 static const char *keywords
[] = { "name", "command_class", "completer_class",
446 PyObject
*is_prefix
= NULL
;
451 /* Note: this is apparently not documented in Python. We return
452 0 for success, -1 for failure. */
453 PyErr_Format (PyExc_RuntimeError
,
454 _("Command object already initialized."));
458 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
459 keywords
, &name
, &cmdtype
,
460 &completetype
, &is_prefix
))
463 if (cmdtype
!= no_class
&& cmdtype
!= class_run
464 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
465 && cmdtype
!= class_files
&& cmdtype
!= class_support
466 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
467 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
468 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
469 && cmdtype
!= class_tui
)
471 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
475 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
477 PyErr_Format (PyExc_RuntimeError
,
478 _("Invalid completion type argument."));
482 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
487 if (is_prefix
!= NULL
)
489 cmp
= PyObject_IsTrue (is_prefix
);
494 /* Make a normalized form of the command name. */
495 pfx_name
= (char *) xmalloc (strlen (name
) + 2);
501 /* Skip whitespace. */
502 while (name
[i
] == ' ' || name
[i
] == '\t')
504 /* Copy non-whitespace characters. */
505 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
506 pfx_name
[out
++] = name
[i
++];
507 /* Add a single space after each word -- including the final
509 pfx_name
[out
++] = ' ';
511 pfx_name
[out
] = '\0';
519 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
521 gdbpy_ref
<> ds_obj (PyObject_GetAttr (self
, gdbpy_doc_cst
));
523 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
525 docstring
= python_string_to_host_string (ds_obj
.get ()).release ();
526 if (docstring
== NULL
)
535 docstring
= xstrdup (_("This command is not documented."));
537 gdbpy_ref
<> self_ref
= gdbpy_ref
<>::new_reference (self
);
541 struct cmd_list_element
*cmd
;
547 /* If we have our own "invoke" method, then allow unknown
549 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
550 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
551 NULL
, docstring
, &obj
->sub_list
,
552 pfx_name
, allow_unknown
, cmd_list
);
555 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
,
556 docstring
, cmd_list
);
558 /* There appears to be no API to set this. */
559 cmd
->func
= cmdpy_function
;
560 cmd
->destroyer
= cmdpy_destroyer
;
561 cmd
->doc_allocated
= 1;
562 cmd
->name_allocated
= 1;
565 set_cmd_context (cmd
, self_ref
.release ());
566 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
567 : completers
[completetype
].completer
));
568 if (completetype
== -1)
569 set_cmd_completer_handle_brkchars (cmd
,
570 cmdpy_completer_handle_brkchars
);
572 catch (const gdb_exception
&except
)
577 gdbpy_convert_exception (except
);
586 /* Initialize the 'commands' code. */
589 gdbpy_initialize_commands (void)
593 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
594 if (PyType_Ready (&cmdpy_object_type
) < 0)
597 /* Note: alias and user are special. */
598 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
599 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
600 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
601 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
602 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
603 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
605 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
606 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
607 class_breakpoint
) < 0
608 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
610 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
612 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
613 class_maintenance
) < 0
614 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0
615 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TUI", class_tui
) < 0)
618 for (i
= 0; i
< N_COMPLETERS
; ++i
)
620 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
624 if (gdb_pymodule_addobject (gdb_module
, "Command",
625 (PyObject
*) &cmdpy_object_type
) < 0)
628 invoke_cst
= PyString_FromString ("invoke");
629 if (invoke_cst
== NULL
)
631 complete_cst
= PyString_FromString ("complete");
632 if (complete_cst
== NULL
)
640 static PyMethodDef cmdpy_object_methods
[] =
642 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
643 "Prevent command repetition when user enters empty line." },
648 PyTypeObject cmdpy_object_type
=
650 PyVarObject_HEAD_INIT (NULL
, 0)
651 "gdb.Command", /*tp_name*/
652 sizeof (cmdpy_object
), /*tp_basicsize*/
661 0, /*tp_as_sequence*/
669 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
670 "GDB command object", /* tp_doc */
673 0, /* tp_richcompare */
674 0, /* tp_weaklistoffset */
677 cmdpy_object_methods
, /* tp_methods */
682 0, /* tp_descr_get */
683 0, /* tp_descr_set */
684 0, /* tp_dictoffset */
685 cmdpy_init
, /* tp_init */
691 /* Utility to build a buildargv-like result from ARGS.
692 This intentionally parses arguments the way libiberty/argv.c:buildargv
693 does. It splits up arguments in a reasonable way, and we want a standard
694 way of parsing arguments. Several gdb commands use buildargv to parse their
695 arguments. Plus we want to be able to write compatible python
696 implementations of gdb commands. */
699 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
703 if (!PyArg_ParseTuple (args
, "s", &input
))
706 gdbpy_ref
<> py_argv (PyList_New (0));
710 /* buildargv uses NULL to represent an empty argument list, but we can't use
711 that in Python. Instead, if ARGS is "" then return an empty list.
712 This undoes the NULL -> "" conversion that cmdpy_function does. */
716 gdb_argv
c_argv (input
);
718 for (char *arg
: c_argv
)
720 gdbpy_ref
<> argp (PyString_FromString (arg
));
723 || PyList_Append (py_argv
.get (), argp
.get ()) < 0)
728 return py_argv
.release ();