1 /* CLI options framework, for GDB. 2 3 Copyright (C) 2017-2020 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 char **(*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 char **(*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 */ 357