gdb/cli/cli-option.h

   1 /* CLI options framework, for GDB.
   2
   3    Copyright (C) 2017-2019 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 "common/gdb_optional.h"
  24 #include "common/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       int *(*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     }
  90   var_address;
  91
  92   /* Pointer to null terminated list of enumerated values (like argv).
  93      Only used by var_enum options.  */
  94   const char *const *enums = nullptr;
  95
  96   /* True if the option takes an argument.  */
  97   bool have_argument = true;
  98
  99   /* The "show" callback to use in the associated "show" command.
 100      E.g., "show print elements".  */
 101   show_value_ftype *show_cmd_cb;
 102
 103   /* The set/show/help strings.  These are shown in both the help of
 104      commands that use the option group this option belongs to (e.g.,
 105      "help print"), and in the associated commands (e.g., "set/show
 106      print elements", "help set print elements").  */
 107   const char *set_doc;
 108   const char *show_doc;
 109   const char *help_doc;
 110
 111   /* Convenience method that returns THIS as an option_def.  Useful
 112      when you're putting an option_def subclass in an option_def
 113      array_view.  */
 114   const option_def &def () const
 115   {
 116     return *this;
 117   }
 118 };
 119
 120 namespace detail
 121 {
 122
 123 /* Get the address of the option's value, cast to the right type.
 124    RetType is the restored type of the variable, and Context is the
 125    restored type of the context pointer.  */
 126 template<typename RetType, typename Context>
 127 static inline RetType *
 128 get_var_address (const option_def &option, void *ctx)
 129 {
 130   using unerased_ftype = RetType *(Context *);
 131   unerased_ftype *fun = (unerased_ftype *) option.erased_get_var_address;
 132   return fun ((Context *) ctx);
 133 }
 134
 135 /* Convenience identity helper that just returns SELF.  */
 136
 137 template<typename T>
 138 static T *
 139 return_self (T *self)
 140 {
 141   return self;
 142 }
 143
 144 } /* namespace detail */
 145
 146 /* Follows the definitions of the option types that client code should
 147    define.  Note that objects of these types are placed in option_def
 148    arrays, by design, so they must not have data fields of their
 149    own.  */
 150
 151 /* A var_boolean command line option.  */
 152
 153 template<typename Context>
 154 struct boolean_option_def : option_def
 155 {
 156   boolean_option_def (const char *long_option_,
 157                       int *(*get_var_address_cb_) (Context *),
 158                       show_value_ftype *show_cmd_cb_,
 159                       const char *set_doc_,
 160                       const char *show_doc_ = nullptr,
 161                       const char *help_doc_ = nullptr)
 162     : option_def (long_option_, var_boolean,
 163                   (erased_get_var_address_ftype *) get_var_address_cb_,
 164                   show_cmd_cb_,
 165                   set_doc_, show_doc_, help_doc_)
 166   {
 167     var_address.boolean = detail::get_var_address<int, Context>;
 168   }
 169 };
 170
 171 /* A flag command line option.  This is a var_boolean option under the
 172    hood, but unlike boolean options, flag options don't take an on/off
 173    argument.  */
 174
 175 template<typename Context = int>
 176 struct flag_option_def : boolean_option_def<Context>
 177 {
 178   flag_option_def (const char *long_option_,
 179                      int *(*var_address_cb_) (Context *),
 180                      const char *set_doc_,
 181                      const char *help_doc_ = nullptr)
 182     : boolean_option_def<Context> (long_option_,
 183                                    var_address_cb_,
 184                                    NULL,
 185                                    set_doc_, NULL, help_doc_)
 186   {
 187     this->have_argument = false;
 188   }
 189
 190   flag_option_def (const char *long_option_,
 191                      const char *set_doc_,
 192                      const char *help_doc_ = nullptr)
 193     : boolean_option_def<Context> (long_option_,
 194                                    gdb::option::detail::return_self,
 195                                    NULL,
 196                                    set_doc_, nullptr, help_doc_)
 197   {
 198     this->have_argument = false;
 199   }
 200 };
 201
 202 /* A var_uinteger command line option.  */
 203
 204 template<typename Context>
 205 struct uinteger_option_def : option_def
 206 {
 207   uinteger_option_def (const char *long_option_,
 208                        unsigned int *(*get_var_address_cb_) (Context *),
 209                        show_value_ftype *show_cmd_cb_,
 210                        const char *set_doc_,
 211                        const char *show_doc_ = nullptr,
 212                        const char *help_doc_ = nullptr)
 213     : option_def (long_option_, var_uinteger,
 214                   (erased_get_var_address_ftype *) get_var_address_cb_,
 215                   show_cmd_cb_,
 216                   set_doc_, show_doc_, help_doc_)
 217   {
 218     var_address.uinteger = detail::get_var_address<unsigned int, Context>;
 219   }
 220 };
 221
 222 /* A var_zuinteger_unlimited command line option.  */
 223
 224 template<typename Context>
 225 struct zuinteger_unlimited_option_def : option_def
 226 {
 227   zuinteger_unlimited_option_def (const char *long_option_,
 228                                   int *(*get_var_address_cb_) (Context *),
 229                                   show_value_ftype *show_cmd_cb_,
 230                                   const char *set_doc_,
 231                                   const char *show_doc_ = nullptr,
 232                                   const char *help_doc_ = nullptr)
 233     : option_def (long_option_, var_zuinteger_unlimited,
 234                   (erased_get_var_address_ftype *) get_var_address_cb_,
 235                   show_cmd_cb_,
 236                   set_doc_, show_doc_, help_doc_)
 237   {
 238     var_address.integer = detail::get_var_address<int, Context>;
 239   }
 240 };
 241
 242 /* An var_enum command line option.  */
 243
 244 template<typename Context>
 245 struct enum_option_def : option_def
 246 {
 247   enum_option_def (const char *long_option_,
 248                    const char *const *enumlist,
 249                    const char **(*get_var_address_cb_) (Context *),
 250                    show_value_ftype *show_cmd_cb_,
 251                    const char *set_doc_,
 252                    const char *show_doc_ = nullptr,
 253                    const char *help_doc_ = nullptr)
 254     : option_def (long_option_, var_enum,
 255                   (erased_get_var_address_ftype *) get_var_address_cb_,
 256                   show_cmd_cb_,
 257                   set_doc_, show_doc_, help_doc_)
 258   {
 259     var_address.enumeration = detail::get_var_address<const char *, Context>;
 260     this->enums = enumlist;
 261   }
 262 };
 263
 264 /* A group of options that all share the same context pointer to pass
 265    to the options' get-current-value callbacks.  */
 266 struct option_def_group
 267 {
 268   /* The list of options.  */
 269   gdb::array_view<const option_def> options;
 270
 271   /* The context pointer to pass to the options' get-current-value
 272      callbacks.  */
 273   void *ctx;
 274 };
 275
 276 /* Modes of operation for process_options.  */
 277 enum process_options_mode
 278 {
 279   /* In this mode, options are only processed if we find a "--"
 280      delimiter.  Throws an error if unknown options are found.  */
 281   PROCESS_OPTIONS_REQUIRE_DELIMITER,
 282
 283   /* In this mode, a "--" delimiter is not required.  Throws an error
 284      if unknown options are found, regardless of whether a delimiter
 285      is present.  */
 286   PROCESS_OPTIONS_UNKNOWN_IS_ERROR,
 287
 288   /* In this mode, a "--" delimiter is not required.  If an unknown
 289      option is found, assume it is the command's argument/operand.  */
 290   PROCESS_OPTIONS_UNKNOWN_IS_OPERAND,
 291 };
 292
 293 /* Process ARGS, using OPTIONS_GROUP as valid options.  Returns true
 294    if the string has been fully parsed and there are no operands to
 295    handle by the caller.  Return false if options were parsed, and
 296    *ARGS now points at the first operand.  */
 297 extern bool process_options
 298   (const char **args,
 299    process_options_mode mode,
 300    gdb::array_view<const option_def_group> options_group);
 301
 302 /* Complete ARGS on options listed by OPTIONS_GROUP.  Returns true if
 303    the string has been fully parsed and there are no operands to
 304    handle by the caller.  Return false if options were parsed, and
 305    *ARGS now points at the first operand.  */
 306 extern bool complete_options
 307   (completion_tracker &tracker,
 308    const char **args,
 309    process_options_mode mode,
 310    gdb::array_view<const option_def_group> options_group);
 311
 312 /* Complete on all options listed by OPTIONS_GROUP.  */
 313 extern void
 314   complete_on_all_options (completion_tracker &tracker,
 315                            gdb::array_view<const option_def_group> options_group);
 316
 317 /* Return a string with the result of replacing %OPTIONS% in HELP_TMLP
 318    with an auto-generated "help" string fragment for all the options
 319    in OPTIONS_GROUP.  */
 320 extern std::string build_help
 321   (const char *help_tmpl,
 322    gdb::array_view<const option_def_group> options_group);
 323
 324 /* Install set/show commands for options defined in OPTIONS.  DATA is
 325    a pointer to the structure that holds the data associated with the
 326    OPTIONS array.  */
 327 extern void add_setshow_cmds_for_options (command_class cmd_class, void *data,
 328                                           gdb::array_view<const option_def> options,
 329                                           struct cmd_list_element **set_list,
 330                                           struct cmd_list_element **show_list);
 331
 332 } /* namespace option */
 333 } /* namespace gdb */
 334
 335 #endif /* CLI_OPTION_H */