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 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 && (isalnum (name
[i
- 1])
376 || name
[i
- 1] == '-'
377 || name
[i
- 1] == '_');
380 result
= (char *) xmalloc (lastchar
- i
+ 2);
381 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
382 result
[lastchar
- i
+ 1] = '\0';
384 /* Skip whitespace again. */
385 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
389 *base_list
= start_list
;
393 std::string
prefix_text (name
, i
+ 1);
395 prefix_text2
= prefix_text
.c_str ();
396 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
397 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
399 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
400 prefix_text
.c_str ());
407 *base_list
= elt
->prefixlist
;
411 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
412 prefix_text
.c_str ());
417 /* Object initializer; sets up gdb-side structures for command.
419 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
421 NAME is the name of the command. It may consist of multiple words,
422 in which case the final word is the name of the new command, and
423 earlier words must be prefix commands.
425 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
426 constants defined in the gdb module.
428 COMPLETER_CLASS is the kind of completer. If not given, the
429 "complete" method will be used. Otherwise, it should be one of the
430 COMPLETE_* constants defined in the gdb module.
432 If PREFIX is True, then this command is a prefix command.
434 The documentation for the command is taken from the doc string for
438 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
440 cmdpy_object
*obj
= (cmdpy_object
*) self
;
443 int completetype
= -1;
444 char *docstring
= NULL
;
445 struct cmd_list_element
**cmd_list
;
446 char *cmd_name
, *pfx_name
;
447 static const char *keywords
[] = { "name", "command_class", "completer_class",
449 PyObject
*is_prefix
= NULL
;
454 /* Note: this is apparently not documented in Python. We return
455 0 for success, -1 for failure. */
456 PyErr_Format (PyExc_RuntimeError
,
457 _("Command object already initialized."));
461 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
462 keywords
, &name
, &cmdtype
,
463 &completetype
, &is_prefix
))
466 if (cmdtype
!= no_class
&& cmdtype
!= class_run
467 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
468 && cmdtype
!= class_files
&& cmdtype
!= class_support
469 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
470 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
471 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
473 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
477 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
479 PyErr_Format (PyExc_RuntimeError
,
480 _("Invalid completion type argument."));
484 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
489 if (is_prefix
!= NULL
)
491 cmp
= PyObject_IsTrue (is_prefix
);
496 /* Make a normalized form of the command name. */
497 pfx_name
= (char *) xmalloc (strlen (name
) + 2);
503 /* Skip whitespace. */
504 while (name
[i
] == ' ' || name
[i
] == '\t')
506 /* Copy non-whitespace characters. */
507 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
508 pfx_name
[out
++] = name
[i
++];
509 /* Add a single space after each word -- including the final
511 pfx_name
[out
++] = ' ';
513 pfx_name
[out
] = '\0';
521 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
523 gdbpy_ref
<> ds_obj (PyObject_GetAttr (self
, gdbpy_doc_cst
));
525 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
527 docstring
= python_string_to_host_string (ds_obj
.get ()).release ();
528 if (docstring
== NULL
)
537 docstring
= xstrdup (_("This command is not documented."));
539 gdbpy_ref
<> self_ref
= gdbpy_ref
<>::new_reference (self
);
543 struct cmd_list_element
*cmd
;
549 /* If we have our own "invoke" method, then allow unknown
551 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
552 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
553 NULL
, docstring
, &obj
->sub_list
,
554 pfx_name
, allow_unknown
, cmd_list
);
557 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
,
558 docstring
, cmd_list
);
560 /* There appears to be no API to set this. */
561 cmd
->func
= cmdpy_function
;
562 cmd
->destroyer
= cmdpy_destroyer
;
563 cmd
->doc_allocated
= 1;
564 cmd
->name_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 ();