1 /* gdb commands 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/>. */
22 #include "arch-utils.h"
24 #include "python-internal.h"
27 #include "cli/cli-decode.h"
28 #include "completer.h"
32 /* Struct representing built-in completion types. */
33 struct cmdpy_completer
35 /* Python symbol name. */
37 /* Completion function. */
38 completer_ftype
*completer
;
41 static const struct cmdpy_completer completers
[] =
43 { "COMPLETE_NONE", noop_completer
},
44 { "COMPLETE_FILENAME", filename_completer
},
45 { "COMPLETE_LOCATION", location_completer
},
46 { "COMPLETE_COMMAND", command_completer
},
47 { "COMPLETE_SYMBOL", symbol_completer
},
48 { "COMPLETE_EXPRESSION", expression_completer
},
51 #define N_COMPLETERS (sizeof (completers) / sizeof (completers[0]))
53 /* A gdb command. For the time being only ordinary commands (not
54 set/show commands) are allowed. */
59 /* The corresponding gdb command object, or NULL if the command is
60 no longer installed. */
61 struct cmd_list_element
*command
;
63 /* A prefix command requires storage for a list of its sub-commands.
64 A pointer to this is passed to add_prefix_command, and to add_cmd
65 for sub-commands of that prefix. If this Command is not a prefix
66 command, then this field is unused. */
67 struct cmd_list_element
*sub_list
;
70 typedef struct cmdpy_object cmdpy_object
;
72 extern PyTypeObject cmdpy_object_type
73 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("cmdpy_object");
75 /* Constants used by this module. */
76 static PyObject
*invoke_cst
;
77 static PyObject
*complete_cst
;
81 /* Python function which wraps dont_repeat. */
83 cmdpy_dont_repeat (PyObject
*self
, PyObject
*args
)
91 /* Called if the gdb cmd_list_element is destroyed. */
94 cmdpy_destroyer (struct cmd_list_element
*self
, void *context
)
96 gdbpy_enter
enter_py (get_current_arch (), current_language
);
98 /* Release our hold on the command object. */
99 gdbpy_ref
<cmdpy_object
> cmd ((cmdpy_object
*) context
);
102 /* We allocated the name, doc string, and perhaps the prefix
104 xfree ((char *) self
->name
);
105 xfree ((char *) self
->doc
);
106 xfree ((char *) self
->prefixname
);
109 /* Called by gdb to invoke the command. */
112 cmdpy_function (struct cmd_list_element
*command
,
113 const char *args
, int from_tty
)
115 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
117 gdbpy_enter
enter_py (get_current_arch (), current_language
);
120 error (_("Invalid invocation of Python command object."));
121 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
123 if (obj
->command
->prefixname
)
125 /* A prefix command does not need an invoke method. */
128 error (_("Python command object missing 'invoke' method."));
133 gdbpy_ref
<> argobj (PyUnicode_Decode (args
, strlen (args
), host_charset (),
137 gdbpy_print_stack ();
138 error (_("Could not convert arguments to Python string."));
142 = gdbpy_ref
<>::new_reference (from_tty
? Py_True
: Py_False
);
143 gdbpy_ref
<> result (PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
,
144 argobj
.get (), ttyobj
.get (),
148 gdbpy_handle_exception ();
151 /* Helper function for the Python command completers (both "pure"
152 completer and brkchar handler). This function takes COMMAND, TEXT
153 and WORD and tries to call the Python method for completion with
156 This function is usually called twice: once when we are figuring out
157 the break characters to be used, and another to perform the real
158 completion itself. The reason for this two step dance is that we
159 need to know the set of "brkchars" to use early on, before we
160 actually try to perform the completion. But if a Python command
161 supplies a "complete" method then we have to call that method
162 first: it may return as its result the kind of completion to
163 perform and that will in turn specify which brkchars to use. IOW,
164 we need the result of the "complete" method before we actually
165 perform the completion. The only situation when this function is
166 not called twice is when the user uses the "complete" command: in
167 this scenario, there is no call to determine the "brkchars".
169 Ideally, it would be nice to cache the result of the first call (to
170 determine the "brkchars") and return this value directly in the
171 second call (to perform the actual completion). However, due to
172 the peculiarity of the "complete" command mentioned above, it is
173 possible to put GDB in a bad state if you perform a TAB-completion
174 and then a "complete"-completion sequentially. Therefore, we just
175 recalculate everything twice for TAB-completions.
177 This function returns a reference to the PyObject representing the
178 Python method call. */
181 cmdpy_completer_helper (struct cmd_list_element
*command
,
182 const char *text
, const char *word
)
184 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
187 error (_("Invalid invocation of Python command object."));
188 if (!PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
190 /* If there is no complete method, don't error. */
194 gdbpy_ref
<> textobj (PyUnicode_Decode (text
, strlen (text
), host_charset (),
197 error (_("Could not convert argument to Python string."));
202 /* "brkchars" phase. */
203 wordobj
= gdbpy_ref
<>::new_reference (Py_None
);
207 wordobj
.reset (PyUnicode_Decode (word
, strlen (word
), host_charset (),
210 error (_("Could not convert argument to Python string."));
213 gdbpy_ref
<> resultobj (PyObject_CallMethodObjArgs ((PyObject
*) obj
,
216 wordobj
.get (), NULL
));
217 if (resultobj
== NULL
)
219 /* Just swallow errors here. */
226 /* Python function called to determine the break characters of a
227 certain completer. We are only interested in knowing if the
228 completer registered by the user will return one of the integer
229 codes (see COMPLETER_* symbols). */
232 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
233 completion_tracker
&tracker
,
234 const char *text
, const char *word
)
236 gdbpy_enter
enter_py (get_current_arch (), current_language
);
238 /* Calling our helper to obtain a reference to the PyObject of the Python
240 gdbpy_ref
<> resultobj
= cmdpy_completer_helper (command
, text
, word
);
242 /* Check if there was an error. */
243 if (resultobj
== NULL
)
246 if (PyInt_Check (resultobj
.get ()))
248 /* User code may also return one of the completion constants,
249 thus requesting that sort of completion. We are only
250 interested in this kind of return. */
253 if (!gdb_py_int_as_long (resultobj
.get (), &value
))
258 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
260 completer_handle_brkchars_ftype
*brkchars_fn
;
262 /* This is the core of this function. Depending on which
263 completer type the Python function returns, we have to
264 adjust the break characters accordingly. */
265 brkchars_fn
= (completer_handle_brkchars_func_for_completer
266 (completers
[value
].completer
));
267 brkchars_fn (command
, tracker
, text
, word
);
272 /* Called by gdb for command completion. */
275 cmdpy_completer (struct cmd_list_element
*command
,
276 completion_tracker
&tracker
,
277 const char *text
, const char *word
)
279 gdbpy_enter
enter_py (get_current_arch (), current_language
);
281 /* Calling our helper to obtain a reference to the PyObject of the Python
283 gdbpy_ref
<> resultobj
= cmdpy_completer_helper (command
, text
, word
);
285 /* If the result object of calling the Python function is NULL, it
286 means that there was an error. In this case, just give up. */
287 if (resultobj
== NULL
)
290 if (PyInt_Check (resultobj
.get ()))
292 /* User code may also return one of the completion constants,
293 thus requesting that sort of completion. */
296 if (! gdb_py_int_as_long (resultobj
.get (), &value
))
301 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
302 completers
[value
].completer (command
, tracker
, text
, word
);
306 gdbpy_ref
<> iter (PyObject_GetIter (resultobj
.get ()));
311 bool got_matches
= false;
314 gdbpy_ref
<> elt (PyIter_Next (iter
.get ()));
318 if (! gdbpy_is_string (elt
.get ()))
320 /* Skip problem elements. */
323 gdb::unique_xmalloc_ptr
<char>
324 item (python_string_to_host_string (elt
.get ()));
327 /* Skip problem elements. */
331 tracker
.add_completion (std::move (item
));
335 /* If we got some results, ignore problems. Otherwise, report
337 if (got_matches
&& PyErr_Occurred ())
342 /* Helper for cmdpy_init which locates the command list to use and
343 pulls out the command name.
345 NAME is the command name list. The final word in the list is the
346 name of the new command. All earlier words must be existing prefix
349 *BASE_LIST is set to the final prefix command's list of
352 START_LIST is the list in which the search starts.
354 This function returns the xmalloc()d name of the new command. On
355 error sets the Python error and returns NULL. */
358 gdbpy_parse_command_name (const char *name
,
359 struct cmd_list_element
***base_list
,
360 struct cmd_list_element
**start_list
)
362 struct cmd_list_element
*elt
;
363 int len
= strlen (name
);
366 const char *prefix_text2
;
369 /* Skip trailing whitespace. */
370 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
374 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
379 /* Find first character of the final word. */
380 for (; i
> 0 && (isalnum (name
[i
- 1])
381 || name
[i
- 1] == '-'
382 || name
[i
- 1] == '_');
385 result
= (char *) xmalloc (lastchar
- i
+ 2);
386 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
387 result
[lastchar
- i
+ 1] = '\0';
389 /* Skip whitespace again. */
390 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
394 *base_list
= start_list
;
398 prefix_text
= (char *) xmalloc (i
+ 2);
399 memcpy (prefix_text
, name
, i
+ 1);
400 prefix_text
[i
+ 1] = '\0';
402 prefix_text2
= prefix_text
;
403 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
404 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
406 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
416 *base_list
= elt
->prefixlist
;
420 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
427 /* Object initializer; sets up gdb-side structures for command.
429 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
431 NAME is the name of the command. It may consist of multiple words,
432 in which case the final word is the name of the new command, and
433 earlier words must be prefix commands.
435 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
436 constants defined in the gdb module.
438 COMPLETER_CLASS is the kind of completer. If not given, the
439 "complete" method will be used. Otherwise, it should be one of the
440 COMPLETE_* constants defined in the gdb module.
442 If PREFIX is True, then this command is a prefix command.
444 The documentation for the command is taken from the doc string for
448 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
450 cmdpy_object
*obj
= (cmdpy_object
*) self
;
453 int completetype
= -1;
454 char *docstring
= NULL
;
455 struct cmd_list_element
**cmd_list
;
456 char *cmd_name
, *pfx_name
;
457 static const char *keywords
[] = { "name", "command_class", "completer_class",
459 PyObject
*is_prefix
= NULL
;
464 /* Note: this is apparently not documented in Python. We return
465 0 for success, -1 for failure. */
466 PyErr_Format (PyExc_RuntimeError
,
467 _("Command object already initialized."));
471 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
472 keywords
, &name
, &cmdtype
,
473 &completetype
, &is_prefix
))
476 if (cmdtype
!= no_class
&& cmdtype
!= class_run
477 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
478 && cmdtype
!= class_files
&& cmdtype
!= class_support
479 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
480 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
481 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
483 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
487 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
489 PyErr_Format (PyExc_RuntimeError
,
490 _("Invalid completion type argument."));
494 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
499 if (is_prefix
!= NULL
)
501 cmp
= PyObject_IsTrue (is_prefix
);
506 /* Make a normalized form of the command name. */
507 pfx_name
= (char *) xmalloc (strlen (name
) + 2);
513 /* Skip whitespace. */
514 while (name
[i
] == ' ' || name
[i
] == '\t')
516 /* Copy non-whitespace characters. */
517 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
518 pfx_name
[out
++] = name
[i
++];
519 /* Add a single space after each word -- including the final
521 pfx_name
[out
++] = ' ';
523 pfx_name
[out
] = '\0';
531 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
533 gdbpy_ref
<> ds_obj (PyObject_GetAttr (self
, gdbpy_doc_cst
));
535 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
537 docstring
= python_string_to_host_string (ds_obj
.get ()).release ();
538 if (docstring
== NULL
)
547 docstring
= xstrdup (_("This command is not documented."));
553 struct cmd_list_element
*cmd
;
559 /* If we have our own "invoke" method, then allow unknown
561 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
562 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
563 NULL
, docstring
, &obj
->sub_list
,
564 pfx_name
, allow_unknown
, cmd_list
);
567 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
,
568 docstring
, cmd_list
);
570 /* There appears to be no API to set this. */
571 cmd
->func
= cmdpy_function
;
572 cmd
->destroyer
= cmdpy_destroyer
;
575 set_cmd_context (cmd
, self
);
576 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
577 : completers
[completetype
].completer
));
578 if (completetype
== -1)
579 set_cmd_completer_handle_brkchars (cmd
,
580 cmdpy_completer_handle_brkchars
);
582 CATCH (except
, RETURN_MASK_ALL
)
588 PyErr_Format (except
.reason
== RETURN_QUIT
589 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
590 "%s", except
.message
);
600 /* Initialize the 'commands' code. */
603 gdbpy_initialize_commands (void)
607 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
608 if (PyType_Ready (&cmdpy_object_type
) < 0)
611 /* Note: alias and user are special; pseudo appears to be unused,
612 and there is no reason to expose tui, I think. */
613 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
614 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
615 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
616 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
617 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
618 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
620 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
621 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
622 class_breakpoint
) < 0
623 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
625 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
627 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
628 class_maintenance
) < 0
629 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
632 for (i
= 0; i
< N_COMPLETERS
; ++i
)
634 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
638 if (gdb_pymodule_addobject (gdb_module
, "Command",
639 (PyObject
*) &cmdpy_object_type
) < 0)
642 invoke_cst
= PyString_FromString ("invoke");
643 if (invoke_cst
== NULL
)
645 complete_cst
= PyString_FromString ("complete");
646 if (complete_cst
== NULL
)
654 static PyMethodDef cmdpy_object_methods
[] =
656 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
657 "Prevent command repetition when user enters empty line." },
662 PyTypeObject cmdpy_object_type
=
664 PyVarObject_HEAD_INIT (NULL
, 0)
665 "gdb.Command", /*tp_name*/
666 sizeof (cmdpy_object
), /*tp_basicsize*/
675 0, /*tp_as_sequence*/
683 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
684 "GDB command object", /* tp_doc */
687 0, /* tp_richcompare */
688 0, /* tp_weaklistoffset */
691 cmdpy_object_methods
, /* tp_methods */
696 0, /* tp_descr_get */
697 0, /* tp_descr_set */
698 0, /* tp_dictoffset */
699 cmdpy_init
, /* tp_init */
705 /* Utility to build a buildargv-like result from ARGS.
706 This intentionally parses arguments the way libiberty/argv.c:buildargv
707 does. It splits up arguments in a reasonable way, and we want a standard
708 way of parsing arguments. Several gdb commands use buildargv to parse their
709 arguments. Plus we want to be able to write compatible python
710 implementations of gdb commands. */
713 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
717 if (!PyArg_ParseTuple (args
, "s", &input
))
720 gdbpy_ref
<> py_argv (PyList_New (0));
724 /* buildargv uses NULL to represent an empty argument list, but we can't use
725 that in Python. Instead, if ARGS is "" then return an empty list.
726 This undoes the NULL -> "" conversion that cmdpy_function does. */
730 gdb_argv
c_argv (input
);
732 for (char *arg
: c_argv
)
734 gdbpy_ref
<> argp (PyString_FromString (arg
));
737 || PyList_Append (py_argv
.get (), argp
.get ()) < 0)
742 return py_argv
.release ();