1 /* gdb commands implemented in Python
3 Copyright (C) 2008-2019 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 allocated the name and perhaps the prefix name. */
102 xfree ((char *) self
->name
);
103 xfree ((char *) self
->prefixname
);
106 /* Called by gdb to invoke the command. */
109 cmdpy_function (struct cmd_list_element
*command
,
110 const char *args
, int from_tty
)
112 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
114 gdbpy_enter
enter_py (get_current_arch (), current_language
);
117 error (_("Invalid invocation of Python command object."));
118 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
120 if (obj
->command
->prefixname
)
122 /* A prefix command does not need an invoke method. */
125 error (_("Python command object missing 'invoke' method."));
130 gdbpy_ref
<> argobj (PyUnicode_Decode (args
, strlen (args
), host_charset (),
134 gdbpy_print_stack ();
135 error (_("Could not convert arguments to Python string."));
139 = gdbpy_ref
<>::new_reference (from_tty
? Py_True
: Py_False
);
140 gdbpy_ref
<> result (PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
,
141 argobj
.get (), ttyobj
.get (),
145 gdbpy_handle_exception ();
148 /* Helper function for the Python command completers (both "pure"
149 completer and brkchar handler). This function takes COMMAND, TEXT
150 and WORD and tries to call the Python method for completion with
153 This function is usually called twice: once when we are figuring out
154 the break characters to be used, and another to perform the real
155 completion itself. The reason for this two step dance is that we
156 need to know the set of "brkchars" to use early on, before we
157 actually try to perform the completion. But if a Python command
158 supplies a "complete" method then we have to call that method
159 first: it may return as its result the kind of completion to
160 perform and that will in turn specify which brkchars to use. IOW,
161 we need the result of the "complete" method before we actually
162 perform the completion. The only situation when this function is
163 not called twice is when the user uses the "complete" command: in
164 this scenario, there is no call to determine the "brkchars".
166 Ideally, it would be nice to cache the result of the first call (to
167 determine the "brkchars") and return this value directly in the
168 second call (to perform the actual completion). However, due to
169 the peculiarity of the "complete" command mentioned above, it is
170 possible to put GDB in a bad state if you perform a TAB-completion
171 and then a "complete"-completion sequentially. Therefore, we just
172 recalculate everything twice for TAB-completions.
174 This function returns a reference to the PyObject representing the
175 Python method call. */
178 cmdpy_completer_helper (struct cmd_list_element
*command
,
179 const char *text
, const char *word
)
181 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
184 error (_("Invalid invocation of Python command object."));
185 if (!PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
187 /* If there is no complete method, don't error. */
191 gdbpy_ref
<> textobj (PyUnicode_Decode (text
, strlen (text
), host_charset (),
194 error (_("Could not convert argument to Python string."));
199 /* "brkchars" phase. */
200 wordobj
= gdbpy_ref
<>::new_reference (Py_None
);
204 wordobj
.reset (PyUnicode_Decode (word
, strlen (word
), host_charset (),
207 error (_("Could not convert argument to Python string."));
210 gdbpy_ref
<> resultobj (PyObject_CallMethodObjArgs ((PyObject
*) obj
,
213 wordobj
.get (), NULL
));
214 if (resultobj
== NULL
)
216 /* Just swallow errors here. */
223 /* Python function called to determine the break characters of a
224 certain completer. We are only interested in knowing if the
225 completer registered by the user will return one of the integer
226 codes (see COMPLETER_* symbols). */
229 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
230 completion_tracker
&tracker
,
231 const char *text
, const char *word
)
233 gdbpy_enter
enter_py (get_current_arch (), current_language
);
235 /* Calling our helper to obtain a reference to the PyObject of the Python
237 gdbpy_ref
<> resultobj
= cmdpy_completer_helper (command
, text
, word
);
239 /* Check if there was an error. */
240 if (resultobj
== NULL
)
243 if (PyInt_Check (resultobj
.get ()))
245 /* User code may also return one of the completion constants,
246 thus requesting that sort of completion. We are only
247 interested in this kind of return. */
250 if (!gdb_py_int_as_long (resultobj
.get (), &value
))
255 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
257 completer_handle_brkchars_ftype
*brkchars_fn
;
259 /* This is the core of this function. Depending on which
260 completer type the Python function returns, we have to
261 adjust the break characters accordingly. */
262 brkchars_fn
= (completer_handle_brkchars_func_for_completer
263 (completers
[value
].completer
));
264 brkchars_fn (command
, tracker
, text
, word
);
269 /* Called by gdb for command completion. */
272 cmdpy_completer (struct cmd_list_element
*command
,
273 completion_tracker
&tracker
,
274 const char *text
, const char *word
)
276 gdbpy_enter
enter_py (get_current_arch (), current_language
);
278 /* Calling our helper to obtain a reference to the PyObject of the Python
280 gdbpy_ref
<> resultobj
= cmdpy_completer_helper (command
, text
, word
);
282 /* If the result object of calling the Python function is NULL, it
283 means that there was an error. In this case, just give up. */
284 if (resultobj
== NULL
)
287 if (PyInt_Check (resultobj
.get ()))
289 /* User code may also return one of the completion constants,
290 thus requesting that sort of completion. */
293 if (! gdb_py_int_as_long (resultobj
.get (), &value
))
298 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
299 completers
[value
].completer (command
, tracker
, text
, word
);
303 gdbpy_ref
<> iter (PyObject_GetIter (resultobj
.get ()));
308 bool got_matches
= false;
311 gdbpy_ref
<> elt (PyIter_Next (iter
.get ()));
315 if (! gdbpy_is_string (elt
.get ()))
317 /* Skip problem elements. */
320 gdb::unique_xmalloc_ptr
<char>
321 item (python_string_to_host_string (elt
.get ()));
324 /* Skip problem elements. */
328 tracker
.add_completion (std::move (item
));
332 /* If we got some results, ignore problems. Otherwise, report
334 if (got_matches
&& PyErr_Occurred ())
339 /* Helper for cmdpy_init which locates the command list to use and
340 pulls out the command name.
342 NAME is the command name list. The final word in the list is the
343 name of the new command. All earlier words must be existing prefix
346 *BASE_LIST is set to the final prefix command's list of
349 START_LIST is the list in which the search starts.
351 This function returns the xmalloc()d name of the new command. On
352 error sets the Python error and returns NULL. */
355 gdbpy_parse_command_name (const char *name
,
356 struct cmd_list_element
***base_list
,
357 struct cmd_list_element
**start_list
)
359 struct cmd_list_element
*elt
;
360 int len
= strlen (name
);
362 const char *prefix_text2
;
365 /* Skip trailing whitespace. */
366 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
370 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
375 /* Find first character of the final word. */
376 for (; i
> 0 && (isalnum (name
[i
- 1])
377 || name
[i
- 1] == '-'
378 || name
[i
- 1] == '_');
381 result
= (char *) xmalloc (lastchar
- i
+ 2);
382 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
383 result
[lastchar
- i
+ 1] = '\0';
385 /* Skip whitespace again. */
386 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
390 *base_list
= start_list
;
394 std::string
prefix_text (name
, i
+ 1);
396 prefix_text2
= prefix_text
.c_str ();
397 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
398 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
400 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
401 prefix_text
.c_str ());
408 *base_list
= elt
->prefixlist
;
412 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
413 prefix_text
.c_str ());
418 /* Object initializer; sets up gdb-side structures for command.
420 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
422 NAME is the name of the command. It may consist of multiple words,
423 in which case the final word is the name of the new command, and
424 earlier words must be prefix commands.
426 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
427 constants defined in the gdb module.
429 COMPLETER_CLASS is the kind of completer. If not given, the
430 "complete" method will be used. Otherwise, it should be one of the
431 COMPLETE_* constants defined in the gdb module.
433 If PREFIX is True, then this command is a prefix command.
435 The documentation for the command is taken from the doc string for
439 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
441 cmdpy_object
*obj
= (cmdpy_object
*) self
;
444 int completetype
= -1;
445 char *docstring
= NULL
;
446 struct cmd_list_element
**cmd_list
;
447 char *cmd_name
, *pfx_name
;
448 static const char *keywords
[] = { "name", "command_class", "completer_class",
450 PyObject
*is_prefix
= NULL
;
455 /* Note: this is apparently not documented in Python. We return
456 0 for success, -1 for failure. */
457 PyErr_Format (PyExc_RuntimeError
,
458 _("Command object already initialized."));
462 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
463 keywords
, &name
, &cmdtype
,
464 &completetype
, &is_prefix
))
467 if (cmdtype
!= no_class
&& cmdtype
!= class_run
468 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
469 && cmdtype
!= class_files
&& cmdtype
!= class_support
470 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
471 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
472 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
474 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
478 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
480 PyErr_Format (PyExc_RuntimeError
,
481 _("Invalid completion type argument."));
485 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
490 if (is_prefix
!= NULL
)
492 cmp
= PyObject_IsTrue (is_prefix
);
497 /* Make a normalized form of the command name. */
498 pfx_name
= (char *) xmalloc (strlen (name
) + 2);
504 /* Skip whitespace. */
505 while (name
[i
] == ' ' || name
[i
] == '\t')
507 /* Copy non-whitespace characters. */
508 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
509 pfx_name
[out
++] = name
[i
++];
510 /* Add a single space after each word -- including the final
512 pfx_name
[out
++] = ' ';
514 pfx_name
[out
] = '\0';
522 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
524 gdbpy_ref
<> ds_obj (PyObject_GetAttr (self
, gdbpy_doc_cst
));
526 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
528 docstring
= python_string_to_host_string (ds_obj
.get ()).release ();
529 if (docstring
== NULL
)
538 docstring
= xstrdup (_("This command is not documented."));
540 gdbpy_ref
<> self_ref
= gdbpy_ref
<>::new_reference (self
);
544 struct cmd_list_element
*cmd
;
550 /* If we have our own "invoke" method, then allow unknown
552 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
553 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
554 NULL
, docstring
, &obj
->sub_list
,
555 pfx_name
, allow_unknown
, cmd_list
);
558 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
,
559 docstring
, cmd_list
);
561 /* There appears to be no API to set this. */
562 cmd
->func
= cmdpy_function
;
563 cmd
->destroyer
= cmdpy_destroyer
;
564 cmd
->doc_allocated
= 1;
567 set_cmd_context (cmd
, self_ref
.release ());
568 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
569 : completers
[completetype
].completer
));
570 if (completetype
== -1)
571 set_cmd_completer_handle_brkchars (cmd
,
572 cmdpy_completer_handle_brkchars
);
574 catch (const gdb_exception
&except
)
579 gdbpy_convert_exception (except
);
588 /* Initialize the 'commands' code. */
591 gdbpy_initialize_commands (void)
595 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
596 if (PyType_Ready (&cmdpy_object_type
) < 0)
599 /* Note: alias and user are special; pseudo appears to be unused,
600 and there is no reason to expose tui, I think. */
601 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
602 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
603 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
604 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
605 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
606 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
608 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
609 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
610 class_breakpoint
) < 0
611 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
613 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
615 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
616 class_maintenance
) < 0
617 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
620 for (i
= 0; i
< N_COMPLETERS
; ++i
)
622 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
626 if (gdb_pymodule_addobject (gdb_module
, "Command",
627 (PyObject
*) &cmdpy_object_type
) < 0)
630 invoke_cst
= PyString_FromString ("invoke");
631 if (invoke_cst
== NULL
)
633 complete_cst
= PyString_FromString ("complete");
634 if (complete_cst
== NULL
)
642 static PyMethodDef cmdpy_object_methods
[] =
644 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
645 "Prevent command repetition when user enters empty line." },
650 PyTypeObject cmdpy_object_type
=
652 PyVarObject_HEAD_INIT (NULL
, 0)
653 "gdb.Command", /*tp_name*/
654 sizeof (cmdpy_object
), /*tp_basicsize*/
663 0, /*tp_as_sequence*/
671 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
672 "GDB command object", /* tp_doc */
675 0, /* tp_richcompare */
676 0, /* tp_weaklistoffset */
679 cmdpy_object_methods
, /* tp_methods */
684 0, /* tp_descr_get */
685 0, /* tp_descr_set */
686 0, /* tp_dictoffset */
687 cmdpy_init
, /* tp_init */
693 /* Utility to build a buildargv-like result from ARGS.
694 This intentionally parses arguments the way libiberty/argv.c:buildargv
695 does. It splits up arguments in a reasonable way, and we want a standard
696 way of parsing arguments. Several gdb commands use buildargv to parse their
697 arguments. Plus we want to be able to write compatible python
698 implementations of gdb commands. */
701 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
705 if (!PyArg_ParseTuple (args
, "s", &input
))
708 gdbpy_ref
<> py_argv (PyList_New (0));
712 /* buildargv uses NULL to represent an empty argument list, but we can't use
713 that in Python. Instead, if ARGS is "" then return an empty list.
714 This undoes the NULL -> "" conversion that cmdpy_function does. */
718 gdb_argv
c_argv (input
);
720 for (char *arg
: c_argv
)
722 gdbpy_ref
<> argp (PyString_FromString (arg
));
725 || PyList_Append (py_argv
.get (), argp
.get ()) < 0)
730 return py_argv
.release ();