1/*
2 * Copyright 2013 Google Inc.
3 *
4 * Use of this source code is governed by a BSD-style license that can be
5 * found in the LICENSE file.
6 */
7
8#ifndef SK_COMMAND_LINE_FLAGS_H
9#define SK_COMMAND_LINE_FLAGS_H
10
11#include "SkString.h"
12#include "SkTArray.h"
13#include "SkTDArray.h"
14
15/**
16 *  Including this file (and compiling SkCommandLineFlags.cpp) provides command line
17 *  parsing. In order to use it, use the following macros in global
18 *  namespace:
19 *
20 *  DEFINE_bool(name, defaultValue, helpString);
21 *  DEFINE_string(name, defaultValue, helpString);
22 *  DEFINE_int32(name, defaultValue, helpString);
23 *  DEFINE_double(name, defaultValue, helpString);
24 *
25 *  Then, in main, call SkCommandLineFlags::SetUsage() to describe usage and call
26 *  SkCommandLineFlags::Parse() to parse the flags. Henceforth, each flag can
27 *  be referenced using
28 *
29 *  FLAGS_name
30 *
31 *  For example, the line
32 *
33 *  DEFINE_bool(boolean, false, "The variable boolean does such and such");
34 *
35 *  will create the following variable:
36 *
37 *  bool FLAGS_boolean;
38 *
39 *  which will initially be set to false, and can be set to true by using the
40 *  flag "--boolean" on the commandline. "--noboolean" will set FLAGS_boolean
41 *  to false. FLAGS_boolean can also be set using "--boolean=true" or
42 *  "--boolean true" (where "true" can be replaced by "false", "TRUE", "FALSE",
43 *  "1" or "0").
44 *
45 *  The helpString will be printed if the help flag (-h or -help) is used.
46 *
47 *  Similarly, the line
48 *
49 *  DEFINE_int32(integer, .., ..);
50 *
51 *  will create
52 *
53 *  int32_t FLAGS_integer;
54 *
55 *  and
56 *
57 *  DEFINE_double(real, .., ..);
58 *
59 *  will create
60 *
61 *  double FLAGS_real;
62 *
63 *  These flags can be set by specifying, for example, "--integer 7" and
64 *  "--real 3.14" on the command line.
65 *
66 *  Unlike the others, the line
67 *
68 *  DEFINE_string(args, .., ..);
69 *
70 *  creates an array:
71 *
72 *  SkCommandLineFlags::StringArray FLAGS_args;
73 *
74 *  If the default value is the empty string, FLAGS_args will default to a size
75 *  of zero. Otherwise it will default to a size of 1 with the default string
76 *  as its value. All strings that follow the flag on the command line (until
77 *  a string that begins with '-') will be entries in the array.
78 *
79 *  Any flag can be referenced from another file after using the following:
80 *
81 *  DECLARE_x(name);
82 *
83 *  (where 'x' is the type specified in the DEFINE).
84 *
85 *  Inspired by gflags (https://code.google.com/p/gflags/). Is not quite as
86 *  robust as gflags, but suits our purposes. For example, allows creating
87 *  a flag -h or -help which will never be used, since SkCommandLineFlags handles it.
88 *  SkCommandLineFlags will also allow creating --flag and --noflag. Uses the same input
89 *  format as gflags and creates similarly named variables (i.e. FLAGS_name).
90 *  Strings are handled differently (resulting variable will be an array of
91 *  strings) so that a flag can be followed by multiple parameters.
92 */
93
94class SkFlagInfo;
95
96class SkCommandLineFlags {
97
98public:
99    /**
100     *  Call to set the help message to be displayed. Should be called before
101     *  Parse.
102     */
103    static void SetUsage(const char* usage);
104
105    /**
106     *  Call at the beginning of main to parse flags created by DEFINE_x, above.
107     *  Must only be called once.
108     */
109    static void Parse(int argc, char** argv);
110
111    /**
112     *  Custom class for holding the arguments for a string flag.
113     *  Publicly only has accessors so the strings cannot be modified.
114     */
115    class StringArray {
116    public:
117        const char* operator[](int i) const {
118            SkASSERT(i >= 0 && i < fStrings.count());
119            return fStrings[i].c_str();
120        }
121
122        int count() const {
123            return fStrings.count();
124        }
125
126        bool isEmpty() const { return this->count() == 0; }
127
128        /**
129         * Returns true iff string is equal to one of the strings in this array.
130         */
131        bool contains(const char* string) const {
132            for (int i = 0; i < fStrings.count(); i++) {
133                if (fStrings[i].equals(string)) {
134                    return true;
135                }
136            }
137            return false;
138        }
139
140    private:
141        void reset() { fStrings.reset(); }
142
143        void append(const char* string) {
144            fStrings.push_back().set(string);
145        }
146
147        void append(const char* string, size_t length) {
148            fStrings.push_back().set(string, length);
149        }
150
151        SkTArray<SkString> fStrings;
152
153        friend class SkFlagInfo;
154    };
155
156    /* Takes a list of the form [~][^]match[$]
157     ~ causes a matching test to always be skipped
158     ^ requires the start of the test to match
159     $ requires the end of the test to match
160     ^ and $ requires an exact match
161     If a test does not match any list entry, it is skipped unless some list entry starts with ~
162    */
163    static bool ShouldSkip(const SkTDArray<const char*>& strings, const char* name);
164    static bool ShouldSkip(const StringArray& strings, const char* name);
165
166private:
167    static SkFlagInfo* gHead;
168    static SkString    gUsage;
169
170    // For access to gHead.
171    friend class SkFlagInfo;
172};
173
174#define TO_STRING2(s) #s
175#define TO_STRING(s) TO_STRING2(s)
176
177#define DEFINE_bool(name, defaultValue, helpString)                         \
178bool FLAGS_##name;                                                          \
179static bool unused_##name = SkFlagInfo::CreateBoolFlag(TO_STRING(name),     \
180                                                       NULL,                \
181                                                       &FLAGS_##name,       \
182                                                       defaultValue,        \
183                                                       helpString)
184
185// bool 2 allows specifying a short name. No check is done to ensure that shortName
186// is actually shorter than name.
187#define DEFINE_bool2(name, shortName, defaultValue, helpString)             \
188bool FLAGS_##name;                                                          \
189static bool unused_##name = SkFlagInfo::CreateBoolFlag(TO_STRING(name),     \
190                                                       TO_STRING(shortName),\
191                                                       &FLAGS_##name,       \
192                                                       defaultValue,        \
193                                                       helpString)
194
195#define DECLARE_bool(name) extern bool FLAGS_##name;
196
197#define DEFINE_string(name, defaultValue, helpString)                       \
198SkCommandLineFlags::StringArray FLAGS_##name;                               \
199static bool unused_##name = SkFlagInfo::CreateStringFlag(TO_STRING(name),   \
200                                                         NULL,              \
201                                                         &FLAGS_##name,     \
202                                                         defaultValue,      \
203                                                         helpString)
204
205// string2 allows specifying a short name. There is an assert that shortName
206// is only 1 character.
207#define DEFINE_string2(name, shortName, defaultValue, helpString)               \
208SkCommandLineFlags::StringArray FLAGS_##name;                                   \
209static bool unused_##name = SkFlagInfo::CreateStringFlag(TO_STRING(name),       \
210                                                         TO_STRING(shortName),  \
211                                                         &FLAGS_##name,         \
212                                                         defaultValue,          \
213                                                         helpString)
214
215#define DECLARE_string(name) extern SkCommandLineFlags::StringArray FLAGS_##name;
216
217#define DEFINE_int32(name, defaultValue, helpString)                        \
218int32_t FLAGS_##name;                                                       \
219static bool unused_##name = SkFlagInfo::CreateIntFlag(TO_STRING(name),      \
220                                                      &FLAGS_##name,        \
221                                                      defaultValue,         \
222                                                      helpString)
223
224#define DECLARE_int32(name) extern int32_t FLAGS_##name;
225
226#define DEFINE_double(name, defaultValue, helpString)                       \
227double FLAGS_##name;                                                        \
228static bool unused_##name = SkFlagInfo::CreateDoubleFlag(TO_STRING(name),   \
229                                                         &FLAGS_##name,     \
230                                                         defaultValue,      \
231                                                         helpString)
232
233#define DECLARE_double(name) extern double FLAGS_##name;
234
235class SkFlagInfo {
236
237public:
238    enum FlagTypes {
239        kBool_FlagType,
240        kString_FlagType,
241        kInt_FlagType,
242        kDouble_FlagType,
243    };
244
245    /**
246     *  Each Create<Type>Flag function creates an SkFlagInfo of the specified type. The SkFlagInfo
247     *  object is appended to a list, which is deleted when SkCommandLineFlags::Parse is called.
248     *  Therefore, each call should be made before the call to ::Parse. They are not intended
249     *  to be called directly. Instead, use the macros described above.
250     *  @param name Long version (at least 2 characters) of the name of the flag. This name can
251     *      be referenced on the command line as "--name" to set the value of this flag.
252     *  @param shortName Short version (one character) of the name of the flag. This name can
253     *      be referenced on the command line as "-shortName" to set the value of this flag.
254     *  @param p<Type> Pointer to a global variable which holds the value set by SkCommandLineFlags.
255     *  @param defaultValue The default value of this flag. The variable pointed to by p<Type> will
256     *      be set to this value initially. This is also displayed as part of the help output.
257     *  @param helpString Explanation of what this flag changes in the program.
258     */
259    static bool CreateBoolFlag(const char* name, const char* shortName, bool* pBool,
260                               bool defaultValue, const char* helpString) {
261        SkFlagInfo* info = SkNEW_ARGS(SkFlagInfo, (name, shortName, kBool_FlagType, helpString));
262        info->fBoolValue = pBool;
263        *info->fBoolValue = info->fDefaultBool = defaultValue;
264        return true;
265    }
266
267    /**
268     *  See comments for CreateBoolFlag.
269     *  @param pStrings Unlike the others, this is a pointer to an array of values.
270     *  @param defaultValue Thise default will be parsed so that strings separated by spaces
271     *      will be added to pStrings.
272     */
273    static bool CreateStringFlag(const char* name, const char* shortName,
274                                 SkCommandLineFlags::StringArray* pStrings,
275                                 const char* defaultValue, const char* helpString);
276
277    /**
278     *  See comments for CreateBoolFlag.
279     */
280    static bool CreateIntFlag(const char* name, int32_t* pInt,
281                              int32_t defaultValue, const char* helpString) {
282        SkFlagInfo* info = SkNEW_ARGS(SkFlagInfo, (name, NULL, kInt_FlagType, helpString));
283        info->fIntValue = pInt;
284        *info->fIntValue = info->fDefaultInt = defaultValue;
285        return true;
286    }
287
288    /**
289     *  See comments for CreateBoolFlag.
290     */
291    static bool CreateDoubleFlag(const char* name, double* pDouble,
292                                 double defaultValue, const char* helpString) {
293        SkFlagInfo* info = SkNEW_ARGS(SkFlagInfo, (name, NULL, kDouble_FlagType, helpString));
294        info->fDoubleValue = pDouble;
295        *info->fDoubleValue = info->fDefaultDouble = defaultValue;
296        return true;
297    }
298
299    /**
300     *  Returns true if the string matches this flag.
301     *  For a boolean flag, also sets the value, since a boolean flag can be set in a number of ways
302     *  without looking at the following string:
303     *      --name
304     *      --noname
305     *      --name=true
306     *      --name=false
307     *      --name=1
308     *      --name=0
309     *      --name=TRUE
310     *      --name=FALSE
311     */
312    bool match(const char* string);
313
314    FlagTypes getFlagType() const { return fFlagType; }
315
316    void resetStrings() {
317        if (kString_FlagType == fFlagType) {
318            fStrings->reset();
319        } else {
320            SkDEBUGFAIL("Can only call resetStrings on kString_FlagType");
321        }
322    }
323
324    void append(const char* string) {
325        if (kString_FlagType == fFlagType) {
326            fStrings->append(string);
327        } else {
328            SkDEBUGFAIL("Can only append to kString_FlagType");
329        }
330    }
331
332    void setInt(int32_t value) {
333        if (kInt_FlagType == fFlagType) {
334            *fIntValue = value;
335        } else {
336            SkDEBUGFAIL("Can only call setInt on kInt_FlagType");
337        }
338    }
339
340    void setDouble(double value) {
341        if (kDouble_FlagType == fFlagType) {
342            *fDoubleValue = value;
343        } else {
344            SkDEBUGFAIL("Can only call setDouble on kDouble_FlagType");
345        }
346    }
347
348    void setBool(bool value) {
349        if (kBool_FlagType == fFlagType) {
350            *fBoolValue = value;
351        } else {
352            SkDEBUGFAIL("Can only call setBool on kBool_FlagType");
353        }
354    }
355
356    SkFlagInfo* next() { return fNext; }
357
358    const SkString& name() const { return fName; }
359
360    const SkString& shortName() const { return fShortName; }
361
362    const SkString& help() const { return fHelpString; }
363
364    SkString defaultValue() const {
365        SkString result;
366        switch (fFlagType) {
367            case SkFlagInfo::kBool_FlagType:
368                result.printf("%s", fDefaultBool ? "true" : "false");
369                break;
370            case SkFlagInfo::kString_FlagType:
371                return fDefaultString;
372            case SkFlagInfo::kInt_FlagType:
373                result.printf("%i", fDefaultInt);
374                break;
375            case SkFlagInfo::kDouble_FlagType:
376                result.printf("%2.2f", fDefaultDouble);
377                break;
378            default:
379                SkDEBUGFAIL("Invalid flag type");
380        }
381        return result;
382    }
383
384    SkString typeAsString() const {
385        switch (fFlagType) {
386            case SkFlagInfo::kBool_FlagType:
387                return SkString("bool");
388            case SkFlagInfo::kString_FlagType:
389                return SkString("string");
390            case SkFlagInfo::kInt_FlagType:
391                return SkString("int");
392            case SkFlagInfo::kDouble_FlagType:
393                return SkString("double");
394            default:
395                SkDEBUGFAIL("Invalid flag type");
396                return SkString();
397        }
398    }
399
400private:
401    SkFlagInfo(const char* name, const char* shortName, FlagTypes type, const char* helpString)
402        : fName(name)
403        , fShortName(shortName)
404        , fFlagType(type)
405        , fHelpString(helpString)
406        , fBoolValue(NULL)
407        , fDefaultBool(false)
408        , fIntValue(NULL)
409        , fDefaultInt(0)
410        , fDoubleValue(NULL)
411        , fDefaultDouble(0)
412        , fStrings(NULL) {
413        fNext = SkCommandLineFlags::gHead;
414        SkCommandLineFlags::gHead = this;
415        SkASSERT(NULL != name && strlen(name) > 1);
416        SkASSERT(NULL == shortName || 1 == strlen(shortName));
417    }
418
419    /**
420     *  Set a StringArray to hold the values stored in defaultStrings.
421     *  @param array The StringArray to modify.
422     *  @param defaultStrings Space separated list of strings that should be inserted into array
423     *      individually.
424     */
425    static void SetDefaultStrings(SkCommandLineFlags::StringArray* array,
426                                  const char* defaultStrings);
427
428    // Name of the flag, without initial dashes
429    SkString             fName;
430    SkString             fShortName;
431    FlagTypes            fFlagType;
432    SkString             fHelpString;
433    bool*                fBoolValue;
434    bool                 fDefaultBool;
435    int32_t*             fIntValue;
436    int32_t              fDefaultInt;
437    double*              fDoubleValue;
438    double               fDefaultDouble;
439    SkCommandLineFlags::StringArray* fStrings;
440    // Both for the help string and in case fStrings is empty.
441    SkString             fDefaultString;
442
443    // In order to keep a linked list.
444    SkFlagInfo*          fNext;
445};
446#endif // SK_COMMAND_LINE_FLAGS_H
447