1/* gdb commands implemented in Python
2
3   Copyright (C) 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
4
5   This file is part of GDB.
6
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.
11
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.
16
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/>.  */
19
20
21#include "defs.h"
22#include "arch-utils.h"
23#include "value.h"
24#include "exceptions.h"
25#include "python-internal.h"
26#include "charset.h"
27#include "gdbcmd.h"
28#include "cli/cli-decode.h"
29#include "completer.h"
30#include "language.h"
31
32/* Struct representing built-in completion types.  */
33struct cmdpy_completer
34{
35  /* Python symbol name.  */
36  char *name;
37  /* Completion function.  */
38  char **(*completer) (struct cmd_list_element *, char *, char *);
39};
40
41static struct cmdpy_completer completers[] =
42{
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 },
48};
49
50#define N_COMPLETERS (sizeof (completers) / sizeof (completers[0]))
51
52/* A gdb command.  For the time being only ordinary commands (not
53   set/show commands) are allowed.  */
54struct cmdpy_object
55{
56  PyObject_HEAD
57
58  /* The corresponding gdb command object, or NULL if the command is
59     no longer installed.  */
60  struct cmd_list_element *command;
61
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;
67};
68
69typedef struct cmdpy_object cmdpy_object;
70
71static PyTypeObject cmdpy_object_type;
72
73
74/* Constants used by this module.  */
75static PyObject *invoke_cst;
76static PyObject *complete_cst;
77
78
79
80/* Python function which wraps dont_repeat.  */
81static PyObject *
82cmdpy_dont_repeat (PyObject *self, PyObject *args)
83{
84  dont_repeat ();
85  Py_RETURN_NONE;
86}
87
88
89
90/* Called if the gdb cmd_list_element is destroyed.  */
91
92static void
93cmdpy_destroyer (struct cmd_list_element *self, void *context)
94{
95  cmdpy_object *cmd;
96  struct cleanup *cleanup;
97
98  cleanup = ensure_python_env (get_current_arch (), current_language);
99
100  /* Release our hold on the command object.  */
101  cmd = (cmdpy_object *) context;
102  cmd->command = NULL;
103  Py_DECREF (cmd);
104
105  /* We allocated the name, doc string, and perhaps the prefix
106     name.  */
107  xfree (self->name);
108  xfree (self->doc);
109  xfree (self->prefixname);
110
111  do_cleanups (cleanup);
112}
113
114/* Called by gdb to invoke the command.  */
115
116static void
117cmdpy_function (struct cmd_list_element *command, char *args, int from_tty)
118{
119  cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command);
120  PyObject *argobj, *ttyobj, *result;
121  struct cleanup *cleanup;
122
123  cleanup = ensure_python_env (get_current_arch (), current_language);
124
125  if (! obj)
126    error (_("Invalid invocation of Python command object."));
127  if (! PyObject_HasAttr ((PyObject *) obj, invoke_cst))
128    {
129      if (obj->command->prefixname)
130	{
131	  /* A prefix command does not need an invoke method.  */
132	  do_cleanups (cleanup);
133	  return;
134	}
135      error (_("Python command object missing 'invoke' method."));
136    }
137
138  if (! args)
139    args = "";
140  argobj = PyUnicode_Decode (args, strlen (args), host_charset (), NULL);
141  if (! argobj)
142    {
143      gdbpy_print_stack ();
144      error (_("Could not convert arguments to Python string."));
145    }
146
147  ttyobj = from_tty ? Py_True : Py_False;
148  Py_INCREF (ttyobj);
149  result = PyObject_CallMethodObjArgs ((PyObject *) obj, invoke_cst, argobj,
150				       ttyobj, NULL);
151  Py_DECREF (argobj);
152  Py_DECREF (ttyobj);
153
154  if (! result)
155    {
156      PyObject *ptype, *pvalue, *ptraceback;
157      char *msg;
158
159      PyErr_Fetch (&ptype, &pvalue, &ptraceback);
160
161      /* Try to fetch an error message contained within ptype, pvalue.
162	 When fetching the error message we need to make our own copy,
163	 we no longer own ptype, pvalue after the call to PyErr_Restore.  */
164
165      msg = gdbpy_exception_to_string (ptype, pvalue);
166      make_cleanup (xfree, msg);
167
168      if (msg == NULL)
169	{
170	  /* An error occurred computing the string representation of the
171	     error message.  This is rare, but we should inform the user.  */
172	  printf_filtered (_("An error occurred in a Python command\n"
173			     "and then another occurred computing the "
174			     "error message.\n"));
175	  gdbpy_print_stack ();
176	}
177
178      /* Don't print the stack for gdb.GdbError exceptions.
179	 It is generally used to flag user errors.
180
181	 We also don't want to print "Error occurred in Python command"
182	 for user errors.  However, a missing message for gdb.GdbError
183	 exceptions is arguably a bug, so we flag it as such.  */
184
185      if (! PyErr_GivenExceptionMatches (ptype, gdbpy_gdberror_exc)
186	  || msg == NULL || *msg == '\0')
187	{
188	  PyErr_Restore (ptype, pvalue, ptraceback);
189	  gdbpy_print_stack ();
190	  if (msg != NULL && *msg != '\0')
191	    error (_("Error occurred in Python command: %s"), msg);
192	  else
193	    error (_("Error occurred in Python command."));
194	}
195      else
196	{
197	  Py_XDECREF (ptype);
198	  Py_XDECREF (pvalue);
199	  Py_XDECREF (ptraceback);
200	  error ("%s", msg);
201	}
202    }
203
204  Py_DECREF (result);
205  do_cleanups (cleanup);
206}
207
208/* Called by gdb for command completion.  */
209static char **
210cmdpy_completer (struct cmd_list_element *command, char *text, char *word)
211{
212  cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command);
213  PyObject *textobj, *wordobj, *resultobj = NULL;
214  char **result = NULL;
215  struct cleanup *cleanup;
216
217  cleanup = ensure_python_env (get_current_arch (), current_language);
218
219  if (! obj)
220    error (_("Invalid invocation of Python command object."));
221  if (! PyObject_HasAttr ((PyObject *) obj, complete_cst))
222    {
223      /* If there is no complete method, don't error -- instead, just
224	 say that there are no completions.  */
225      goto done;
226    }
227
228  textobj = PyUnicode_Decode (text, strlen (text), host_charset (), NULL);
229  if (! textobj)
230    error (_("Could not convert argument to Python string."));
231  wordobj = PyUnicode_Decode (word, strlen (word), host_charset (), NULL);
232  if (! wordobj)
233    error (_("Could not convert argument to Python string."));
234
235  resultobj = PyObject_CallMethodObjArgs ((PyObject *) obj, complete_cst,
236					  textobj, wordobj, NULL);
237  Py_DECREF (textobj);
238  Py_DECREF (wordobj);
239  if (! resultobj)
240    {
241      /* Just swallow errors here.  */
242      PyErr_Clear ();
243      goto done;
244    }
245  make_cleanup_py_decref (resultobj);
246
247  result = NULL;
248  if (PySequence_Check (resultobj))
249    {
250      Py_ssize_t i, len = PySequence_Size (resultobj);
251      Py_ssize_t out;
252
253      if (len < 0)
254	goto done;
255
256      result = (char **) xmalloc ((len + 1) * sizeof (char *));
257      for (i = out = 0; i < len; ++i)
258	{
259	  PyObject *elt = PySequence_GetItem (resultobj, i);
260
261	  if (elt == NULL || ! gdbpy_is_string (elt))
262	    {
263	      /* Skip problem elements.  */
264	      PyErr_Clear ();
265	      continue;
266	    }
267	  result[out] = python_string_to_host_string (elt);
268	  if (result[out] == NULL)
269	    {
270	      /* Skip problem elements.  */
271	      PyErr_Clear ();
272	      continue;
273	    }
274	  ++out;
275	}
276      result[out] = NULL;
277    }
278  else if (PyInt_Check (resultobj))
279    {
280      /* User code may also return one of the completion constants,
281	 thus requesting that sort of completion.  */
282      long value;
283
284      if (! gdb_py_int_as_long (resultobj, &value))
285	{
286	  /* Ignore.  */
287	  PyErr_Clear ();
288	}
289      else if (value >= 0 && value < (long) N_COMPLETERS)
290	result = completers[value].completer (command, text, word);
291    }
292
293 done:
294
295  do_cleanups (cleanup);
296
297  return result;
298}
299
300/* Helper for cmdpy_init which locates the command list to use and
301   pulls out the command name.
302
303   TEXT is the command name list.  The final word in the list is the
304   name of the new command.  All earlier words must be existing prefix
305   commands.
306
307   *BASE_LIST is set to the final prefix command's list of
308   *sub-commands.
309
310   START_LIST is the list in which the search starts.
311
312   This function returns the xmalloc()d name of the new command.  On
313   error sets the Python error and returns NULL.  */
314char *
315gdbpy_parse_command_name (char *text,
316			  struct cmd_list_element ***base_list,
317			  struct cmd_list_element **start_list)
318{
319  struct cmd_list_element *elt;
320  int len = strlen (text);
321  int i, lastchar;
322  char *prefix_text;
323  char *result;
324
325  /* Skip trailing whitespace.  */
326  for (i = len - 1; i >= 0 && (text[i] == ' ' || text[i] == '\t'); --i)
327    ;
328  if (i < 0)
329    {
330      PyErr_SetString (PyExc_RuntimeError, _("No command name found."));
331      return NULL;
332    }
333  lastchar = i;
334
335  /* Find first character of the final word.  */
336  for (; i > 0 && (isalnum (text[i - 1])
337		   || text[i - 1] == '-'
338		   || text[i - 1] == '_');
339       --i)
340    ;
341  result = xmalloc (lastchar - i + 2);
342  memcpy (result, &text[i], lastchar - i + 1);
343  result[lastchar - i + 1] = '\0';
344
345  /* Skip whitespace again.  */
346  for (--i; i >= 0 && (text[i] == ' ' || text[i] == '\t'); --i)
347    ;
348  if (i < 0)
349    {
350      *base_list = start_list;
351      return result;
352    }
353
354  prefix_text = xmalloc (i + 2);
355  memcpy (prefix_text, text, i + 1);
356  prefix_text[i + 1] = '\0';
357
358  text = prefix_text;
359  elt = lookup_cmd_1 (&text, *start_list, NULL, 1);
360  if (!elt || elt == (struct cmd_list_element *) -1)
361    {
362      PyErr_Format (PyExc_RuntimeError, _("Could not find command prefix %s."),
363		    prefix_text);
364      xfree (prefix_text);
365      xfree (result);
366      return NULL;
367    }
368
369  if (elt->prefixlist)
370    {
371      xfree (prefix_text);
372      *base_list = elt->prefixlist;
373      return result;
374    }
375
376  PyErr_Format (PyExc_RuntimeError, _("'%s' is not a prefix command."),
377		prefix_text);
378  xfree (prefix_text);
379  xfree (result);
380  return NULL;
381}
382
383/* Object initializer; sets up gdb-side structures for command.
384
385   Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
386
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.
390
391   COMMAND_CLASS is the kind of command.  It should be one of the COMMAND_*
392   constants defined in the gdb module.
393
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.
397
398   If PREFIX is True, then this command is a prefix command.
399
400   The documentation for the command is taken from the doc string for
401   the python class.
402
403*/
404static int
405cmdpy_init (PyObject *self, PyObject *args, PyObject *kw)
406{
407  cmdpy_object *obj = (cmdpy_object *) self;
408  char *name;
409  int cmdtype;
410  int completetype = -1;
411  char *docstring = NULL;
412  volatile struct gdb_exception except;
413  struct cmd_list_element **cmd_list;
414  char *cmd_name, *pfx_name;
415  static char *keywords[] = { "name", "command_class", "completer_class",
416			      "prefix", NULL };
417  PyObject *is_prefix = NULL;
418  int cmp;
419
420  if (obj->command)
421    {
422      /* Note: this is apparently not documented in Python.  We return
423	 0 for success, -1 for failure.  */
424      PyErr_Format (PyExc_RuntimeError,
425		    _("Command object already initialized."));
426      return -1;
427    }
428
429  if (! PyArg_ParseTupleAndKeywords (args, kw, "si|iO",
430				     keywords, &name, &cmdtype,
431			  &completetype, &is_prefix))
432    return -1;
433
434  if (cmdtype != no_class && cmdtype != class_run
435      && cmdtype != class_vars && cmdtype != class_stack
436      && cmdtype != class_files && cmdtype != class_support
437      && cmdtype != class_info && cmdtype != class_breakpoint
438      && cmdtype != class_trace && cmdtype != class_obscure
439      && cmdtype != class_maintenance)
440    {
441      PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
442      return -1;
443    }
444
445  if (completetype < -1 || completetype >= (int) N_COMPLETERS)
446    {
447      PyErr_Format (PyExc_RuntimeError,
448		    _("Invalid completion type argument."));
449      return -1;
450    }
451
452  cmd_name = gdbpy_parse_command_name (name, &cmd_list, &cmdlist);
453  if (! cmd_name)
454    return -1;
455
456  pfx_name = NULL;
457  if (is_prefix != NULL)
458    {
459      cmp = PyObject_IsTrue (is_prefix);
460      if (cmp == 1)
461	{
462	  int i, out;
463
464	  /* Make a normalized form of the command name.  */
465	  pfx_name = xmalloc (strlen (name) + 2);
466
467	  i = 0;
468	  out = 0;
469	  while (name[i])
470	    {
471	      /* Skip whitespace.  */
472	      while (name[i] == ' ' || name[i] == '\t')
473		++i;
474	      /* Copy non-whitespace characters.  */
475	      while (name[i] && name[i] != ' ' && name[i] != '\t')
476		pfx_name[out++] = name[i++];
477	      /* Add a single space after each word -- including the final
478		 word.  */
479	      pfx_name[out++] = ' ';
480	    }
481	  pfx_name[out] = '\0';
482	}
483      else if (cmp < 0)
484	{
485	  xfree (cmd_name);
486	  return -1;
487	}
488    }
489  if (PyObject_HasAttr (self, gdbpy_doc_cst))
490    {
491      PyObject *ds_obj = PyObject_GetAttr (self, gdbpy_doc_cst);
492
493      if (ds_obj && gdbpy_is_string (ds_obj))
494	{
495	  docstring = python_string_to_host_string (ds_obj);
496	  if (docstring == NULL)
497	    {
498	      xfree (cmd_name);
499	      xfree (pfx_name);
500	      return -1;
501	    }
502	}
503    }
504  if (! docstring)
505    docstring = xstrdup (_("This command is not documented."));
506
507  Py_INCREF (self);
508
509  TRY_CATCH (except, RETURN_MASK_ALL)
510    {
511      struct cmd_list_element *cmd;
512
513      if (pfx_name)
514	{
515	  int allow_unknown;
516
517	  /* If we have our own "invoke" method, then allow unknown
518	     sub-commands.  */
519	  allow_unknown = PyObject_HasAttr (self, invoke_cst);
520	  cmd = add_prefix_cmd (cmd_name, (enum command_class) cmdtype,
521				NULL, docstring, &obj->sub_list,
522				pfx_name, allow_unknown, cmd_list);
523	}
524      else
525	cmd = add_cmd (cmd_name, (enum command_class) cmdtype, NULL,
526		       docstring, cmd_list);
527
528      /* There appears to be no API to set this.  */
529      cmd->func = cmdpy_function;
530      cmd->destroyer = cmdpy_destroyer;
531
532      obj->command = cmd;
533      set_cmd_context (cmd, self);
534      set_cmd_completer (cmd, ((completetype == -1) ? cmdpy_completer
535			       : completers[completetype].completer));
536    }
537  if (except.reason < 0)
538    {
539      xfree (cmd_name);
540      xfree (docstring);
541      xfree (pfx_name);
542      Py_DECREF (self);
543      PyErr_Format (except.reason == RETURN_QUIT
544		    ? PyExc_KeyboardInterrupt : PyExc_RuntimeError,
545		    "%s", except.message);
546      return -1;
547    }
548  return 0;
549}
550
551
552
553/* Initialize the 'commands' code.  */
554void
555gdbpy_initialize_commands (void)
556{
557  int i;
558
559  if (PyType_Ready (&cmdpy_object_type) < 0)
560    return;
561
562  /* Note: alias and user are special; pseudo appears to be unused,
563     and there is no reason to expose tui or xdb, I think.  */
564  if (PyModule_AddIntConstant (gdb_module, "COMMAND_NONE", no_class) < 0
565      || PyModule_AddIntConstant (gdb_module, "COMMAND_RUNNING", class_run) < 0
566      || PyModule_AddIntConstant (gdb_module, "COMMAND_DATA", class_vars) < 0
567      || PyModule_AddIntConstant (gdb_module, "COMMAND_STACK", class_stack) < 0
568      || PyModule_AddIntConstant (gdb_module, "COMMAND_FILES", class_files) < 0
569      || PyModule_AddIntConstant (gdb_module, "COMMAND_SUPPORT",
570				  class_support) < 0
571      || PyModule_AddIntConstant (gdb_module, "COMMAND_STATUS", class_info) < 0
572      || PyModule_AddIntConstant (gdb_module, "COMMAND_BREAKPOINTS",
573				  class_breakpoint) < 0
574      || PyModule_AddIntConstant (gdb_module, "COMMAND_TRACEPOINTS",
575				  class_trace) < 0
576      || PyModule_AddIntConstant (gdb_module, "COMMAND_OBSCURE",
577				  class_obscure) < 0
578      || PyModule_AddIntConstant (gdb_module, "COMMAND_MAINTENANCE",
579				  class_maintenance) < 0)
580    return;
581
582  for (i = 0; i < N_COMPLETERS; ++i)
583    {
584      if (PyModule_AddIntConstant (gdb_module, completers[i].name, i) < 0)
585	return;
586    }
587
588  Py_INCREF (&cmdpy_object_type);
589  PyModule_AddObject (gdb_module, "Command",
590		      (PyObject *) &cmdpy_object_type);
591
592  invoke_cst = PyString_FromString ("invoke");
593  complete_cst = PyString_FromString ("complete");
594}
595
596
597
598static PyMethodDef cmdpy_object_methods[] =
599{
600  { "dont_repeat", cmdpy_dont_repeat, METH_NOARGS,
601    "Prevent command repetition when user enters empty line." },
602
603  { 0 }
604};
605
606static PyTypeObject cmdpy_object_type =
607{
608  PyObject_HEAD_INIT (NULL)
609  0,				  /*ob_size*/
610  "gdb.Command",		  /*tp_name*/
611  sizeof (cmdpy_object),	  /*tp_basicsize*/
612  0,				  /*tp_itemsize*/
613  0,				  /*tp_dealloc*/
614  0,				  /*tp_print*/
615  0,				  /*tp_getattr*/
616  0,				  /*tp_setattr*/
617  0,				  /*tp_compare*/
618  0,				  /*tp_repr*/
619  0,				  /*tp_as_number*/
620  0,				  /*tp_as_sequence*/
621  0,				  /*tp_as_mapping*/
622  0,				  /*tp_hash */
623  0,				  /*tp_call*/
624  0,				  /*tp_str*/
625  0,				  /*tp_getattro*/
626  0,				  /*tp_setattro*/
627  0,				  /*tp_as_buffer*/
628  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
629  "GDB command object",		  /* tp_doc */
630  0,				  /* tp_traverse */
631  0,				  /* tp_clear */
632  0,				  /* tp_richcompare */
633  0,				  /* tp_weaklistoffset */
634  0,				  /* tp_iter */
635  0,				  /* tp_iternext */
636  cmdpy_object_methods,		  /* tp_methods */
637  0,				  /* tp_members */
638  0,				  /* tp_getset */
639  0,				  /* tp_base */
640  0,				  /* tp_dict */
641  0,				  /* tp_descr_get */
642  0,				  /* tp_descr_set */
643  0,				  /* tp_dictoffset */
644  cmdpy_init,			  /* tp_init */
645  0,				  /* tp_alloc */
646  PyType_GenericNew		  /* tp_new */
647};
648
649
650
651/* Utility to build a buildargv-like result from ARGS.
652   This intentionally parses arguments the way libiberty/argv.c:buildargv
653   does.  It splits up arguments in a reasonable way, and we want a standard
654   way of parsing arguments.  Several gdb commands use buildargv to parse their
655   arguments.  Plus we want to be able to write compatible python
656   implementations of gdb commands.  */
657
658PyObject *
659gdbpy_string_to_argv (PyObject *self, PyObject *args)
660{
661  PyObject *py_argv;
662  char *input;
663
664  if (!PyArg_ParseTuple (args, "s", &input))
665    return NULL;
666
667  py_argv = PyList_New (0);
668
669  /* buildargv uses NULL to represent an empty argument list, but we can't use
670     that in Python.  Instead, if ARGS is "" then return an empty list.
671     This undoes the NULL -> "" conversion that cmdpy_function does.  */
672
673  if (*input != '\0')
674    {
675      char **c_argv = gdb_buildargv (input);
676      int i;
677
678      for (i = 0; c_argv[i] != NULL; ++i)
679	{
680	  PyObject *argp = PyString_FromString (c_argv[i]);
681
682	  if (argp == NULL
683	      || PyList_Append (py_argv, argp) < 0)
684	    {
685	      if (argp != NULL)
686		{
687		  Py_DECREF (argp);
688		}
689	      Py_DECREF (py_argv);
690	      freeargv (c_argv);
691	      return NULL;
692	    }
693	}
694
695      freeargv (c_argv);
696    }
697
698  return py_argv;
699}
700