gdb/cli/cli-option.h

   1 /* CLI options framework, for GDB.
   2
   3    Copyright (C) 2017-2022 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 #ifndef CLI_OPTION_H
  21 #define CLI_OPTION_H 1
  22
  23 #include "gdbsupport/gdb_optional.h"
  24 #include "gdbsupport/array-view.h"
  25 #include "completer.h"
  26 #include <string>
  27 #include "command.h"
  28
  29 namespace gdb {
  30 namespace option {
  31
  32 /* A type-erased option definition.  The actual type of the option is
  33    stored in the TYPE field.  Client code cannot define objects of
  34    this type directly (the ctor is protected).  Instead, one of the
  35    wrapper types below that extends this (boolean_option_def,
  36    flag_option_def, uinteger_option_def, etc.) should be defined.  */
  37 struct option_def
  38 {
  39   /* The ctor is protected because you're supposed to construct using
  40      one of bool_option_def, etc. below.  */
  41 protected:
  42   typedef void *(erased_get_var_address_ftype) ();
  43
  44   /* Construct an option.  NAME_ is the option's name.  VAR_TYPE_
  45      defines the option's type.  ERASED_GET_VAR_ADDRESS_ is a pointer
  46      to a function that returns the option's control variable.
  47      SHOW_CMD_CB_ is a pointer to callback for the "show" command that
  48      is installed for this option.  SET_DOC_, SHOW_DOC_, HELP_DOC_ are
  49      used to create the option's "set/show" commands.  */
  50   constexpr option_def (const char *name_,
  51                         var_types var_type_,
  52                         erased_get_var_address_ftype *erased_get_var_address_,
  53                         show_value_ftype *show_cmd_cb_,
  54                         const char *set_doc_,
  55                         const char *show_doc_,
  56                         const char *help_doc_)
  57     : name (name_), type (var_type_),
  58       erased_get_var_address (erased_get_var_address_),
  59       var_address {},
  60       show_cmd_cb (show_cmd_cb_),
  61       set_doc (set_doc_), show_doc (show_doc_), help_doc (help_doc_)
  62   {}
  63
  64 public:
  65   /* The option's name.  */
  66   const char *name;
  67
  68   /* The option's type.  */
  69   var_types type;
  70
  71   /* A function that gets the controlling variable's address, type
  72      erased.  */
  73   erased_get_var_address_ftype *erased_get_var_address;
  74
  75   /* Get the controlling variable's address.  Each type of variable
  76      uses a different union member.  We do this instead of having a
  77      single hook that return a "void *", for better type safety.  This
  78      way, actual instances of concrete option_def types
  79      (boolean_option_def, etc.) fail to compile if you pass in a
  80      function with incorrect return type.  CTX here is the aggregate
  81      object that groups the option variables from which the callback
  82      returns the address of some member.  */
  83   union
  84     {
  85       bool *(*boolean) (const option_def &, void *ctx);
  86       unsigned int *(*uinteger) (const option_def &, void *ctx);
  87       int *(*integer) (const option_def &, void *ctx);
  88       const char **(*enumeration) (const option_def &, void *ctx);
  89       std::string *(*string) (const option_def &, void *ctx);
  90     }
  91   var_address;
  92
  93   /* Pointer to null terminated list of enumerated values (like argv).
  94      Only used by var_enum options.  */
  95   const char *const *enums = nullptr;
  96
  97   /* True if the option takes an argument.  */
  98   bool have_argument = true;
  99
 100   /* The "show" callback to use in the associated "show" command.
 101      E.g., "show print elements".  */
 102   show_value_ftype *show_cmd_cb;
 103
 104   /* The set/show/help strings.  These are shown in both the help of
 105      commands that use the option group this option belongs to (e.g.,
 106      "help print"), and in the associated commands (e.g., "set/show
 107      print elements", "help set print elements").  */
 108   const char *set_doc;
 109   const char *show_doc;
 110   const char *help_doc;
 111
 112   /* Convenience method that returns THIS as an option_def.  Useful
 113      when you're putting an option_def subclass in an option_def
 114      array_view.  */
 115   const option_def &def () const
 116   {
 117     return *this;
 118   }
 119 };
 120
 121 namespace detail
 122 {
 123
 124 /* Get the address of the option's value, cast to the right type.
 125    RetType is the restored type of the variable, and Context is the
 126    restored type of the context pointer.  */
 127 template<typename RetType, typename Context>
 128 static inline RetType *
 129 get_var_address (const option_def &option, void *ctx)
 130 {
 131   using unerased_ftype = RetType *(Context *);
 132   unerased_ftype *fun = (unerased_ftype *) option.erased_get_var_address;
 133   return fun ((Context *) ctx);
 134 }
 135
 136 /* Convenience identity helper that just returns SELF.  */
 137
 138 template<typename T>
 139 static T *
 140 return_self (T *self)
 141 {
 142   return self;
 143 }
 144
 145 } /* namespace detail */
 146
 147 /* Follows the definitions of the option types that client code should
 148    define.  Note that objects of these types are placed in option_def
 149    arrays, by design, so they must not have data fields of their
 150    own.  */
 151
 152 /* A var_boolean command line option.  */
 153
 154 template<typename Context>
 155 struct boolean_option_def : option_def
 156 {
 157   boolean_option_def (const char *long_option_,
 158                       bool *(*get_var_address_cb_) (Context *),
 159                       show_value_ftype *show_cmd_cb_,
 160                       const char *set_doc_,
 161                       const char *show_doc_ = nullptr,
 162                       const char *help_doc_ = nullptr)
 163     : option_def (long_option_, var_boolean,
 164                   (erased_get_var_address_ftype *) get_var_address_cb_,
 165                   show_cmd_cb_,
 166                   set_doc_, show_doc_, help_doc_)
 167   {
 168     var_address.boolean = detail::get_var_address<bool, Context>;
 169   }
 170 };
 171
 172 /* A flag command line option.  This is a var_boolean option under the
 173    hood, but unlike boolean options, flag options don't take an on/off
 174    argument.  */
 175
 176 template<typename Context = bool>
 177 struct flag_option_def : boolean_option_def<Context>
 178 {
 179   flag_option_def (const char *long_option_,
 180                      bool *(*var_address_cb_) (Context *),
 181                      const char *set_doc_,
 182                      const char *help_doc_ = nullptr)
 183     : boolean_option_def<Context> (long_option_,
 184                                    var_address_cb_,
 185                                    NULL,
 186                                    set_doc_, NULL, help_doc_)
 187   {
 188     this->have_argument = false;
 189   }
 190
 191   flag_option_def (const char *long_option_,
 192                      const char *set_doc_,
 193                      const char *help_doc_ = nullptr)
 194     : boolean_option_def<Context> (long_option_,
 195                                    gdb::option::detail::return_self,
 196                                    NULL,
 197                                    set_doc_, nullptr, help_doc_)
 198   {
 199     this->have_argument = false;
 200   }
 201 };
 202
 203 /* A var_uinteger command line option.  */
 204
 205 template<typename Context>
 206 struct uinteger_option_def : option_def
 207 {
 208   uinteger_option_def (const char *long_option_,
 209                        unsigned int *(*get_var_address_cb_) (Context *),
 210                        show_value_ftype *show_cmd_cb_,
 211                        const char *set_doc_,
 212                        const char *show_doc_ = nullptr,
 213                        const char *help_doc_ = nullptr)
 214     : option_def (long_option_, var_uinteger,
 215                   (erased_get_var_address_ftype *) get_var_address_cb_,
 216                   show_cmd_cb_,
 217                   set_doc_, show_doc_, help_doc_)
 218   {
 219     var_address.uinteger = detail::get_var_address<unsigned int, Context>;
 220   }
 221 };
 222
 223 /* A var_zuinteger_unlimited command line option.  */
 224
 225 template<typename Context>
 226 struct zuinteger_unlimited_option_def : option_def
 227 {
 228   zuinteger_unlimited_option_def (const char *long_option_,
 229                                   int *(*get_var_address_cb_) (Context *),
 230                                   show_value_ftype *show_cmd_cb_,
 231                                   const char *set_doc_,
 232                                   const char *show_doc_ = nullptr,
 233                                   const char *help_doc_ = nullptr)
 234     : option_def (long_option_, var_zuinteger_unlimited,
 235                   (erased_get_var_address_ftype *) get_var_address_cb_,
 236                   show_cmd_cb_,
 237                   set_doc_, show_doc_, help_doc_)
 238   {
 239     var_address.integer = detail::get_var_address<int, Context>;
 240   }
 241 };
 242
 243 /* An var_enum command line option.  */
 244
 245 template<typename Context>
 246 struct enum_option_def : option_def
 247 {
 248   enum_option_def (const char *long_option_,
 249                    const char *const *enumlist,
 250                    const char **(*get_var_address_cb_) (Context *),
 251                    show_value_ftype *show_cmd_cb_,
 252                    const char *set_doc_,
 253                    const char *show_doc_ = nullptr,
 254                    const char *help_doc_ = nullptr)
 255     : option_def (long_option_, var_enum,
 256                   (erased_get_var_address_ftype *) get_var_address_cb_,
 257                   show_cmd_cb_,
 258                   set_doc_, show_doc_, help_doc_)
 259   {
 260     var_address.enumeration = detail::get_var_address<const char *, Context>;
 261     this->enums = enumlist;
 262   }
 263 };
 264
 265 /* A var_string command line option.  */
 266
 267 template<typename Context>
 268 struct string_option_def : option_def
 269 {
 270   string_option_def (const char *long_option_,
 271                      std::string *(*get_var_address_cb_) (Context *),
 272                      show_value_ftype *show_cmd_cb_,
 273                      const char *set_doc_,
 274                      const char *show_doc_ = nullptr,
 275                      const char *help_doc_ = nullptr)
 276     : option_def (long_option_, var_string,
 277                   (erased_get_var_address_ftype *) get_var_address_cb_,
 278                   show_cmd_cb_,
 279                   set_doc_, show_doc_, help_doc_)
 280   {
 281     var_address.enumeration = detail::get_var_address<const char *, Context>;
 282   }
 283 };
 284
 285 /* A group of options that all share the same context pointer to pass
 286    to the options' get-current-value callbacks.  */
 287 struct option_def_group
 288 {
 289   /* The list of options.  */
 290   gdb::array_view<const option_def> options;
 291
 292   /* The context pointer to pass to the options' get-current-value
 293      callbacks.  */
 294   void *ctx;
 295 };
 296
 297 /* Modes of operation for process_options.  */
 298 enum process_options_mode
 299 {
 300   /* In this mode, options are only processed if we find a "--"
 301      delimiter.  Throws an error if unknown options are found.  */
 302   PROCESS_OPTIONS_REQUIRE_DELIMITER,
 303
 304   /* In this mode, a "--" delimiter is not required.  Throws an error
 305      if unknown options are found, regardless of whether a delimiter
 306      is present.  */
 307   PROCESS_OPTIONS_UNKNOWN_IS_ERROR,
 308
 309   /* In this mode, a "--" delimiter is not required.  If an unknown
 310      option is found, assume it is the command's argument/operand.  */
 311   PROCESS_OPTIONS_UNKNOWN_IS_OPERAND,
 312 };
 313
 314 /* Process ARGS, using OPTIONS_GROUP as valid options.  Returns true
 315    if the string has been fully parsed and there are no operands to
 316    handle by the caller.  Return false if options were parsed, and
 317    *ARGS now points at the first operand.  */
 318 extern bool process_options
 319   (const char **args,
 320    process_options_mode mode,
 321    gdb::array_view<const option_def_group> options_group);
 322
 323 /* Complete ARGS on options listed by OPTIONS_GROUP.  Returns true if
 324    the string has been fully parsed and there are no operands to
 325    handle by the caller.  Return false if options were parsed, and
 326    *ARGS now points at the first operand.  */
 327 extern bool complete_options
 328   (completion_tracker &tracker,
 329    const char **args,
 330    process_options_mode mode,
 331    gdb::array_view<const option_def_group> options_group);
 332
 333 /* Complete on all options listed by OPTIONS_GROUP.  */
 334 extern void
 335   complete_on_all_options (completion_tracker &tracker,
 336                            gdb::array_view<const option_def_group> options_group);
 337
 338 /* Return a string with the result of replacing %OPTIONS% in HELP_TMLP
 339    with an auto-generated "help" string fragment for all the options
 340    in OPTIONS_GROUP.  */
 341 extern std::string build_help
 342   (const char *help_tmpl,
 343    gdb::array_view<const option_def_group> options_group);
 344
 345 /* Install set/show commands for options defined in OPTIONS.  DATA is
 346    a pointer to the structure that holds the data associated with the
 347    OPTIONS array.  */
 348 extern void add_setshow_cmds_for_options (command_class cmd_class, void *data,
 349                                           gdb::array_view<const option_def> options,
 350                                           struct cmd_list_element **set_list,
 351                                           struct cmd_list_element **show_list);
 352
 353 } /* namespace option */
 354 } /* namespace gdb */
 355
 356 #endif /* CLI_OPTION_H */