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_
18 // Other libraries and framework includes
20 #include "lldb/Interpreter/Args.h"
21 #include "lldb/lldb-defines.h"
22 #include "lldb/lldb-private.h"
24 #include "llvm/ADT/ArrayRef.h"
26 namespace lldb_private {
28 static inline bool isprint8(int ch) {
34 //----------------------------------------------------------------------
35 /// @class Options Options.h "lldb/Interpreter/Options.h"
36 /// @brief A command line option parsing protocol class.
38 /// Options is designed to be subclassed to contain all needed
39 /// options for a given command. The options can be parsed by calling:
41 /// Status Args::ParseOptions (Options &);
44 /// The options are specified using the format defined for the libc
45 /// options parsing function getopt_long_only:
47 /// #include <getopt.h>
48 /// int getopt_long_only(int argc, char * const *argv, const char
49 /// *optstring, const struct option *longopts, int *longindex);
54 /// #include <getopt.h>
57 /// class CommandOptions : public Options
60 /// virtual struct option *
61 /// GetLongOptions() {
66 /// SetOptionValue (uint32_t option_idx, int option_val, const char
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, nullptr, 0); break;
77 /// error.SetErrorStringWithFormat("unrecognized short option
85 /// CommandOptions (CommandInterpreter &interpreter) : debug (true),
86 /// verbose (false), log_file (), log_flags (0)
91 /// std::string log_file;
92 /// uint32_t log_flags;
94 /// static struct option g_options[];
98 /// struct option CommandOptions::g_options[] =
100 /// { "debug", no_argument, nullptr, 'g' },
101 /// { "log-file", required_argument, nullptr, 'l' },
102 /// { "log-flags", required_argument, nullptr, 'f' },
103 /// { "verbose", no_argument, nullptr, 'v' },
104 /// { nullptr, 0, nullptr, 0 }
107 /// int main (int argc, const char **argv, const char **envp)
109 /// CommandOptions options;
110 /// Args main_command;
111 /// main_command.SetArguments(argc, argv, false);
112 /// main_command.ParseOptions(options);
114 /// if (options.verbose)
116 /// std::cout << "verbose is on" << std::endl;
120 //----------------------------------------------------------------------
127 void BuildGetoptTable();
129 void BuildValidOptionSets();
131 uint32_t NumCommandOptions();
133 //------------------------------------------------------------------
134 /// Get the option definitions to use when parsing Args options.
136 /// @see Args::ParseOptions (Options&)
137 /// @see man getopt_long_only
138 //------------------------------------------------------------------
139 Option *GetLongOptions();
141 // This gets passed the short option as an integer...
142 void OptionSeen(int short_option);
144 bool VerifyOptions(CommandReturnObject &result);
146 // Verify that the options given are in the options table and can
147 // be used together, but there may be some required options that are
148 // missing (used to verify options that get folded into command aliases).
149 bool VerifyPartialOptions(CommandReturnObject &result);
151 void OutputFormattedUsageText(Stream &strm,
152 const OptionDefinition &option_def,
153 uint32_t output_max_columns);
155 void GenerateOptionUsage(Stream &strm, CommandObject *cmd,
156 uint32_t screen_width);
158 bool SupportsLongOption(const char *long_option);
160 // The following two pure virtual functions must be defined by every
161 // class that inherits from this class.
163 virtual llvm::ArrayRef<OptionDefinition> GetDefinitions() {
164 return llvm::ArrayRef<OptionDefinition>();
167 // Call this prior to parsing any options. This call will call the
168 // subclass OptionParsingStarting() and will avoid the need for all
169 // OptionParsingStarting() function instances from having to call the
170 // Option::OptionParsingStarting() like they did before. This was error
171 // prone and subclasses shouldn't have to do it.
172 void NotifyOptionParsingStarting(ExecutionContext *execution_context);
174 Status NotifyOptionParsingFinished(ExecutionContext *execution_context);
176 //------------------------------------------------------------------
177 /// Set the value of an option.
179 /// @param[in] option_idx
180 /// The index into the "struct option" array that was returned
181 /// by Options::GetLongOptions().
183 /// @param[in] option_arg
184 /// The argument value for the option that the user entered, or
185 /// nullptr if there is no argument for the current option.
187 /// @param[in] execution_context
188 /// The execution context to use for evaluating the option.
189 /// May be nullptr if the option is to be evaluated outside any
190 /// particular context.
192 /// @see Args::ParseOptions (Options&)
193 /// @see man getopt_long_only
194 //------------------------------------------------------------------
195 virtual Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
196 ExecutionContext *execution_context) = 0;
198 //------------------------------------------------------------------
199 /// Handles the generic bits of figuring out whether we are in an
200 /// option, and if so completing it.
203 /// The command line parsed into words
205 /// @param[in] cursor_index
206 /// The index in \ainput of the word in which the cursor lies.
208 /// @param[in] char_pos
209 /// The character position of the cursor in its argument word.
211 /// @param[in] match_start_point
212 /// @param[in] match_return_elements
213 /// See CommandObject::HandleCompletions for a description of
216 /// @param[in] interpreter
217 /// The interpreter that's doing the completing.
219 /// @param[out] word_complete
220 /// \btrue if this is a complete option value (a space will be
221 /// inserted after the completion.) \b false otherwise.
223 /// @param[out] matches
224 /// The array of matches returned.
226 /// FIXME: This is the wrong return value, since we also need to
227 /// make a distinction between total number of matches, and the
228 /// window the user wants returned.
231 /// \btrue if we were in an option, \bfalse otherwise.
232 //------------------------------------------------------------------
233 bool HandleOptionCompletion(Args &input, OptionElementVector &option_map,
234 int cursor_index, int char_pos,
235 int match_start_point, int max_return_elements,
236 CommandInterpreter &interpreter,
238 lldb_private::StringList &matches);
240 //------------------------------------------------------------------
241 /// Handles the generic bits of figuring out whether we are in an
242 /// option, and if so completing it.
244 /// @param[in] interpreter
245 /// The command interpreter doing the completion.
248 /// The command line parsed into words
250 /// @param[in] cursor_index
251 /// The index in \ainput of the word in which the cursor lies.
253 /// @param[in] char_pos
254 /// The character position of the cursor in its argument word.
256 /// @param[in] opt_element_vector
257 /// The results of the options parse of \a input.
259 /// @param[in] opt_element_index
260 /// The position in \a opt_element_vector of the word in \a
261 /// input containing the cursor.
263 /// @param[in] match_start_point
264 /// @param[in] match_return_elements
265 /// See CommandObject::HandleCompletions for a description of
268 /// @param[in] interpreter
269 /// The command interpreter in which we're doing completion.
271 /// @param[out] word_complete
272 /// \btrue if this is a complete option value (a space will
273 /// be inserted after the completion.) \bfalse otherwise.
275 /// @param[out] matches
276 /// The array of matches returned.
278 /// FIXME: This is the wrong return value, since we also need to
279 /// make a distinction between total number of matches, and the
280 /// window the user wants returned.
283 /// \btrue if we were in an option, \bfalse otherwise.
284 //------------------------------------------------------------------
286 HandleOptionArgumentCompletion(Args &input, int cursor_index, int char_pos,
287 OptionElementVector &opt_element_vector,
288 int opt_element_index, int match_start_point,
289 int max_return_elements,
290 CommandInterpreter &interpreter,
291 bool &word_complete, StringList &matches);
294 // This is a set of options expressed as indexes into the options table for
296 typedef std::set<int> OptionSet;
297 typedef std::vector<OptionSet> OptionSetVector;
299 std::vector<Option> m_getopt_table;
300 OptionSet m_seen_options;
301 OptionSetVector m_required_options;
302 OptionSetVector m_optional_options;
304 OptionSetVector &GetRequiredOptions() {
305 BuildValidOptionSets();
306 return m_required_options;
309 OptionSetVector &GetOptionalOptions() {
310 BuildValidOptionSets();
311 return m_optional_options;
314 bool IsASubset(const OptionSet &set_a, const OptionSet &set_b);
316 size_t OptionsSetDiff(const OptionSet &set_a, const OptionSet &set_b,
319 void OptionsSetUnion(const OptionSet &set_a, const OptionSet &set_b,
320 OptionSet &union_set);
322 // Subclasses must reset their option values prior to starting a new
323 // option parse. Each subclass must override this function and revert
324 // all option settings to default values.
325 virtual void OptionParsingStarting(ExecutionContext *execution_context) = 0;
327 virtual Status OptionParsingFinished(ExecutionContext *execution_context) {
328 // If subclasses need to know when the options are done being parsed
329 // they can implement this function to do extra checking
337 OptionGroup() = default;
339 virtual ~OptionGroup() = default;
341 virtual llvm::ArrayRef<OptionDefinition> GetDefinitions() = 0;
343 virtual Status SetOptionValue(uint32_t option_idx,
344 llvm::StringRef option_value,
345 ExecutionContext *execution_context) = 0;
347 virtual void OptionParsingStarting(ExecutionContext *execution_context) = 0;
349 virtual Status OptionParsingFinished(ExecutionContext *execution_context) {
350 // If subclasses need to know when the options are done being parsed
351 // they can implement this function to do extra checking
357 class OptionGroupOptions : public Options {
360 : Options(), m_option_defs(), m_option_infos(), m_did_finalize(false) {}
362 ~OptionGroupOptions() override = default;
364 //----------------------------------------------------------------------
365 /// Append options from a OptionGroup class.
367 /// Append all options from \a group using the exact same option groups
368 /// that each option is defined with.
371 /// A group of options to take option values from and copy their
372 /// definitions into this class.
373 //----------------------------------------------------------------------
374 void Append(OptionGroup *group);
376 //----------------------------------------------------------------------
377 /// Append options from a OptionGroup class.
379 /// Append options from \a group that have a usage mask that has any bits
380 /// in "src_mask" set. After the option definition is copied into the
381 /// options definitions in this class, set the usage_mask to "dst_mask".
384 /// A group of options to take option values from and copy their
385 /// definitions into this class.
387 /// @param[in] src_mask
388 /// When copying options from \a group, you might only want some of
389 /// the options to be appended to this group. This mask allows you
390 /// to control which options from \a group get added. It also allows
391 /// you to specify the same options from \a group multiple times
392 /// for different option sets.
394 /// @param[in] dst_mask
395 /// Set the usage mask for any copied options to \a dst_mask after
396 /// copying the option definition.
397 //----------------------------------------------------------------------
398 void Append(OptionGroup *group, uint32_t src_mask, uint32_t dst_mask);
402 bool DidFinalize() { return m_did_finalize; }
404 Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
405 ExecutionContext *execution_context) override;
407 void OptionParsingStarting(ExecutionContext *execution_context) override;
409 Status OptionParsingFinished(ExecutionContext *execution_context) override;
411 llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
412 assert(m_did_finalize);
413 return m_option_defs;
416 const OptionGroup *GetGroupWithOption(char short_opt);
419 OptionInfo(OptionGroup *g, uint32_t i) : option_group(g), option_index(i) {}
420 OptionGroup *option_group; // The group that this option came from
421 uint32_t option_index; // The original option index from the OptionGroup
423 typedef std::vector<OptionInfo> OptionInfos;
425 std::vector<OptionDefinition> m_option_defs;
426 OptionInfos m_option_infos;
430 } // namespace lldb_private
432 #endif // liblldb_Options_h_