1 /* gdb commands implemented in Python
3 Copyright (C) 2008-2012 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 "exceptions.h"
25 #include "python-internal.h"
28 #include "cli/cli-decode.h"
29 #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 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", make_symbol_completion_list_fn
},
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 static PyTypeObject cmdpy_object_type
;
73 /* Constants used by this module. */
74 static PyObject
*invoke_cst
;
75 static PyObject
*complete_cst
;
79 /* Python function which wraps dont_repeat. */
81 cmdpy_dont_repeat (PyObject
*self
, PyObject
*args
)
89 /* Called if the gdb cmd_list_element is destroyed. */
92 cmdpy_destroyer (struct cmd_list_element
*self
, void *context
)
95 struct cleanup
*cleanup
;
97 cleanup
= ensure_python_env (get_current_arch (), current_language
);
99 /* Release our hold on the command object. */
100 cmd
= (cmdpy_object
*) context
;
104 /* We allocated the name, doc string, and perhaps the prefix
108 xfree (self
->prefixname
);
110 do_cleanups (cleanup
);
113 /* Called by gdb to invoke the command. */
116 cmdpy_function (struct cmd_list_element
*command
, char *args
, int from_tty
)
118 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
119 PyObject
*argobj
, *ttyobj
, *result
;
120 struct cleanup
*cleanup
;
122 cleanup
= ensure_python_env (get_current_arch (), current_language
);
125 error (_("Invalid invocation of Python command object."));
126 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
128 if (obj
->command
->prefixname
)
130 /* A prefix command does not need an invoke method. */
131 do_cleanups (cleanup
);
134 error (_("Python command object missing 'invoke' method."));
139 argobj
= PyUnicode_Decode (args
, strlen (args
), host_charset (), NULL
);
142 gdbpy_print_stack ();
143 error (_("Could not convert arguments to Python string."));
146 ttyobj
= from_tty
? Py_True
: Py_False
;
148 result
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
, argobj
,
155 PyObject
*ptype
, *pvalue
, *ptraceback
;
158 PyErr_Fetch (&ptype
, &pvalue
, &ptraceback
);
160 /* Try to fetch an error message contained within ptype, pvalue.
161 When fetching the error message we need to make our own copy,
162 we no longer own ptype, pvalue after the call to PyErr_Restore. */
164 msg
= gdbpy_exception_to_string (ptype
, pvalue
);
165 make_cleanup (xfree
, msg
);
169 /* An error occurred computing the string representation of the
170 error message. This is rare, but we should inform the user. */
171 printf_filtered (_("An error occurred in a Python command\n"
172 "and then another occurred computing the "
173 "error message.\n"));
174 gdbpy_print_stack ();
177 /* Don't print the stack for gdb.GdbError exceptions.
178 It is generally used to flag user errors.
180 We also don't want to print "Error occurred in Python command"
181 for user errors. However, a missing message for gdb.GdbError
182 exceptions is arguably a bug, so we flag it as such. */
184 if (! PyErr_GivenExceptionMatches (ptype
, gdbpy_gdberror_exc
)
185 || msg
== NULL
|| *msg
== '\0')
187 PyErr_Restore (ptype
, pvalue
, ptraceback
);
188 gdbpy_print_stack ();
189 if (msg
!= NULL
&& *msg
!= '\0')
190 error (_("Error occurred in Python command: %s"), msg
);
192 error (_("Error occurred in Python command."));
198 Py_XDECREF (ptraceback
);
204 do_cleanups (cleanup
);
207 /* Called by gdb for command completion. */
209 static VEC (char_ptr
) *
210 cmdpy_completer (struct cmd_list_element
*command
, char *text
, char *word
)
212 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
213 PyObject
*textobj
, *wordobj
, *resultobj
= NULL
;
214 VEC (char_ptr
) *result
= NULL
;
215 struct cleanup
*cleanup
;
217 cleanup
= ensure_python_env (get_current_arch (), current_language
);
220 error (_("Invalid invocation of Python command object."));
221 if (! PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
223 /* If there is no complete method, don't error -- instead, just
224 say that there are no completions. */
228 textobj
= PyUnicode_Decode (text
, strlen (text
), host_charset (), NULL
);
230 error (_("Could not convert argument to Python string."));
231 wordobj
= PyUnicode_Decode (word
, strlen (word
), host_charset (), NULL
);
233 error (_("Could not convert argument to Python string."));
235 resultobj
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, complete_cst
,
236 textobj
, wordobj
, NULL
);
241 /* Just swallow errors here. */
245 make_cleanup_py_decref (resultobj
);
248 if (PySequence_Check (resultobj
))
250 Py_ssize_t i
, len
= PySequence_Size (resultobj
);
256 for (i
= out
= 0; i
< len
; ++i
)
258 PyObject
*elt
= PySequence_GetItem (resultobj
, i
);
261 if (elt
== NULL
|| ! gdbpy_is_string (elt
))
263 /* Skip problem elements. */
267 item
= python_string_to_host_string (elt
);
270 /* Skip problem elements. */
274 VEC_safe_push (char_ptr
, result
, item
);
277 else if (PyInt_Check (resultobj
))
279 /* User code may also return one of the completion constants,
280 thus requesting that sort of completion. */
283 if (! gdb_py_int_as_long (resultobj
, &value
))
288 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
289 result
= completers
[value
].completer (command
, text
, word
);
294 do_cleanups (cleanup
);
299 /* Helper for cmdpy_init which locates the command list to use and
300 pulls out the command name.
302 NAME is the command name list. The final word in the list is the
303 name of the new command. All earlier words must be existing prefix
306 *BASE_LIST is set to the final prefix command's list of
309 START_LIST is the list in which the search starts.
311 This function returns the xmalloc()d name of the new command. On
312 error sets the Python error and returns NULL. */
315 gdbpy_parse_command_name (const char *name
,
316 struct cmd_list_element
***base_list
,
317 struct cmd_list_element
**start_list
)
319 struct cmd_list_element
*elt
;
320 int len
= strlen (name
);
322 char *prefix_text
, *prefix_text2
;
325 /* Skip trailing whitespace. */
326 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
330 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
335 /* Find first character of the final word. */
336 for (; i
> 0 && (isalnum (name
[i
- 1])
337 || name
[i
- 1] == '-'
338 || name
[i
- 1] == '_');
341 result
= xmalloc (lastchar
- i
+ 2);
342 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
343 result
[lastchar
- i
+ 1] = '\0';
345 /* Skip whitespace again. */
346 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
350 *base_list
= start_list
;
354 prefix_text
= xmalloc (i
+ 2);
355 memcpy (prefix_text
, name
, i
+ 1);
356 prefix_text
[i
+ 1] = '\0';
358 prefix_text2
= prefix_text
;
359 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
360 if (!elt
|| elt
== (struct cmd_list_element
*) -1)
362 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
372 *base_list
= elt
->prefixlist
;
376 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
383 /* Object initializer; sets up gdb-side structures for command.
385 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
387 NAME is the name of the command. It may consist of multiple words,
388 in which case the final word is the name of the new command, and
389 earlier words must be prefix commands.
391 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
392 constants defined in the gdb module.
394 COMPLETER_CLASS is the kind of completer. If not given, the
395 "complete" method will be used. Otherwise, it should be one of the
396 COMPLETE_* constants defined in the gdb module.
398 If PREFIX is True, then this command is a prefix command.
400 The documentation for the command is taken from the doc string for
404 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
406 cmdpy_object
*obj
= (cmdpy_object
*) self
;
409 int completetype
= -1;
410 char *docstring
= NULL
;
411 volatile struct gdb_exception except
;
412 struct cmd_list_element
**cmd_list
;
413 char *cmd_name
, *pfx_name
;
414 static char *keywords
[] = { "name", "command_class", "completer_class",
416 PyObject
*is_prefix
= NULL
;
421 /* Note: this is apparently not documented in Python. We return
422 0 for success, -1 for failure. */
423 PyErr_Format (PyExc_RuntimeError
,
424 _("Command object already initialized."));
428 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
429 keywords
, &name
, &cmdtype
,
430 &completetype
, &is_prefix
))
433 if (cmdtype
!= no_class
&& cmdtype
!= class_run
434 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
435 && cmdtype
!= class_files
&& cmdtype
!= class_support
436 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
437 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
438 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
440 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
444 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
446 PyErr_Format (PyExc_RuntimeError
,
447 _("Invalid completion type argument."));
451 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
456 if (is_prefix
!= NULL
)
458 cmp
= PyObject_IsTrue (is_prefix
);
463 /* Make a normalized form of the command name. */
464 pfx_name
= xmalloc (strlen (name
) + 2);
470 /* Skip whitespace. */
471 while (name
[i
] == ' ' || name
[i
] == '\t')
473 /* Copy non-whitespace characters. */
474 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
475 pfx_name
[out
++] = name
[i
++];
476 /* Add a single space after each word -- including the final
478 pfx_name
[out
++] = ' ';
480 pfx_name
[out
] = '\0';
488 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
490 PyObject
*ds_obj
= PyObject_GetAttr (self
, gdbpy_doc_cst
);
492 if (ds_obj
&& gdbpy_is_string (ds_obj
))
494 docstring
= python_string_to_host_string (ds_obj
);
495 if (docstring
== NULL
)
504 docstring
= xstrdup (_("This command is not documented."));
508 TRY_CATCH (except
, RETURN_MASK_ALL
)
510 struct cmd_list_element
*cmd
;
516 /* If we have our own "invoke" method, then allow unknown
518 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
519 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
520 NULL
, docstring
, &obj
->sub_list
,
521 pfx_name
, allow_unknown
, cmd_list
);
524 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
, NULL
,
525 docstring
, cmd_list
);
527 /* There appears to be no API to set this. */
528 cmd
->func
= cmdpy_function
;
529 cmd
->destroyer
= cmdpy_destroyer
;
532 set_cmd_context (cmd
, self
);
533 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
534 : completers
[completetype
].completer
));
536 if (except
.reason
< 0)
542 PyErr_Format (except
.reason
== RETURN_QUIT
543 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
544 "%s", except
.message
);
552 /* Initialize the 'commands' code. */
555 gdbpy_initialize_commands (void)
559 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
560 if (PyType_Ready (&cmdpy_object_type
) < 0)
563 /* Note: alias and user are special; pseudo appears to be unused,
564 and there is no reason to expose tui or xdb, I think. */
565 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
566 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
567 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
568 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
569 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
570 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
572 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
573 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
574 class_breakpoint
) < 0
575 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
577 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
579 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
580 class_maintenance
) < 0
581 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
584 for (i
= 0; i
< N_COMPLETERS
; ++i
)
586 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
590 Py_INCREF (&cmdpy_object_type
);
591 PyModule_AddObject (gdb_module
, "Command",
592 (PyObject
*) &cmdpy_object_type
);
594 invoke_cst
= PyString_FromString ("invoke");
595 complete_cst
= PyString_FromString ("complete");
600 static PyMethodDef cmdpy_object_methods
[] =
602 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
603 "Prevent command repetition when user enters empty line." },
608 static PyTypeObject cmdpy_object_type
=
610 PyObject_HEAD_INIT (NULL
)
612 "gdb.Command", /*tp_name*/
613 sizeof (cmdpy_object
), /*tp_basicsize*/
622 0, /*tp_as_sequence*/
630 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
631 "GDB command object", /* tp_doc */
634 0, /* tp_richcompare */
635 0, /* tp_weaklistoffset */
638 cmdpy_object_methods
, /* tp_methods */
643 0, /* tp_descr_get */
644 0, /* tp_descr_set */
645 0, /* tp_dictoffset */
646 cmdpy_init
, /* tp_init */
652 /* Utility to build a buildargv-like result from ARGS.
653 This intentionally parses arguments the way libiberty/argv.c:buildargv
654 does. It splits up arguments in a reasonable way, and we want a standard
655 way of parsing arguments. Several gdb commands use buildargv to parse their
656 arguments. Plus we want to be able to write compatible python
657 implementations of gdb commands. */
660 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
665 if (!PyArg_ParseTuple (args
, "s", &input
))
668 py_argv
= PyList_New (0);
670 /* buildargv uses NULL to represent an empty argument list, but we can't use
671 that in Python. Instead, if ARGS is "" then return an empty list.
672 This undoes the NULL -> "" conversion that cmdpy_function does. */
676 char **c_argv
= gdb_buildargv (input
);
679 for (i
= 0; c_argv
[i
] != NULL
; ++i
)
681 PyObject
*argp
= PyString_FromString (c_argv
[i
]);
684 || PyList_Append (py_argv
, argp
) < 0)