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