contrib/llvm/tools/lldb/include/lldb/Interpreter/Options.h

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