gdb/python/py-param.c

   1 /* GDB parameters implemented in Python
   2
   3    Copyright (C) 2008-2023 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 "value.h"
  23 #include "python-internal.h"
  24 #include "charset.h"
  25 #include "gdbcmd.h"
  26 #include "cli/cli-decode.h"
  27 #include "completer.h"
  28 #include "language.h"
  29 #include "arch-utils.h"
  30
  31 /* Python parameter types as in PARM_CONSTANTS below.  */
  32
  33 enum py_param_types
  34 {
  35   param_boolean,
  36   param_auto_boolean,
  37   param_uinteger,
  38   param_integer,
  39   param_string,
  40   param_string_noescape,
  41   param_optional_filename,
  42   param_filename,
  43   param_zinteger,
  44   param_zuinteger,
  45   param_zuinteger_unlimited,
  46   param_enum,
  47 };
  48
  49 /* Translation from Python parameters to GDB variable types.  Keep in the
  50    same order as PARAM_TYPES due to C++'s lack of designated initializers.  */
  51
  52 static const struct
  53 {
  54   /* The type of the parameter.  */
  55   enum var_types type;
  56
  57   /* Extra literals, such as `unlimited', accepted in lieu of a number.  */
  58   const literal_def *extra_literals;
  59 }
  60 param_to_var[] =
  61 {
  62   { var_boolean },
  63   { var_auto_boolean },
  64   { var_uinteger, uinteger_unlimited_literals },
  65   { var_integer, integer_unlimited_literals },
  66   { var_string },
  67   { var_string_noescape },
  68   { var_optional_filename },
  69   { var_filename },
  70   { var_integer },
  71   { var_uinteger },
  72   { var_pinteger, pinteger_unlimited_literals },
  73   { var_enum }
  74 };
  75
  76 /* Parameter constants and their values.  */
  77 static struct {
  78   const char *name;
  79   int value;
  80 } parm_constants[] =
  81 {
  82   { "PARAM_BOOLEAN", param_boolean }, /* ARI: param_boolean */
  83   { "PARAM_AUTO_BOOLEAN", param_auto_boolean },
  84   { "PARAM_UINTEGER", param_uinteger },
  85   { "PARAM_INTEGER", param_integer },
  86   { "PARAM_STRING", param_string },
  87   { "PARAM_STRING_NOESCAPE", param_string_noescape },
  88   { "PARAM_OPTIONAL_FILENAME", param_optional_filename },
  89   { "PARAM_FILENAME", param_filename },
  90   { "PARAM_ZINTEGER", param_zinteger },
  91   { "PARAM_ZUINTEGER", param_zuinteger },
  92   { "PARAM_ZUINTEGER_UNLIMITED", param_zuinteger_unlimited },
  93   { "PARAM_ENUM", param_enum },
  94   { NULL, 0 }
  95 };
  96
  97 /* A union that can hold anything described by enum var_types.  */
  98 union parmpy_variable
  99 {
 100   /* Hold a boolean value.  */
 101   bool boolval;
 102
 103   /* Hold an integer value.  */
 104   int intval;
 105
 106   /* Hold an auto_boolean.  */
 107   enum auto_boolean autoboolval;
 108
 109   /* Hold an unsigned integer value, for uinteger.  */
 110   unsigned int uintval;
 111
 112   /* Hold a string, for the various string types.  The std::string is
 113      new-ed.  */
 114   std::string *stringval;
 115
 116   /* Hold a string, for enums.  */
 117   const char *cstringval;
 118 };
 119
 120 /* A GDB parameter.  */
 121 struct parmpy_object
 122 {
 123   PyObject_HEAD
 124
 125   /* The type of the parameter.  */
 126   enum var_types type;
 127
 128   /* Extra literals, such as `unlimited', accepted in lieu of a number.  */
 129   const literal_def *extra_literals;
 130
 131   /* The value of the parameter.  */
 132   union parmpy_variable value;
 133
 134   /* For an enum command, the possible values.  The vector is
 135      allocated with xmalloc, as is each element.  It is
 136      NULL-terminated.  */
 137   const char **enumeration;
 138 };
 139
 140 /* Wraps a setting around an existing parmpy_object.  This abstraction
 141    is used to manipulate the value in S->VALUE in a type safe manner using
 142    the setting interface.  */
 143
 144 static setting
 145 make_setting (parmpy_object *s)
 146 {
 147   enum var_types type = s->type;
 148
 149   if (var_type_uses<bool> (type))
 150     return setting (type, &s->value.boolval);
 151   else if (var_type_uses<int> (type))
 152     return setting (type, &s->value.intval, s->extra_literals);
 153   else if (var_type_uses<auto_boolean> (type))
 154     return setting (type, &s->value.autoboolval);
 155   else if (var_type_uses<unsigned int> (type))
 156     return setting (type, &s->value.uintval, s->extra_literals);
 157   else if (var_type_uses<std::string> (type))
 158     return setting (type, s->value.stringval);
 159   else if (var_type_uses<const char *> (type))
 160     return setting (type, &s->value.cstringval);
 161   else
 162     gdb_assert_not_reached ("unhandled var type");
 163 }
 164
 165 extern PyTypeObject parmpy_object_type
 166     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("parmpy_object");
 167
 168 /* Some handy string constants.  */
 169 static PyObject *set_doc_cst;
 170 static PyObject *show_doc_cst;
 171
 172 \f
 173
 174 /* Get an attribute.  */
 175 static PyObject *
 176 get_attr (PyObject *obj, PyObject *attr_name)
 177 {
 178   if (PyUnicode_Check (attr_name)
 179       && ! PyUnicode_CompareWithASCIIString (attr_name, "value"))
 180     {
 181       parmpy_object *self = (parmpy_object *) obj;
 182
 183       return gdbpy_parameter_value (make_setting (self));
 184     }
 185
 186   return PyObject_GenericGetAttr (obj, attr_name);
 187 }
 188
 189 /* Set a parameter value from a Python value.  Return 0 on success.  Returns
 190    -1 on error, with a python exception set.  */
 191 static int
 192 set_parameter_value (parmpy_object *self, PyObject *value)
 193 {
 194   int cmp;
 195
 196   switch (self->type)
 197     {
 198     case var_string:
 199     case var_string_noescape:
 200     case var_optional_filename:
 201     case var_filename:
 202       if (! gdbpy_is_string (value)
 203           && (self->type == var_filename
 204               || value != Py_None))
 205         {
 206           PyErr_SetString (PyExc_RuntimeError,
 207                            _("String required for filename."));
 208
 209           return -1;
 210         }
 211       if (value == Py_None)
 212         self->value.stringval->clear ();
 213       else
 214         {
 215           gdb::unique_xmalloc_ptr<char>
 216             string (python_string_to_host_string (value));
 217           if (string == NULL)
 218             return -1;
 219
 220           *self->value.stringval = string.get ();
 221         }
 222       break;
 223
 224     case var_enum:
 225       {
 226         int i;
 227
 228         if (! gdbpy_is_string (value))
 229           {
 230             PyErr_SetString (PyExc_RuntimeError,
 231                              _("ENUM arguments must be a string."));
 232             return -1;
 233           }
 234
 235         gdb::unique_xmalloc_ptr<char>
 236           str (python_string_to_host_string (value));
 237         if (str == NULL)
 238           return -1;
 239         for (i = 0; self->enumeration[i]; ++i)
 240           if (! strcmp (self->enumeration[i], str.get ()))
 241             break;
 242         if (! self->enumeration[i])
 243           {
 244             PyErr_SetString (PyExc_RuntimeError,
 245                              _("The value must be member of an enumeration."));
 246             return -1;
 247           }
 248         self->value.cstringval = self->enumeration[i];
 249         break;
 250       }
 251
 252     case var_boolean:
 253       if (! PyBool_Check (value))
 254         {
 255           PyErr_SetString (PyExc_RuntimeError,
 256                            _("A boolean argument is required."));
 257           return -1;
 258         }
 259       cmp = PyObject_IsTrue (value);
 260       if (cmp < 0)
 261           return -1;
 262       self->value.boolval = cmp;
 263       break;
 264
 265     case var_auto_boolean:
 266       if (! PyBool_Check (value) && value != Py_None)
 267         {
 268           PyErr_SetString (PyExc_RuntimeError,
 269                            _("A boolean or None is required"));
 270           return -1;
 271         }
 272
 273       if (value == Py_None)
 274         self->value.autoboolval = AUTO_BOOLEAN_AUTO;
 275       else
 276         {
 277           cmp = PyObject_IsTrue (value);
 278           if (cmp < 0 )
 279             return -1;
 280           if (cmp == 1)
 281             self->value.autoboolval = AUTO_BOOLEAN_TRUE;
 282           else
 283             self->value.autoboolval = AUTO_BOOLEAN_FALSE;
 284         }
 285       break;
 286
 287     case var_uinteger:
 288     case var_integer:
 289     case var_pinteger:
 290       {
 291         const literal_def *extra_literals = self->extra_literals;
 292         enum tribool allowed = TRIBOOL_UNKNOWN;
 293         enum var_types var_type = self->type;
 294         std::string buffer = "";
 295         size_t count = 0;
 296         LONGEST val;
 297
 298         if (extra_literals != nullptr)
 299           {
 300             gdb::unique_xmalloc_ptr<char>
 301               str (python_string_to_host_string (value));
 302             const char *s = str != nullptr ? str.get () : nullptr;
 303             PyErr_Clear ();
 304
 305             for (const literal_def *l = extra_literals;
 306                  l->literal != nullptr;
 307                  l++, count++)
 308               {
 309                 if (count != 0)
 310                   buffer += ", ";
 311                 buffer = buffer + "'" + l->literal + "'";
 312                 if (allowed == TRIBOOL_UNKNOWN
 313                     && ((value == Py_None && !strcmp ("unlimited", l->literal))
 314                         || (s != nullptr && !strcmp (s, l->literal))))
 315                   {
 316                     val = l->use;
 317                     allowed = TRIBOOL_TRUE;
 318                   }
 319               }
 320           }
 321
 322         if (allowed == TRIBOOL_UNKNOWN)
 323           {
 324             val = PyLong_AsLongLong (value);
 325
 326             if (PyErr_Occurred ())
 327               {
 328                 if (extra_literals == nullptr)
 329                   PyErr_SetString (PyExc_RuntimeError,
 330                                    _("The value must be integer."));
 331                 else if (count > 1)
 332                   PyErr_SetString (PyExc_RuntimeError,
 333                                    string_printf (_("integer or one of: %s"),
 334                                                   buffer.c_str ()).c_str ());
 335                 else
 336                   PyErr_SetString (PyExc_RuntimeError,
 337                                    string_printf (_("integer or %s"),
 338                                                   buffer.c_str ()).c_str ());
 339                 return -1;
 340               }
 341
 342
 343             if (extra_literals != nullptr)
 344               for (const literal_def *l = extra_literals;
 345                    l->literal != nullptr;
 346                    l++)
 347                 {
 348                   if (l->val.has_value () && val == *l->val)
 349                     {
 350                       allowed = TRIBOOL_TRUE;
 351                       val = l->use;
 352                       break;
 353                     }
 354                   else if (val == l->use)
 355                     allowed = TRIBOOL_FALSE;
 356                 }
 357             }
 358
 359         if (allowed == TRIBOOL_UNKNOWN)
 360           {
 361             if (val > UINT_MAX || val < INT_MIN
 362                 || (var_type == var_uinteger && val < 0)
 363                 || (var_type == var_integer && val > INT_MAX)
 364                 || (var_type == var_pinteger && val < 0)
 365                 || (var_type == var_pinteger && val > INT_MAX))
 366               allowed = TRIBOOL_FALSE;
 367           }
 368         if (allowed == TRIBOOL_FALSE)
 369           {
 370             PyErr_SetString (PyExc_RuntimeError,
 371                              _("Range exceeded."));
 372             return -1;
 373           }
 374
 375         if (self->type == var_uinteger)
 376           self->value.uintval = (unsigned) val;
 377         else
 378           self->value.intval = (int) val;
 379         break;
 380       }
 381
 382     default:
 383       PyErr_SetString (PyExc_RuntimeError,
 384                        _("Unhandled type in parameter value."));
 385       return -1;
 386     }
 387
 388   return 0;
 389 }
 390
 391 /* Set an attribute.  Returns -1 on error, with a python exception set.  */
 392 static int
 393 set_attr (PyObject *obj, PyObject *attr_name, PyObject *val)
 394 {
 395   if (PyUnicode_Check (attr_name)
 396       && ! PyUnicode_CompareWithASCIIString (attr_name, "value"))
 397     {
 398       if (!val)
 399         {
 400           PyErr_SetString (PyExc_RuntimeError,
 401                            _("Cannot delete a parameter's value."));
 402           return -1;
 403         }
 404       return set_parameter_value ((parmpy_object *) obj, val);
 405     }
 406
 407   return PyObject_GenericSetAttr (obj, attr_name, val);
 408 }
 409
 410 /* Build up the path to command C, but drop the first component of the
 411    command prefix.  This is only intended for use with the set/show
 412    parameters this file deals with, the first prefix should always be
 413    either 'set' or 'show'.
 414
 415    As an example, if this full command is 'set prefix_a prefix_b command'
 416    this function will return the string 'prefix_a prefix_b command'.  */
 417
 418 static std::string
 419 full_cmd_name_without_first_prefix (struct cmd_list_element *c)
 420 {
 421   std::vector<std::string> components
 422     = c->command_components ();
 423   gdb_assert (components.size () > 1);
 424   std::string result = components[1];
 425   for (int i = 2; i < components.size (); ++i)
 426     result += " " + components[i];
 427   return result;
 428 }
 429
 430 /* The different types of documentation string.  */
 431
 432 enum doc_string_type
 433 {
 434   doc_string_set,
 435   doc_string_show,
 436   doc_string_description
 437 };
 438
 439 /* A helper function which returns a documentation string for an
 440    object. */
 441
 442 static gdb::unique_xmalloc_ptr<char>
 443 get_doc_string (PyObject *object, enum doc_string_type doc_type,
 444                 const char *cmd_name)
 445 {
 446   gdb::unique_xmalloc_ptr<char> result;
 447
 448   PyObject *attr = nullptr;
 449   switch (doc_type)
 450     {
 451     case doc_string_set:
 452       attr = set_doc_cst;
 453       break;
 454     case doc_string_show:
 455       attr = show_doc_cst;
 456       break;
 457     case doc_string_description:
 458       attr = gdbpy_doc_cst;
 459       break;
 460     }
 461   gdb_assert (attr != nullptr);
 462
 463   if (PyObject_HasAttr (object, attr))
 464     {
 465       gdbpy_ref<> ds_obj (PyObject_GetAttr (object, attr));
 466
 467       if (ds_obj != NULL && gdbpy_is_string (ds_obj.get ()))
 468         {
 469           result = python_string_to_host_string (ds_obj.get ());
 470           if (result == NULL)
 471             gdbpy_print_stack ();
 472           else if (doc_type == doc_string_description)
 473             result = gdbpy_fix_doc_string_indentation (std::move (result));
 474         }
 475     }
 476
 477   if (result == nullptr)
 478     {
 479       if (doc_type == doc_string_description)
 480         result.reset (xstrdup (_("This command is not documented.")));
 481       else
 482         {
 483           if (doc_type == doc_string_show)
 484             result = xstrprintf (_("Show the current value of '%s'."),
 485                                  cmd_name);
 486           else
 487             result = xstrprintf (_("Set the current value of '%s'."),
 488                                  cmd_name);
 489         }
 490     }
 491   return result;
 492 }
 493
 494 /* Helper function which will execute a METHOD in OBJ passing the
 495    argument ARG.  ARG can be NULL.  METHOD should return a Python
 496    string.  If this function returns NULL, there has been an error and
 497    the appropriate exception set.  */
 498 static gdb::unique_xmalloc_ptr<char>
 499 call_doc_function (PyObject *obj, PyObject *method, PyObject *arg)
 500 {
 501   gdb::unique_xmalloc_ptr<char> data;
 502   gdbpy_ref<> result (PyObject_CallMethodObjArgs (obj, method, arg, NULL));
 503
 504   if (result == NULL)
 505     return NULL;
 506
 507   if (gdbpy_is_string (result.get ()))
 508     {
 509       data = python_string_to_host_string (result.get ());
 510       if (! data)
 511         return NULL;
 512     }
 513   else
 514     {
 515       PyErr_SetString (PyExc_RuntimeError,
 516                        _("Parameter must return a string value."));
 517       return NULL;
 518     }
 519
 520   return data;
 521 }
 522
 523 /* A callback function that is registered against the respective
 524    add_setshow_* set_doc prototype.  This function calls the Python function
 525    "get_set_string" if it exists, which will return a string.  That string
 526    is then printed.  If "get_set_string" does not exist, or returns an
 527    empty string, then nothing is printed.  */
 528 static void
 529 get_set_value (const char *args, int from_tty,
 530                struct cmd_list_element *c)
 531 {
 532   PyObject *obj = (PyObject *) c->context ();
 533   gdb::unique_xmalloc_ptr<char> set_doc_string;
 534
 535   gdbpy_enter enter_py;
 536   gdbpy_ref<> set_doc_func (PyUnicode_FromString ("get_set_string"));
 537
 538   if (set_doc_func == NULL)
 539     {
 540       gdbpy_print_stack ();
 541       return;
 542     }
 543
 544   if (PyObject_HasAttr (obj, set_doc_func.get ()))
 545     {
 546       set_doc_string = call_doc_function (obj, set_doc_func.get (), NULL);
 547       if (! set_doc_string)
 548         gdbpy_handle_exception ();
 549     }
 550
 551   const char *str = set_doc_string.get ();
 552   if (str != nullptr && str[0] != '\0')
 553     gdb_printf ("%s\n", str);
 554 }
 555
 556 /* A callback function that is registered against the respective
 557    add_setshow_* show_doc prototype.  This function will either call
 558    the Python function "get_show_string" or extract the Python
 559    attribute "show_doc" and return the contents as a string.  If
 560    neither exist, insert a string indicating the Parameter is not
 561    documented.  */
 562 static void
 563 get_show_value (struct ui_file *file, int from_tty,
 564                 struct cmd_list_element *c,
 565                 const char *value)
 566 {
 567   PyObject *obj = (PyObject *) c->context ();
 568   gdb::unique_xmalloc_ptr<char> show_doc_string;
 569
 570   gdbpy_enter enter_py;
 571   gdbpy_ref<> show_doc_func (PyUnicode_FromString ("get_show_string"));
 572
 573   if (show_doc_func == NULL)
 574     {
 575       gdbpy_print_stack ();
 576       return;
 577     }
 578
 579   if (PyObject_HasAttr (obj, show_doc_func.get ()))
 580     {
 581       gdbpy_ref<> val_obj (PyUnicode_FromString (value));
 582
 583       if (val_obj == NULL)
 584         {
 585           gdbpy_print_stack ();
 586           return;
 587         }
 588
 589       show_doc_string = call_doc_function (obj, show_doc_func.get (),
 590                                            val_obj.get ());
 591       if (! show_doc_string)
 592         {
 593           gdbpy_print_stack ();
 594           return;
 595         }
 596
 597       gdb_printf (file, "%s\n", show_doc_string.get ());
 598     }
 599   else
 600     {
 601       /* If there is no 'get_show_string' callback then we want to show
 602          something sensible here.  In older versions of GDB (< 7.3) we
 603          didn't support 'get_show_string', and instead we just made use of
 604          GDB's builtin use of the show_doc.  However, GDB's builtin
 605          show_doc adjustment is not i18n friendly, so, instead, we just
 606          print this generic string.  */
 607       std::string cmd_path = full_cmd_name_without_first_prefix (c);
 608       gdb_printf (file, _("The current value of '%s' is \"%s\".\n"),
 609                   cmd_path.c_str (), value);
 610     }
 611 }
 612 \f
 613
 614 /* A helper function that dispatches to the appropriate add_setshow
 615    function.  */
 616 static void
 617 add_setshow_generic (enum var_types type, const literal_def *extra_literals,
 618                      enum command_class cmdclass,
 619                      gdb::unique_xmalloc_ptr<char> cmd_name,
 620                      parmpy_object *self,
 621                      const char *set_doc, const char *show_doc,
 622                      const char *help_doc,
 623                      struct cmd_list_element **set_list,
 624                      struct cmd_list_element **show_list)
 625 {
 626   set_show_commands commands;
 627
 628   switch (type)
 629     {
 630     case var_boolean:
 631       commands = add_setshow_boolean_cmd (cmd_name.get (), cmdclass,
 632                                           &self->value.boolval, set_doc,
 633                                           show_doc, help_doc, get_set_value,
 634                                           get_show_value, set_list, show_list);
 635
 636       break;
 637
 638     case var_auto_boolean:
 639       commands = add_setshow_auto_boolean_cmd (cmd_name.get (), cmdclass,
 640                                                &self->value.autoboolval,
 641                                                set_doc, show_doc, help_doc,
 642                                                get_set_value, get_show_value,
 643                                                set_list, show_list);
 644       break;
 645
 646     case var_uinteger:
 647       commands = add_setshow_uinteger_cmd (cmd_name.get (), cmdclass,
 648                                            &self->value.uintval,
 649                                            extra_literals, set_doc,
 650                                            show_doc, help_doc, get_set_value,
 651                                            get_show_value, set_list, show_list);
 652       break;
 653
 654     case var_integer:
 655       commands = add_setshow_integer_cmd (cmd_name.get (), cmdclass,
 656                                           &self->value.intval,
 657                                           extra_literals, set_doc,
 658                                           show_doc, help_doc, get_set_value,
 659                                           get_show_value, set_list, show_list);
 660       break;
 661
 662     case var_pinteger:
 663       commands = add_setshow_pinteger_cmd (cmd_name.get (), cmdclass,
 664                                            &self->value.intval,
 665                                            extra_literals, set_doc,
 666                                            show_doc, help_doc, get_set_value,
 667                                            get_show_value, set_list, show_list);
 668       break;
 669
 670     case var_string:
 671       commands = add_setshow_string_cmd (cmd_name.get (), cmdclass,
 672                                          self->value.stringval, set_doc,
 673                                          show_doc, help_doc, get_set_value,
 674                                          get_show_value, set_list, show_list);
 675       break;
 676
 677     case var_string_noescape:
 678       commands = add_setshow_string_noescape_cmd (cmd_name.get (), cmdclass,
 679                                                   self->value.stringval,
 680                                                   set_doc, show_doc, help_doc,
 681                                                   get_set_value, get_show_value,
 682                                                   set_list, show_list);
 683       break;
 684
 685     case var_optional_filename:
 686       commands = add_setshow_optional_filename_cmd (cmd_name.get (), cmdclass,
 687                                                     self->value.stringval,
 688                                                     set_doc, show_doc, help_doc,
 689                                                     get_set_value,
 690                                                     get_show_value, set_list,
 691                                                     show_list);
 692       break;
 693
 694     case var_filename:
 695       commands = add_setshow_filename_cmd (cmd_name.get (), cmdclass,
 696                                            self->value.stringval, set_doc,
 697                                            show_doc, help_doc, get_set_value,
 698                                            get_show_value, set_list, show_list);
 699       break;
 700
 701     case var_enum:
 702       /* Initialize the value, just in case.  */
 703       self->value.cstringval = self->enumeration[0];
 704       commands = add_setshow_enum_cmd (cmd_name.get (), cmdclass,
 705                                        self->enumeration,
 706                                        &self->value.cstringval, set_doc,
 707                                        show_doc, help_doc, get_set_value,
 708                                        get_show_value, set_list, show_list);
 709       break;
 710
 711     default:
 712       gdb_assert_not_reached ("Unhandled parameter class.");
 713     }
 714
 715   /* Register Python objects in both commands' context.  */
 716   commands.set->set_context (self);
 717   commands.show->set_context (self);
 718
 719   /* We (unfortunately) currently leak the command name.  */
 720   cmd_name.release ();
 721 }
 722
 723 /* A helper which computes enum values.  Returns 1 on success.  Returns 0 on
 724    error, with a python exception set.  */
 725 static int
 726 compute_enum_values (parmpy_object *self, PyObject *enum_values)
 727 {
 728   Py_ssize_t size, i;
 729
 730   if (! enum_values)
 731     {
 732       PyErr_SetString (PyExc_RuntimeError,
 733                        _("An enumeration is required for PARAM_ENUM."));
 734       return 0;
 735     }
 736
 737   if (! PySequence_Check (enum_values))
 738     {
 739       PyErr_SetString (PyExc_RuntimeError,
 740                        _("The enumeration is not a sequence."));
 741       return 0;
 742     }
 743
 744   size = PySequence_Size (enum_values);
 745   if (size < 0)
 746     return 0;
 747   if (size == 0)
 748     {
 749       PyErr_SetString (PyExc_RuntimeError,
 750                        _("The enumeration is empty."));
 751       return 0;
 752     }
 753
 754   gdb_argv holder (XCNEWVEC (char *, size + 1));
 755   char **enumeration = holder.get ();
 756
 757   for (i = 0; i < size; ++i)
 758     {
 759       gdbpy_ref<> item (PySequence_GetItem (enum_values, i));
 760
 761       if (item == NULL)
 762         return 0;
 763       if (! gdbpy_is_string (item.get ()))
 764         {
 765           PyErr_SetString (PyExc_RuntimeError,
 766                            _("The enumeration item not a string."));
 767           return 0;
 768         }
 769       enumeration[i] = python_string_to_host_string (item.get ()).release ();
 770       if (enumeration[i] == NULL)
 771         return 0;
 772     }
 773
 774   self->enumeration = const_cast<const char**> (holder.release ());
 775   return 1;
 776 }
 777
 778 /* Object initializer; sets up gdb-side structures for command.
 779
 780    Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
 781
 782    NAME is the name of the parameter.  It may consist of multiple
 783    words, in which case the final word is the name of the new command,
 784    and earlier words must be prefix commands.
 785
 786    CMDCLASS is the kind of command.  It should be one of the COMMAND_*
 787    constants defined in the gdb module.
 788
 789    PARMCLASS is the type of the parameter.  It should be one of the
 790    PARAM_* constants defined in the gdb module.
 791
 792    If PARMCLASS is PARAM_ENUM, then the final argument should be a
 793    collection of strings.  These strings are the valid values for this
 794    parameter.
 795
 796    The documentation for the parameter is taken from the doc string
 797    for the python class.
 798
 799    Returns -1 on error, with a python exception set.  */
 800
 801 static int
 802 parmpy_init (PyObject *self, PyObject *args, PyObject *kwds)
 803 {
 804   parmpy_object *obj = (parmpy_object *) self;
 805   const char *name;
 806   gdb::unique_xmalloc_ptr<char> set_doc, show_doc, doc;
 807   int parmclass, cmdtype;
 808   PyObject *enum_values = NULL;
 809   struct cmd_list_element **set_list, **show_list;
 810   const literal_def *extra_literals;
 811   enum var_types type;
 812
 813   if (! PyArg_ParseTuple (args, "sii|O", &name, &cmdtype, &parmclass,
 814                           &enum_values))
 815     return -1;
 816
 817   if (cmdtype != no_class && cmdtype != class_run
 818       && cmdtype != class_vars && cmdtype != class_stack
 819       && cmdtype != class_files && cmdtype != class_support
 820       && cmdtype != class_info && cmdtype != class_breakpoint
 821       && cmdtype != class_trace && cmdtype != class_obscure
 822       && cmdtype != class_maintenance)
 823     {
 824       PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
 825       return -1;
 826     }
 827
 828   if (parmclass != param_boolean /* ARI: param_boolean */
 829       && parmclass != param_auto_boolean
 830       && parmclass != param_uinteger && parmclass != param_integer
 831       && parmclass != param_string && parmclass != param_string_noescape
 832       && parmclass != param_optional_filename && parmclass != param_filename
 833       && parmclass != param_zinteger && parmclass != param_zuinteger
 834       && parmclass != param_zuinteger_unlimited && parmclass != param_enum)
 835     {
 836       PyErr_SetString (PyExc_RuntimeError,
 837                        _("Invalid parameter class argument."));
 838       return -1;
 839     }
 840
 841   if (enum_values && parmclass != param_enum)
 842     {
 843       PyErr_SetString (PyExc_RuntimeError,
 844                        _("Only PARAM_ENUM accepts a fourth argument."));
 845       return -1;
 846     }
 847   if (parmclass == param_enum)
 848     {
 849       if (! compute_enum_values (obj, enum_values))
 850         return -1;
 851     }
 852   else
 853     obj->enumeration = NULL;
 854   type = param_to_var[parmclass].type;
 855   extra_literals = param_to_var[parmclass].extra_literals;
 856   obj->type = type;
 857   obj->extra_literals = extra_literals;
 858   memset (&obj->value, 0, sizeof (obj->value));
 859
 860   if (var_type_uses<std::string> (obj->type))
 861     obj->value.stringval = new std::string;
 862
 863   gdb::unique_xmalloc_ptr<char> cmd_name
 864     = gdbpy_parse_command_name (name, &set_list, &setlist);
 865   if (cmd_name == nullptr)
 866     return -1;
 867
 868   cmd_name = gdbpy_parse_command_name (name, &show_list, &showlist);
 869   if (cmd_name == nullptr)
 870     return -1;
 871
 872   set_doc = get_doc_string (self, doc_string_set, name);
 873   show_doc = get_doc_string (self, doc_string_show, name);
 874   doc = get_doc_string (self, doc_string_description, cmd_name.get ());
 875
 876   Py_INCREF (self);
 877
 878   try
 879     {
 880       add_setshow_generic (type, extra_literals,
 881                            (enum command_class) cmdtype,
 882                            std::move (cmd_name), obj,
 883                            set_doc.get (), show_doc.get (),
 884                            doc.get (), set_list, show_list);
 885     }
 886   catch (const gdb_exception &except)
 887     {
 888       Py_DECREF (self);
 889       gdbpy_convert_exception (except);
 890       return -1;
 891     }
 892
 893   return 0;
 894 }
 895
 896 /* Deallocate function for a gdb.Parameter.  */
 897
 898 static void
 899 parmpy_dealloc (PyObject *obj)
 900 {
 901   parmpy_object *parm_obj = (parmpy_object *) obj;
 902
 903   if (var_type_uses<std::string> (parm_obj->type))
 904     delete parm_obj->value.stringval;
 905 }
 906
 907 /* Initialize the 'parameters' module.  */
 908 static int CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION
 909 gdbpy_initialize_parameters (void)
 910 {
 911   int i;
 912
 913   parmpy_object_type.tp_new = PyType_GenericNew;
 914   if (PyType_Ready (&parmpy_object_type) < 0)
 915     return -1;
 916
 917   set_doc_cst = PyUnicode_FromString ("set_doc");
 918   if (! set_doc_cst)
 919     return -1;
 920   show_doc_cst = PyUnicode_FromString ("show_doc");
 921   if (! show_doc_cst)
 922     return -1;
 923
 924   for (i = 0; parm_constants[i].name; ++i)
 925     {
 926       if (PyModule_AddIntConstant (gdb_module,
 927                                    parm_constants[i].name,
 928                                    parm_constants[i].value) < 0)
 929         return -1;
 930     }
 931
 932   return gdb_pymodule_addobject (gdb_module, "Parameter",
 933                                  (PyObject *) &parmpy_object_type);
 934 }
 935
 936 GDBPY_INITIALIZE_FILE (gdbpy_initialize_parameters);
 937
 938 \f
 939
 940 PyTypeObject parmpy_object_type =
 941 {
 942   PyVarObject_HEAD_INIT (NULL, 0)
 943   "gdb.Parameter",                /*tp_name*/
 944   sizeof (parmpy_object),         /*tp_basicsize*/
 945   0,                              /*tp_itemsize*/
 946   parmpy_dealloc,                 /*tp_dealloc*/
 947   0,                              /*tp_print*/
 948   0,                              /*tp_getattr*/
 949   0,                              /*tp_setattr*/
 950   0,                              /*tp_compare*/
 951   0,                              /*tp_repr*/
 952   0,                              /*tp_as_number*/
 953   0,                              /*tp_as_sequence*/
 954   0,                              /*tp_as_mapping*/
 955   0,                              /*tp_hash */
 956   0,                              /*tp_call*/
 957   0,                              /*tp_str*/
 958   get_attr,                       /*tp_getattro*/
 959   set_attr,                       /*tp_setattro*/
 960   0,                              /*tp_as_buffer*/
 961   Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
 962   "GDB parameter object",         /* tp_doc */
 963   0,                              /* tp_traverse */
 964   0,                              /* tp_clear */
 965   0,                              /* tp_richcompare */
 966   0,                              /* tp_weaklistoffset */
 967   0,                              /* tp_iter */
 968   0,                              /* tp_iternext */
 969   0,                              /* tp_methods */
 970   0,                              /* tp_members */
 971   0,                              /* tp_getset */
 972   0,                              /* tp_base */
 973   0,                              /* tp_dict */
 974   0,                              /* tp_descr_get */
 975   0,                              /* tp_descr_set */
 976   0,                              /* tp_dictoffset */
 977   parmpy_init,                    /* tp_init */
 978   0,                              /* tp_alloc */
 979 };