Options.h revision b344843f75ef893762c93fd0a22d2d45712ce74d 
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
26namespace lldb_private {
27
28//----------------------------------------------------------------------
29/// @class Options Options.h "lldb/Interpreter/Options.h"
30/// @brief A command line option parsing protocol class.
31///
32/// Options is designed to be subclassed to contain all needed
33/// options for a given command. The options can be parsed by calling:
34/// \code
35///     Error Args::ParseOptions (Options &);
36/// \endcode
37///
38/// The options are specified using the format defined for the libc
39/// options parsing function getopt_long:
40/// \code
41///     #include <getopt.h>
42///     int getopt_long(int argc, char * const *argv, const char *optstring, const struct option *longopts, int *longindex);
43/// \endcode
44///
45/// Example code:
46/// \code
47///     #include <getopt.h>
48///     #include <string>
49///
50///     class CommandOptions : public Options
51///     {
52///     public:
53///         virtual struct option *
54///         GetLongOptions() {
55///             return g_options;
56///         }
57///
58///         virtual Error
59///         SetOptionValue (int option_idx, int option_val, const char *option_arg)
60///         {
61///             Error error;
62///             switch (option_val)
63///             {
64///             case 'g': debug = true; break;
65///             case 'v': verbose = true; break;
66///             case 'l': log_file = option_arg; break;
67///             case 'f': log_flags = strtoull(option_arg, NULL, 0); break;
68///             default:
69///                 error.SetErrorStringWithFormat("unrecognized short option %c", option_val);
70///                 break;
71///             }
72///
73///             return error;
74///         }
75///
76///         CommandOptions () : debug (true), verbose (false), log_file (), log_flags (0)
77///         {}
78///
79///         bool debug;
80///         bool verbose;
81///         std::string log_file;
82///         uint32_t log_flags;
83///
84///         static struct option g_options[];
85///
86///     };
87///
88///     struct option CommandOptions::g_options[] =
89///     {
90///         { "debug",              no_argument,        NULL,   'g' },
91///         { "log-file",           required_argument,  NULL,   'l' },
92///         { "log-flags",          required_argument,  NULL,   'f' },
93///         { "verbose",            no_argument,        NULL,   'v' },
94///         { NULL,                 0,                  NULL,   0   }
95///     };
96///
97///     int main (int argc, const char **argv, const char **envp)
98///     {
99///         CommandOptions options;
100///         Args main_command;
101///         main_command.SetArguments(argc, argv, false);
102///         main_command.ParseOptions(options);
103///
104///         if (options.verbose)
105///         {
106///             std::cout << "verbose is on" << std::endl;
107///         }
108///     }
109/// \endcode
110//----------------------------------------------------------------------
111class Options
112{
113public:
114
115    Options ();
116
117    virtual
118    ~Options ();
119
120    void
121    BuildGetoptTable ();
122
123    void
124    BuildValidOptionSets ();
125
126    uint32_t
127    NumCommandOptions ();
128
129    //------------------------------------------------------------------
130    /// Get the option definitions to use when parsing Args options.
131    ///
132    /// @see Args::ParseOptions (Options&)
133    /// @see man getopt_long
134    //------------------------------------------------------------------
135    struct option *
136    GetLongOptions ();
137
138    // This gets passed the short option as an integer...
139    void
140    OptionSeen (int short_option);
141
142    bool
143    VerifyOptions (CommandReturnObject &result);
144
145    // Verify that the options given are in the options table and can be used together, but there may be
146    // some required options that are missing (used to verify options that get folded into command aliases).
147
148    bool
149    VerifyPartialOptions (CommandReturnObject &result);
150
151//    void
152//    BuildAliasOptions (OptionArgVector *option_arg_vector, Args args);
153
154    void
155    OutputFormattedUsageText (Stream &strm,
156                              const char *text,
157                              uint32_t output_max_columns);
158
159    void
160    GenerateOptionUsage (CommandInterpreter &interpreter,
161                         Stream &strm,
162                         CommandObject *cmd);
163
164    // The following two pure virtual functions must be defined by every class that inherits from
165    // this class.
166
167    virtual const OptionDefinition*
168    GetDefinitions () { return NULL; }
169
170    virtual void
171    ResetOptionValues ();
172
173    //------------------------------------------------------------------
174    /// Set the value of an option.
175    ///
176    /// @param[in] option_idx
177    ///     The index into the "struct option" array that was returned
178    ///     by Options::GetLongOptions().
179    ///
180    /// @param[in] option_arg
181    ///     The argument value for the option that the user entered, or
182    ///     NULL if there is no argument for the current option.
183    ///
184    ///
185    /// @see Args::ParseOptions (Options&)
186    /// @see man getopt_long
187    //------------------------------------------------------------------
188    virtual Error
189    SetOptionValue (int option_idx, const char *option_arg) = 0;
190
191    //------------------------------------------------------------------
192    ///  Handles the generic bits of figuring out whether we are in an option, and if so completing
193    /// it.
194    ///
195    /// @param[in] input
196    ///    The command line parsed into words
197    ///
198    /// @param[in] cursor_index
199    ///     The index in \ainput of the word in which the cursor lies.
200    ///
201    /// @param[in] char_pos
202    ///     The character position of the cursor in its argument word.
203    ///
204    /// @param[in] match_start_point
205    /// @param[in] match_return_elements
206    ///     See CommandObject::HandleCompletions for a description of how these work.
207    ///
208    /// @param[in] interpreter
209    ///     The interpreter that's doing the completing.
210    ///
211    /// @param[out] word_complete
212    ///     \btrue if this is a complete option value (a space will be inserted after the
213    ///     completion.)  \bfalse otherwise.
214    ///
215    /// @param[out] matches
216    ///     The array of matches returned.
217    ///
218    /// FIXME: This is the wrong return value, since we also need to make a distinction between
219    /// total number of matches, and the window the user wants returned.
220    ///
221    /// @return
222    ///     \btrue if we were in an option, \bfalse otherwise.
223    //------------------------------------------------------------------
224    bool
225    HandleOptionCompletion (CommandInterpreter &interpreter,
226                            Args &input,
227                            OptionElementVector &option_map,
228                            int cursor_index,
229                            int char_pos,
230                            int match_start_point,
231                            int max_return_elements,
232                            bool &word_complete,
233                            lldb_private::StringList &matches);
234
235    //------------------------------------------------------------------
236    ///  Handles the generic bits of figuring out whether we are in an option, and if so completing
237    /// it.
238    ///
239    /// @param[in] interpreter
240    ///    The command interpreter doing the completion.
241    ///
242    /// @param[in] input
243    ///    The command line parsed into words
244    ///
245    /// @param[in] cursor_index
246    ///     The index in \ainput of the word in which the cursor lies.
247    ///
248    /// @param[in] char_pos
249    ///     The character position of the cursor in its argument word.
250    ///
251    /// @param[in] opt_element_vector
252    ///     The results of the options parse of \a input.
253    ///
254    /// @param[in] opt_element_index
255    ///     The position in \a opt_element_vector of the word in \a input containing the cursor.
256    ///
257    /// @param[in] match_start_point
258    /// @param[in] match_return_elements
259    ///     See CommandObject::HandleCompletions for a description of how these work.
260    ///
261    /// @param[out] word_complete
262    ///     \btrue if this is a complete option value (a space will be inserted after the
263    ///     completion.)  \bfalse otherwise.
264    ///
265    /// @param[out] matches
266    ///     The array of matches returned.
267    ///
268    /// FIXME: This is the wrong return value, since we also need to make a distinction between
269    /// total number of matches, and the window the user wants returned.
270    ///
271    /// @return
272    ///     \btrue if we were in an option, \bfalse otherwise.
273    //------------------------------------------------------------------
274    virtual bool
275    HandleOptionArgumentCompletion (CommandInterpreter &interpreter,
276                                    Args &input,
277                                    int cursor_index,
278                                    int char_pos,
279                                    OptionElementVector &opt_element_vector,
280                                    int opt_element_index,
281                                    int match_start_point,
282                                    int max_return_elements,
283                                    bool &word_complete,
284                                    StringList &matches);
285
286protected:
287    // This is a set of options expressed as indexes into the options table for this Option.
288    typedef std::set<char> OptionSet;
289    typedef std::vector<OptionSet> OptionSetVector;
290
291    std::vector<struct option> m_getopt_table;
292    OptionSet m_seen_options;
293    OptionSetVector m_required_options;
294    OptionSetVector m_optional_options;
295
296    OptionSetVector &GetRequiredOptions ()
297    {
298        BuildValidOptionSets();
299        return m_required_options;
300    }
301
302    OptionSetVector &GetOptionalOptions ()
303    {
304        BuildValidOptionSets();
305        return m_optional_options;
306    }
307
308    bool
309    IsASubset (const OptionSet& set_a, const OptionSet& set_b);
310
311    size_t
312    OptionsSetDiff (const OptionSet &set_a, const OptionSet &set_b, OptionSet &diffs);
313
314    void
315    OptionsSetUnion (const OptionSet &set_a, const OptionSet &set_b, OptionSet &union_set);
316};
317
318} // namespace lldb_private
319
320#endif  // liblldb_Options_h_
321