Options.h revision 8f00907e68af707b7728901f1ea1d9c40add5168
1//===-- Options.h -----------------------------------------------*- C++ -*-===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9 10#ifndef liblldb_Options_h_ 11#define liblldb_Options_h_ 12 13// C Includes 14#include <getopt.h> 15 16// C++ Includes 17#include <set> 18#include <vector> 19 20// Other libraries and framework includes 21// Project includes 22#include "lldb/lldb-private.h" 23#include "lldb/lldb-defines.h" 24#include "lldb/Interpreter/Args.h" 25 26namespace lldb_private { 27 28 static inline bool 29 isprint8 (int ch) 30 { 31 if (ch & 0xffffff00u) 32 return false; 33 return isprint(ch); 34 } 35 36 37//---------------------------------------------------------------------- 38/// @class Options Options.h "lldb/Interpreter/Options.h" 39/// @brief A command line option parsing protocol class. 40/// 41/// Options is designed to be subclassed to contain all needed 42/// options for a given command. The options can be parsed by calling: 43/// \code 44/// Error Args::ParseOptions (Options &); 45/// \endcode 46/// 47/// The options are specified using the format defined for the libc 48/// options parsing function getopt_long: 49/// \code 50/// #include <getopt.h> 51/// int getopt_long(int argc, char * const *argv, const char *optstring, const struct option *longopts, int *longindex); 52/// \endcode 53/// 54/// Example code: 55/// \code 56/// #include <getopt.h> 57/// #include <string> 58/// 59/// class CommandOptions : public Options 60/// { 61/// public: 62/// virtual struct option * 63/// GetLongOptions() { 64/// return g_options; 65/// } 66/// 67/// virtual Error 68/// SetOptionValue (uint32_t option_idx, int option_val, const char *option_arg) 69/// { 70/// Error error; 71/// switch (option_val) 72/// { 73/// case 'g': debug = true; break; 74/// case 'v': verbose = true; break; 75/// case 'l': log_file = option_arg; break; 76/// case 'f': log_flags = strtoull(option_arg, NULL, 0); break; 77/// default: 78/// error.SetErrorStringWithFormat("unrecognized short option %c", option_val); 79/// break; 80/// } 81/// 82/// return error; 83/// } 84/// 85/// CommandOptions (CommandInterpreter &interpreter) : debug (true), verbose (false), log_file (), log_flags (0) 86/// {} 87/// 88/// bool debug; 89/// bool verbose; 90/// std::string log_file; 91/// uint32_t log_flags; 92/// 93/// static struct option g_options[]; 94/// 95/// }; 96/// 97/// struct option CommandOptions::g_options[] = 98/// { 99/// { "debug", no_argument, NULL, 'g' }, 100/// { "log-file", required_argument, NULL, 'l' }, 101/// { "log-flags", required_argument, NULL, 'f' }, 102/// { "verbose", no_argument, NULL, 'v' }, 103/// { NULL, 0, NULL, 0 } 104/// }; 105/// 106/// int main (int argc, const char **argv, const char **envp) 107/// { 108/// CommandOptions options; 109/// Args main_command; 110/// main_command.SetArguments(argc, argv, false); 111/// main_command.ParseOptions(options); 112/// 113/// if (options.verbose) 114/// { 115/// std::cout << "verbose is on" << std::endl; 116/// } 117/// } 118/// \endcode 119//---------------------------------------------------------------------- 120class Options 121{ 122public: 123 124 Options (CommandInterpreter &interpreter); 125 126 virtual 127 ~Options (); 128 129 void 130 BuildGetoptTable (); 131 132 void 133 BuildValidOptionSets (); 134 135 uint32_t 136 NumCommandOptions (); 137 138 //------------------------------------------------------------------ 139 /// Get the option definitions to use when parsing Args options. 140 /// 141 /// @see Args::ParseOptions (Options&) 142 /// @see man getopt_long 143 //------------------------------------------------------------------ 144 struct option * 145 GetLongOptions (); 146 147 // This gets passed the short option as an integer... 148 void 149 OptionSeen (int short_option); 150 151 bool 152 VerifyOptions (CommandReturnObject &result); 153 154 // Verify that the options given are in the options table and can 155 // be used together, but there may be some required options that are 156 // missing (used to verify options that get folded into command aliases). 157 158 bool 159 VerifyPartialOptions (CommandReturnObject &result); 160 161 void 162 OutputFormattedUsageText (Stream &strm, 163 const char *text, 164 uint32_t output_max_columns); 165 166 void 167 GenerateOptionUsage (Stream &strm, 168 CommandObject *cmd); 169 170 bool 171 SupportsLongOption (const char *long_option); 172 173 // The following two pure virtual functions must be defined by every 174 // class that inherits from this class. 175 176 virtual const OptionDefinition* 177 GetDefinitions () { return NULL; } 178 179 // Call this prior to parsing any options. This call will call the 180 // subclass OptionParsingStarting() and will avoid the need for all 181 // OptionParsingStarting() function instances from having to call the 182 // Option::OptionParsingStarting() like they did before. This was error 183 // prone and subclasses shouldn't have to do it. 184 void 185 NotifyOptionParsingStarting (); 186 187 Error 188 NotifyOptionParsingFinished (); 189 190 //------------------------------------------------------------------ 191 /// Set the value of an option. 192 /// 193 /// @param[in] option_idx 194 /// The index into the "struct option" array that was returned 195 /// by Options::GetLongOptions(). 196 /// 197 /// @param[in] option_arg 198 /// The argument value for the option that the user entered, or 199 /// NULL if there is no argument for the current option. 200 /// 201 /// 202 /// @see Args::ParseOptions (Options&) 203 /// @see man getopt_long 204 //------------------------------------------------------------------ 205 virtual Error 206 SetOptionValue (uint32_t option_idx, const char *option_arg) = 0; 207 208 //------------------------------------------------------------------ 209 /// Handles the generic bits of figuring out whether we are in an 210 /// option, and if so completing it. 211 /// 212 /// @param[in] input 213 /// The command line parsed into words 214 /// 215 /// @param[in] cursor_index 216 /// The index in \ainput of the word in which the cursor lies. 217 /// 218 /// @param[in] char_pos 219 /// The character position of the cursor in its argument word. 220 /// 221 /// @param[in] match_start_point 222 /// @param[in] match_return_elements 223 /// See CommandObject::HandleCompletions for a description of 224 /// how these work. 225 /// 226 /// @param[in] interpreter 227 /// The interpreter that's doing the completing. 228 /// 229 /// @param[out] word_complete 230 /// \btrue if this is a complete option value (a space will be 231 /// inserted after the completion.) \b false otherwise. 232 /// 233 /// @param[out] matches 234 /// The array of matches returned. 235 /// 236 /// FIXME: This is the wrong return value, since we also need to 237 /// make a distinction between total number of matches, and the 238 /// window the user wants returned. 239 /// 240 /// @return 241 /// \btrue if we were in an option, \bfalse otherwise. 242 //------------------------------------------------------------------ 243 bool 244 HandleOptionCompletion (Args &input, 245 OptionElementVector &option_map, 246 int cursor_index, 247 int char_pos, 248 int match_start_point, 249 int max_return_elements, 250 bool &word_complete, 251 lldb_private::StringList &matches); 252 253 //------------------------------------------------------------------ 254 /// Handles the generic bits of figuring out whether we are in an 255 /// option, and if so completing it. 256 /// 257 /// @param[in] interpreter 258 /// The command interpreter doing the completion. 259 /// 260 /// @param[in] input 261 /// The command line parsed into words 262 /// 263 /// @param[in] cursor_index 264 /// The index in \ainput of the word in which the cursor lies. 265 /// 266 /// @param[in] char_pos 267 /// The character position of the cursor in its argument word. 268 /// 269 /// @param[in] opt_element_vector 270 /// The results of the options parse of \a input. 271 /// 272 /// @param[in] opt_element_index 273 /// The position in \a opt_element_vector of the word in \a 274 /// input containing the cursor. 275 /// 276 /// @param[in] match_start_point 277 /// @param[in] match_return_elements 278 /// See CommandObject::HandleCompletions for a description of 279 /// how these work. 280 /// 281 /// @param[out] word_complete 282 /// \btrue if this is a complete option value (a space will 283 /// be inserted after the completion.) \bfalse otherwise. 284 /// 285 /// @param[out] matches 286 /// The array of matches returned. 287 /// 288 /// FIXME: This is the wrong return value, since we also need to 289 /// make a distinction between total number of matches, and the 290 /// window the user wants returned. 291 /// 292 /// @return 293 /// \btrue if we were in an option, \bfalse otherwise. 294 //------------------------------------------------------------------ 295 virtual bool 296 HandleOptionArgumentCompletion (Args &input, 297 int cursor_index, 298 int char_pos, 299 OptionElementVector &opt_element_vector, 300 int opt_element_index, 301 int match_start_point, 302 int max_return_elements, 303 bool &word_complete, 304 StringList &matches); 305 306protected: 307 // This is a set of options expressed as indexes into the options table for this Option. 308 typedef std::set<int> OptionSet; 309 typedef std::vector<OptionSet> OptionSetVector; 310 311 CommandInterpreter &m_interpreter; 312 std::vector<struct option> m_getopt_table; 313 OptionSet m_seen_options; 314 OptionSetVector m_required_options; 315 OptionSetVector m_optional_options; 316 317 OptionSetVector &GetRequiredOptions () 318 { 319 BuildValidOptionSets(); 320 return m_required_options; 321 } 322 323 OptionSetVector &GetOptionalOptions () 324 { 325 BuildValidOptionSets(); 326 return m_optional_options; 327 } 328 329 bool 330 IsASubset (const OptionSet& set_a, const OptionSet& set_b); 331 332 size_t 333 OptionsSetDiff (const OptionSet &set_a, const OptionSet &set_b, OptionSet &diffs); 334 335 void 336 OptionsSetUnion (const OptionSet &set_a, const OptionSet &set_b, OptionSet &union_set); 337 338 // Subclasses must reset their option values prior to starting a new 339 // option parse. Each subclass must override this function and revert 340 // all option settings to default values. 341 virtual void 342 OptionParsingStarting () = 0; 343 344 virtual Error 345 OptionParsingFinished () 346 { 347 // If subclasses need to know when the options are done being parsed 348 // they can implement this function to do extra checking 349 Error error; 350 return error; 351 } 352}; 353 354 class OptionGroup 355 { 356 public: 357 OptionGroup () 358 { 359 } 360 361 virtual 362 ~OptionGroup () 363 { 364 } 365 366 virtual uint32_t 367 GetNumDefinitions () = 0; 368 369 virtual const OptionDefinition* 370 GetDefinitions () = 0; 371 372 virtual Error 373 SetOptionValue (CommandInterpreter &interpreter, 374 uint32_t option_idx, 375 const char *option_value) = 0; 376 377 virtual void 378 OptionParsingStarting (CommandInterpreter &interpreter) = 0; 379 380 virtual Error 381 OptionParsingFinished (CommandInterpreter &interpreter) 382 { 383 // If subclasses need to know when the options are done being parsed 384 // they can implement this function to do extra checking 385 Error error; 386 return error; 387 } 388 }; 389 390 class OptionGroupOptions : public Options 391 { 392 public: 393 394 OptionGroupOptions (CommandInterpreter &interpreter) : 395 Options (interpreter), 396 m_option_defs (), 397 m_option_infos (), 398 m_did_finalize (false) 399 { 400 } 401 402 virtual 403 ~OptionGroupOptions () 404 { 405 } 406 407 408 //---------------------------------------------------------------------- 409 /// Append options from a OptionGroup class. 410 /// 411 /// Append all options from \a group using the exact same option groups 412 /// that each option is defined with. 413 /// 414 /// @param[in] group 415 /// A group of options to take option values from and copy their 416 /// definitions into this class. 417 //---------------------------------------------------------------------- 418 void 419 Append (OptionGroup* group); 420 421 //---------------------------------------------------------------------- 422 /// Append options from a OptionGroup class. 423 /// 424 /// Append options from \a group that have a usage mask that has any bits 425 /// in "src_mask" set. After the option definition is copied into the 426 /// options definitions in this class, set the usage_mask to "dst_mask". 427 /// 428 /// @param[in] group 429 /// A group of options to take option values from and copy their 430 /// definitions into this class. 431 /// 432 /// @param[in] src_mask 433 /// When copying options from \a group, you might only want some of 434 /// the options to be appended to this group. This mask allows you 435 /// to control which options from \a group get added. It also allows 436 /// you to specify the same options from \a group multiple times 437 /// for different option sets. 438 /// 439 /// @param[in] dst_mask 440 /// Set the usage mask for any copied options to \a dst_mask after 441 /// copying the option definition. 442 //---------------------------------------------------------------------- 443 void 444 Append (OptionGroup* group, 445 uint32_t src_mask, 446 uint32_t dst_mask); 447 448 void 449 Finalize (); 450 451 virtual Error 452 SetOptionValue (uint32_t option_idx, 453 const char *option_arg); 454 455 virtual void 456 OptionParsingStarting (); 457 458 virtual Error 459 OptionParsingFinished (); 460 461 const OptionDefinition* 462 GetDefinitions () 463 { 464 assert (m_did_finalize); 465 return &m_option_defs[0]; 466 } 467 struct OptionInfo 468 { 469 OptionInfo (OptionGroup* g, uint32_t i) : 470 option_group (g), 471 option_index (i) 472 { 473 } 474 OptionGroup* option_group; // The group that this option came from 475 uint32_t option_index; // The original option index from the OptionGroup 476 }; 477 typedef std::vector<OptionInfo> OptionInfos; 478 479 std::vector<OptionDefinition> m_option_defs; 480 OptionInfos m_option_infos; 481 bool m_did_finalize; 482 }; 483 484 485} // namespace lldb_private 486 487#endif // liblldb_Options_h_ 488