1 //===-- Options.h -----------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Options_h_
11 #define liblldb_Options_h_
19 // Other libraries and framework includes
21 #include "lldb/lldb-private.h"
22 #include "lldb/lldb-defines.h"
23 #include "lldb/Interpreter/Args.h"
25 namespace lldb_private {
36 //----------------------------------------------------------------------
37 /// @class Options Options.h "lldb/Interpreter/Options.h"
38 /// @brief A command line option parsing protocol class.
40 /// Options is designed to be subclassed to contain all needed
41 /// options for a given command. The options can be parsed by calling:
43 /// Error Args::ParseOptions (Options &);
46 /// The options are specified using the format defined for the libc
47 /// options parsing function getopt_long_only:
49 /// #include <getopt.h>
50 /// int getopt_long_only(int argc, char * const *argv, const char *optstring, const struct option *longopts, int *longindex);
55 /// #include <getopt.h>
58 /// class CommandOptions : public Options
61 /// virtual struct option *
62 /// GetLongOptions() {
67 /// SetOptionValue (uint32_t option_idx, int option_val, const char *option_arg)
70 /// switch (option_val)
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, NULL, 0); break;
77 /// error.SetErrorStringWithFormat("unrecognized short option %c", option_val);
84 /// CommandOptions (CommandInterpreter &interpreter) : debug (true), verbose (false), log_file (), log_flags (0)
89 /// std::string log_file;
90 /// uint32_t log_flags;
92 /// static struct option g_options[];
96 /// struct option CommandOptions::g_options[] =
98 /// { "debug", no_argument, NULL, 'g' },
99 /// { "log-file", required_argument, NULL, 'l' },
100 /// { "log-flags", required_argument, NULL, 'f' },
101 /// { "verbose", no_argument, NULL, 'v' },
102 /// { NULL, 0, NULL, 0 }
105 /// int main (int argc, const char **argv, const char **envp)
107 /// CommandOptions options;
108 /// Args main_command;
109 /// main_command.SetArguments(argc, argv, false);
110 /// main_command.ParseOptions(options);
112 /// if (options.verbose)
114 /// std::cout << "verbose is on" << std::endl;
118 //----------------------------------------------------------------------
123 Options (CommandInterpreter &interpreter);
132 BuildValidOptionSets ();
135 NumCommandOptions ();
137 //------------------------------------------------------------------
138 /// Get the option definitions to use when parsing Args options.
140 /// @see Args::ParseOptions (Options&)
141 /// @see man getopt_long_only
142 //------------------------------------------------------------------
146 // This gets passed the short option as an integer...
148 OptionSeen (int short_option);
151 VerifyOptions (CommandReturnObject &result);
153 // Verify that the options given are in the options table and can
154 // be used together, but there may be some required options that are
155 // missing (used to verify options that get folded into command aliases).
158 VerifyPartialOptions (CommandReturnObject &result);
161 OutputFormattedUsageText (Stream &strm,
162 const OptionDefinition &option_def,
163 uint32_t output_max_columns);
166 GenerateOptionUsage (Stream &strm,
170 SupportsLongOption (const char *long_option);
172 // The following two pure virtual functions must be defined by every
173 // class that inherits from this class.
175 virtual const OptionDefinition*
176 GetDefinitions () { return NULL; }
178 // Call this prior to parsing any options. This call will call the
179 // subclass OptionParsingStarting() and will avoid the need for all
180 // OptionParsingStarting() function instances from having to call the
181 // Option::OptionParsingStarting() like they did before. This was error
182 // prone and subclasses shouldn't have to do it.
184 NotifyOptionParsingStarting ();
187 NotifyOptionParsingFinished ();
189 //------------------------------------------------------------------
190 /// Set the value of an option.
192 /// @param[in] option_idx
193 /// The index into the "struct option" array that was returned
194 /// by Options::GetLongOptions().
196 /// @param[in] option_arg
197 /// The argument value for the option that the user entered, or
198 /// NULL if there is no argument for the current option.
201 /// @see Args::ParseOptions (Options&)
202 /// @see man getopt_long_only
203 //------------------------------------------------------------------
205 SetOptionValue (uint32_t option_idx, const char *option_arg) = 0;
207 //------------------------------------------------------------------
208 /// Handles the generic bits of figuring out whether we are in an
209 /// option, and if so completing it.
212 /// The command line parsed into words
214 /// @param[in] cursor_index
215 /// The index in \ainput of the word in which the cursor lies.
217 /// @param[in] char_pos
218 /// The character position of the cursor in its argument word.
220 /// @param[in] match_start_point
221 /// @param[in] match_return_elements
222 /// See CommandObject::HandleCompletions for a description of
225 /// @param[in] interpreter
226 /// The interpreter that's doing the completing.
228 /// @param[out] word_complete
229 /// \btrue if this is a complete option value (a space will be
230 /// inserted after the completion.) \b false otherwise.
232 /// @param[out] matches
233 /// The array of matches returned.
235 /// FIXME: This is the wrong return value, since we also need to
236 /// make a distinction between total number of matches, and the
237 /// window the user wants returned.
240 /// \btrue if we were in an option, \bfalse otherwise.
241 //------------------------------------------------------------------
243 HandleOptionCompletion (Args &input,
244 OptionElementVector &option_map,
247 int match_start_point,
248 int max_return_elements,
250 lldb_private::StringList &matches);
252 //------------------------------------------------------------------
253 /// Handles the generic bits of figuring out whether we are in an
254 /// option, and if so completing it.
256 /// @param[in] interpreter
257 /// The command interpreter doing the completion.
260 /// The command line parsed into words
262 /// @param[in] cursor_index
263 /// The index in \ainput of the word in which the cursor lies.
265 /// @param[in] char_pos
266 /// The character position of the cursor in its argument word.
268 /// @param[in] opt_element_vector
269 /// The results of the options parse of \a input.
271 /// @param[in] opt_element_index
272 /// The position in \a opt_element_vector of the word in \a
273 /// input containing the cursor.
275 /// @param[in] match_start_point
276 /// @param[in] match_return_elements
277 /// See CommandObject::HandleCompletions for a description of
280 /// @param[out] word_complete
281 /// \btrue if this is a complete option value (a space will
282 /// be inserted after the completion.) \bfalse otherwise.
284 /// @param[out] matches
285 /// The array of matches returned.
287 /// FIXME: This is the wrong return value, since we also need to
288 /// make a distinction between total number of matches, and the
289 /// window the user wants returned.
292 /// \btrue if we were in an option, \bfalse otherwise.
293 //------------------------------------------------------------------
295 HandleOptionArgumentCompletion (Args &input,
298 OptionElementVector &opt_element_vector,
299 int opt_element_index,
300 int match_start_point,
301 int max_return_elements,
303 StringList &matches);
308 return m_interpreter;
312 // This is a set of options expressed as indexes into the options table for this Option.
313 typedef std::set<int> OptionSet;
314 typedef std::vector<OptionSet> OptionSetVector;
316 CommandInterpreter &m_interpreter;
317 std::vector<Option> m_getopt_table;
318 OptionSet m_seen_options;
319 OptionSetVector m_required_options;
320 OptionSetVector m_optional_options;
322 OptionSetVector &GetRequiredOptions ()
324 BuildValidOptionSets();
325 return m_required_options;
328 OptionSetVector &GetOptionalOptions ()
330 BuildValidOptionSets();
331 return m_optional_options;
335 IsASubset (const OptionSet& set_a, const OptionSet& set_b);
338 OptionsSetDiff (const OptionSet &set_a, const OptionSet &set_b, OptionSet &diffs);
341 OptionsSetUnion (const OptionSet &set_a, const OptionSet &set_b, OptionSet &union_set);
343 // Subclasses must reset their option values prior to starting a new
344 // option parse. Each subclass must override this function and revert
345 // all option settings to default values.
347 OptionParsingStarting () = 0;
350 OptionParsingFinished ()
352 // If subclasses need to know when the options are done being parsed
353 // they can implement this function to do extra checking
372 GetNumDefinitions () = 0;
374 virtual const OptionDefinition*
375 GetDefinitions () = 0;
378 SetOptionValue (CommandInterpreter &interpreter,
380 const char *option_value) = 0;
383 OptionParsingStarting (CommandInterpreter &interpreter) = 0;
386 OptionParsingFinished (CommandInterpreter &interpreter)
388 // If subclasses need to know when the options are done being parsed
389 // they can implement this function to do extra checking
395 class OptionGroupOptions : public Options
399 OptionGroupOptions (CommandInterpreter &interpreter) :
400 Options (interpreter),
403 m_did_finalize (false)
408 ~OptionGroupOptions ()
413 //----------------------------------------------------------------------
414 /// Append options from a OptionGroup class.
416 /// Append all options from \a group using the exact same option groups
417 /// that each option is defined with.
420 /// A group of options to take option values from and copy their
421 /// definitions into this class.
422 //----------------------------------------------------------------------
424 Append (OptionGroup* group);
426 //----------------------------------------------------------------------
427 /// Append options from a OptionGroup class.
429 /// Append options from \a group that have a usage mask that has any bits
430 /// in "src_mask" set. After the option definition is copied into the
431 /// options definitions in this class, set the usage_mask to "dst_mask".
434 /// A group of options to take option values from and copy their
435 /// definitions into this class.
437 /// @param[in] src_mask
438 /// When copying options from \a group, you might only want some of
439 /// the options to be appended to this group. This mask allows you
440 /// to control which options from \a group get added. It also allows
441 /// you to specify the same options from \a group multiple times
442 /// for different option sets.
444 /// @param[in] dst_mask
445 /// Set the usage mask for any copied options to \a dst_mask after
446 /// copying the option definition.
447 //----------------------------------------------------------------------
449 Append (OptionGroup* group,
459 return m_did_finalize;
463 SetOptionValue (uint32_t option_idx,
464 const char *option_arg);
467 OptionParsingStarting ();
470 OptionParsingFinished ();
472 const OptionDefinition*
475 assert (m_did_finalize);
476 return &m_option_defs[0];
480 GetGroupWithOption (char short_opt);
484 OptionInfo (OptionGroup* g, uint32_t i) :
489 OptionGroup* option_group; // The group that this option came from
490 uint32_t option_index; // The original option index from the OptionGroup
492 typedef std::vector<OptionInfo> OptionInfos;
494 std::vector<OptionDefinition> m_option_defs;
495 OptionInfos m_option_infos;
500 } // namespace lldb_private
502 #endif // liblldb_Options_h_