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 #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
  26 namespace 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_only:
  49 /// \code
  50 ///     #include <getopt.h>
  51 ///     int getopt_long_only(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 //----------------------------------------------------------------------
 120 class Options
 121 {
 122 public:
 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_only
 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_only
 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
 306 protected:
 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_