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