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/Utility/Args.h"
  21 #include "lldb/Utility/CompletionRequest.h"
  22 #include "lldb/Utility/Status.h"
  23 #include "lldb/lldb-defines.h"
  24 #include "lldb/lldb-private.h"
  25
  26 #include "llvm/ADT/ArrayRef.h"
  27
  28 namespace lldb_private {
  29
  30 struct Option;
  31
  32 typedef std::vector<std::tuple<std::string, int, std::string>> OptionArgVector;
  33 typedef std::shared_ptr<OptionArgVector> OptionArgVectorSP;
  34
  35 struct OptionArgElement {
  36   enum { eUnrecognizedArg = -1, eBareDash = -2, eBareDoubleDash = -3 };
  37
  38   OptionArgElement(int defs_index, int pos, int arg_pos)
  39       : opt_defs_index(defs_index), opt_pos(pos), opt_arg_pos(arg_pos) {}
  40
  41   int opt_defs_index;
  42   int opt_pos;
  43   int opt_arg_pos;
  44 };
  45
  46 typedef std::vector<OptionArgElement> OptionElementVector;
  47
  48 static inline bool isprint8(int ch) {
  49   if (ch & 0xffffff00u)
  50     return false;
  51   return isprint(ch);
  52 }
  53
  54 //----------------------------------------------------------------------
  55 /// @class Options Options.h "lldb/Interpreter/Options.h"
  56 /// A command line option parsing protocol class.
  57 ///
  58 /// Options is designed to be subclassed to contain all needed options for a
  59 /// given command. The options can be parsed by calling the Parse function.
  60 ///
  61 /// The options are specified using the format defined for the libc options
  62 /// parsing function getopt_long_only: \code
  63 ///     #include <getopt.h>
  64 ///     int getopt_long_only(int argc, char * const *argv, const char
  65 ///     *optstring, const struct option *longopts, int *longindex);
  66 /// \endcode
  67 ///
  68 //----------------------------------------------------------------------
  69 class Options {
  70 public:
  71   Options();
  72
  73   virtual ~Options();
  74
  75   void BuildGetoptTable();
  76
  77   void BuildValidOptionSets();
  78
  79   uint32_t NumCommandOptions();
  80
  81   //------------------------------------------------------------------
  82   /// Get the option definitions to use when parsing Args options.
  83   ///
  84   /// @see Args::ParseOptions (Options&)
  85   /// @see man getopt_long_only
  86   //------------------------------------------------------------------
  87   Option *GetLongOptions();
  88
  89   // This gets passed the short option as an integer...
  90   void OptionSeen(int short_option);
  91
  92   bool VerifyOptions(CommandReturnObject &result);
  93
  94   // Verify that the options given are in the options table and can be used
  95   // together, but there may be some required options that are missing (used to
  96   // verify options that get folded into command aliases).
  97   bool VerifyPartialOptions(CommandReturnObject &result);
  98
  99   void OutputFormattedUsageText(Stream &strm,
 100                                 const OptionDefinition &option_def,
 101                                 uint32_t output_max_columns);
 102
 103   void GenerateOptionUsage(Stream &strm, CommandObject *cmd,
 104                            uint32_t screen_width);
 105
 106   bool SupportsLongOption(const char *long_option);
 107
 108   // The following two pure virtual functions must be defined by every class
 109   // that inherits from this class.
 110
 111   virtual llvm::ArrayRef<OptionDefinition> GetDefinitions() {
 112     return llvm::ArrayRef<OptionDefinition>();
 113   }
 114
 115   // Call this prior to parsing any options. This call will call the subclass
 116   // OptionParsingStarting() and will avoid the need for all
 117   // OptionParsingStarting() function instances from having to call the
 118   // Option::OptionParsingStarting() like they did before. This was error prone
 119   // and subclasses shouldn't have to do it.
 120   void NotifyOptionParsingStarting(ExecutionContext *execution_context);
 121
 122   //------------------------------------------------------------------
 123   /// Parse the provided arguments.
 124   ///
 125   /// The parsed options are set via calls to SetOptionValue. In case of a
 126   /// successful parse, the function returns a copy of the input arguments
 127   /// with the parsed options removed. Otherwise, it returns an error.
 128   ///
 129   /// param[in] platform_sp
 130   ///   The platform used for option validation.  This is necessary
 131   ///   because an empty execution_context is not enough to get us
 132   ///   to a reasonable platform.  If the platform isn't given,
 133   ///   we'll try to get it from the execution context.  If we can't
 134   ///   get it from the execution context, we'll skip validation.
 135   ///
 136   /// param[in] require_validation
 137   ///   When true, it will fail option parsing if validation could
 138   ///   not occur due to not having a platform.
 139   //------------------------------------------------------------------
 140   llvm::Expected<Args> Parse(const Args &args,
 141                              ExecutionContext *execution_context,
 142                              lldb::PlatformSP platform_sp,
 143                              bool require_validation);
 144
 145   llvm::Expected<Args> ParseAlias(const Args &args,
 146                                   OptionArgVector *option_arg_vector,
 147                                   std::string &input_line);
 148
 149   OptionElementVector ParseForCompletion(const Args &args,
 150                                          uint32_t cursor_index);
 151
 152   Status NotifyOptionParsingFinished(ExecutionContext *execution_context);
 153
 154   //------------------------------------------------------------------
 155   /// Set the value of an option.
 156   ///
 157   /// @param[in] option_idx
 158   ///     The index into the "struct option" array that was returned
 159   ///     by Options::GetLongOptions().
 160   ///
 161   /// @param[in] option_arg
 162   ///     The argument value for the option that the user entered, or
 163   ///     nullptr if there is no argument for the current option.
 164   ///
 165   /// @param[in] execution_context
 166   ///     The execution context to use for evaluating the option.
 167   ///     May be nullptr if the option is to be evaluated outside any
 168   ///     particular context.
 169   ///
 170   /// @see Args::ParseOptions (Options&)
 171   /// @see man getopt_long_only
 172   //------------------------------------------------------------------
 173   virtual Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
 174                                 ExecutionContext *execution_context) = 0;
 175
 176   //------------------------------------------------------------------
 177   /// Handles the generic bits of figuring out whether we are in an option,
 178   /// and if so completing it.
 179   ///
 180   /// @param[in/out] request
 181   ///    The completion request that we need to act upon.
 182   ///
 183   /// @param[in] interpreter
 184   ///     The interpreter that's doing the completing.
 185   ///
 186   /// FIXME: This is the wrong return value, since we also need to
 187   /// make a distinction between total number of matches, and the window the
 188   /// user wants returned.
 189   ///
 190   /// @return
 191   ///     \btrue if we were in an option, \bfalse otherwise.
 192   //------------------------------------------------------------------
 193   bool HandleOptionCompletion(lldb_private::CompletionRequest &request,
 194                               OptionElementVector &option_map,
 195                               CommandInterpreter &interpreter);
 196
 197   //------------------------------------------------------------------
 198   /// Handles the generic bits of figuring out whether we are in an option,
 199   /// and if so completing it.
 200   ///
 201   /// @param[in/out] request
 202   ///    The completion request that we need to act upon.
 203   ///
 204   /// @param[in] interpreter
 205   ///    The command interpreter doing the completion.
 206   ///
 207   /// FIXME: This is the wrong return value, since we also need to
 208   /// make a distinction between total number of matches, and the window the
 209   /// user wants returned.
 210   ///
 211   /// @return
 212   ///     \btrue if we were in an option, \bfalse otherwise.
 213   //------------------------------------------------------------------
 214   virtual bool
 215   HandleOptionArgumentCompletion(lldb_private::CompletionRequest &request,
 216                                  OptionElementVector &opt_element_vector,
 217                                  int opt_element_index,
 218                                  CommandInterpreter &interpreter);
 219
 220 protected:
 221   // This is a set of options expressed as indexes into the options table for
 222   // this Option.
 223   typedef std::set<int> OptionSet;
 224   typedef std::vector<OptionSet> OptionSetVector;
 225
 226   std::vector<Option> m_getopt_table;
 227   OptionSet m_seen_options;
 228   OptionSetVector m_required_options;
 229   OptionSetVector m_optional_options;
 230
 231   OptionSetVector &GetRequiredOptions() {
 232     BuildValidOptionSets();
 233     return m_required_options;
 234   }
 235
 236   OptionSetVector &GetOptionalOptions() {
 237     BuildValidOptionSets();
 238     return m_optional_options;
 239   }
 240
 241   bool IsASubset(const OptionSet &set_a, const OptionSet &set_b);
 242
 243   size_t OptionsSetDiff(const OptionSet &set_a, const OptionSet &set_b,
 244                         OptionSet &diffs);
 245
 246   void OptionsSetUnion(const OptionSet &set_a, const OptionSet &set_b,
 247                        OptionSet &union_set);
 248
 249   // Subclasses must reset their option values prior to starting a new option
 250   // parse. Each subclass must override this function and revert all option
 251   // settings to default values.
 252   virtual void OptionParsingStarting(ExecutionContext *execution_context) = 0;
 253
 254   virtual Status OptionParsingFinished(ExecutionContext *execution_context) {
 255     // If subclasses need to know when the options are done being parsed they
 256     // can implement this function to do extra checking
 257     Status error;
 258     return error;
 259   }
 260 };
 261
 262 class OptionGroup {
 263 public:
 264   OptionGroup() = default;
 265
 266   virtual ~OptionGroup() = default;
 267
 268   virtual llvm::ArrayRef<OptionDefinition> GetDefinitions() = 0;
 269
 270   virtual Status SetOptionValue(uint32_t option_idx,
 271                                 llvm::StringRef option_value,
 272                                 ExecutionContext *execution_context) = 0;
 273
 274   virtual void OptionParsingStarting(ExecutionContext *execution_context) = 0;
 275
 276   virtual Status OptionParsingFinished(ExecutionContext *execution_context) {
 277     // If subclasses need to know when the options are done being parsed they
 278     // can implement this function to do extra checking
 279     Status error;
 280     return error;
 281   }
 282 };
 283
 284 class OptionGroupOptions : public Options {
 285 public:
 286   OptionGroupOptions()
 287       : Options(), m_option_defs(), m_option_infos(), m_did_finalize(false) {}
 288
 289   ~OptionGroupOptions() override = default;
 290
 291   //----------------------------------------------------------------------
 292   /// Append options from a OptionGroup class.
 293   ///
 294   /// Append all options from \a group using the exact same option groups that
 295   /// each option is defined with.
 296   ///
 297   /// @param[in] group
 298   ///     A group of options to take option values from and copy their
 299   ///     definitions into this class.
 300   //----------------------------------------------------------------------
 301   void Append(OptionGroup *group);
 302
 303   //----------------------------------------------------------------------
 304   /// Append options from a OptionGroup class.
 305   ///
 306   /// Append options from \a group that have a usage mask that has any bits in
 307   /// "src_mask" set. After the option definition is copied into the options
 308   /// definitions in this class, set the usage_mask to "dst_mask".
 309   ///
 310   /// @param[in] group
 311   ///     A group of options to take option values from and copy their
 312   ///     definitions into this class.
 313   ///
 314   /// @param[in] src_mask
 315   ///     When copying options from \a group, you might only want some of
 316   ///     the options to be appended to this group. This mask allows you
 317   ///     to control which options from \a group get added. It also allows
 318   ///     you to specify the same options from \a group multiple times
 319   ///     for different option sets.
 320   ///
 321   /// @param[in] dst_mask
 322   ///     Set the usage mask for any copied options to \a dst_mask after
 323   ///     copying the option definition.
 324   //----------------------------------------------------------------------
 325   void Append(OptionGroup *group, uint32_t src_mask, uint32_t dst_mask);
 326
 327   void Finalize();
 328
 329   bool DidFinalize() { return m_did_finalize; }
 330
 331   Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
 332                         ExecutionContext *execution_context) override;
 333
 334   void OptionParsingStarting(ExecutionContext *execution_context) override;
 335
 336   Status OptionParsingFinished(ExecutionContext *execution_context) override;
 337
 338   llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
 339     assert(m_did_finalize);
 340     return m_option_defs;
 341   }
 342
 343   const OptionGroup *GetGroupWithOption(char short_opt);
 344
 345   struct OptionInfo {
 346     OptionInfo(OptionGroup *g, uint32_t i) : option_group(g), option_index(i) {}
 347     OptionGroup *option_group; // The group that this option came from
 348     uint32_t option_index;     // The original option index from the OptionGroup
 349   };
 350   typedef std::vector<OptionInfo> OptionInfos;
 351
 352   std::vector<OptionDefinition> m_option_defs;
 353   OptionInfos m_option_infos;
 354   bool m_did_finalize;
 355 };
 356
 357 } // namespace lldb_private
 358
 359 #endif // liblldb_Options_h_