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