blob: 370198b5a20d49825e5838637c4a8399f7b7383a [file] [log] [blame]
scroggo@google.com161e1ba2013-03-04 16:41:06 +00001/*
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
scroggo@google.comd9ba9a02013-03-21 19:43:15 +00008#ifndef SK_COMMAND_LINE_FLAGS_H
9#define SK_COMMAND_LINE_FLAGS_H
scroggo@google.com161e1ba2013-03-04 16:41:06 +000010
11#include "SkString.h"
scroggo@google.comb7dbf632013-04-23 15:38:09 +000012#include "SkTArray.h"
sglez@google.com586db932013-07-24 17:24:23 +000013#include "SkTDArray.h"
scroggo@google.com161e1ba2013-03-04 16:41:06 +000014
15/**
scroggo@google.comd9ba9a02013-03-21 19:43:15 +000016 * Including this file (and compiling SkCommandLineFlags.cpp) provides command line
scroggo@google.com161e1ba2013-03-04 16:41:06 +000017 * 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 *
scroggo@google.comd9ba9a02013-03-21 19:43:15 +000025 * Then, in main, call SkCommandLineFlags::SetUsage() to describe usage and call
26 * SkCommandLineFlags::Parse() to parse the flags. Henceforth, each flag can
scroggo@google.com161e1ba2013-03-04 16:41:06 +000027 * 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
scroggo@google.com5dc4ca12013-03-21 13:10:59 +000041 * 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 *
scroggo@google.com5dc4ca12013-03-21 13:10:59 +000045 * The helpString will be printed if the help flag (-h or -help) is used.
scroggo@google.com161e1ba2013-03-04 16:41:06 +000046 *
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 *
scroggo@google.comb7dbf632013-04-23 15:38:09 +000072 * SkCommandLineFlags::StringArray FLAGS_args;
scroggo@google.com161e1ba2013-03-04 16:41:06 +000073 *
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
scroggo@google.comd9ba9a02013-03-21 19:43:15 +000087 * 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
scroggo@google.com161e1ba2013-03-04 16:41:06 +000089 * 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
scroggo@google.com161e1ba2013-03-04 16:41:06 +000094class SkFlagInfo;
95
scroggo@google.comd9ba9a02013-03-21 19:43:15 +000096class SkCommandLineFlags {
scroggo@google.com161e1ba2013-03-04 16:41:06 +000097
98public:
99 /**
100 * Call to set the help message to be displayed. Should be called before
scroggo@google.comd9ba9a02013-03-21 19:43:15 +0000101 * Parse.
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000102 */
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 */
scroggo@google.comd9ba9a02013-03-21 19:43:15 +0000109 static void Parse(int argc, char** argv);
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000110
scroggo@google.comb7dbf632013-04-23 15:38:09 +0000111 /**
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
epoger@google.comdefc4872013-09-19 06:18:27 +0000128 /**
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
scroggo@google.comb7dbf632013-04-23 15:38:09 +0000140 private:
141 void reset() { fStrings.reset(); }
142
143 void append(const char* string) {
144 fStrings.push_back().set(string);
145 }
146
scroggo@google.com58104a92013-04-24 19:25:26 +0000147 void append(const char* string, size_t length) {
148 fStrings.push_back().set(string, length);
149 }
150
scroggo@google.comb7dbf632013-04-23 15:38:09 +0000151 SkTArray<SkString> fStrings;
152
153 friend class SkFlagInfo;
154 };
155
commit-bot@chromium.orga6f37e72013-08-30 15:52:46 +0000156 /* 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
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000166private:
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), \
scroggo@google.com09fd4d22013-03-20 14:20:18 +0000180 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),\
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000191 &FLAGS_##name, \
192 defaultValue, \
193 helpString)
194
195#define DECLARE_bool(name) extern bool FLAGS_##name;
196
197#define DEFINE_string(name, defaultValue, helpString) \
scroggo@google.comb7dbf632013-04-23 15:38:09 +0000198SkCommandLineFlags::StringArray FLAGS_##name; \
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000199static bool unused_##name = SkFlagInfo::CreateStringFlag(TO_STRING(name), \
scroggo@google.com09fd4d22013-03-20 14:20:18 +0000200 NULL, \
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000201 &FLAGS_##name, \
202 defaultValue, \
203 helpString)
204
scroggo@google.com604e0c22013-04-09 21:25:46 +0000205// string2 allows specifying a short name. There is an assert that shortName
206// is only 1 character.
scroggo@google.com09fd4d22013-03-20 14:20:18 +0000207#define DEFINE_string2(name, shortName, defaultValue, helpString) \
scroggo@google.comb7dbf632013-04-23 15:38:09 +0000208SkCommandLineFlags::StringArray FLAGS_##name; \
scroggo@google.com09fd4d22013-03-20 14:20:18 +0000209static bool unused_##name = SkFlagInfo::CreateStringFlag(TO_STRING(name), \
210 TO_STRING(shortName), \
211 &FLAGS_##name, \
212 defaultValue, \
213 helpString)
214
scroggo@google.comb7dbf632013-04-23 15:38:09 +0000215#define DECLARE_string(name) extern SkCommandLineFlags::StringArray FLAGS_##name;
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000216
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
scroggo@google.com58104a92013-04-24 19:25:26 +0000245 /**
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 */
scroggo@google.com09fd4d22013-03-20 14:20:18 +0000259 static bool CreateBoolFlag(const char* name, const char* shortName, bool* pBool,
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000260 bool defaultValue, const char* helpString) {
scroggo@google.com604e0c22013-04-09 21:25:46 +0000261 SkFlagInfo* info = SkNEW_ARGS(SkFlagInfo, (name, shortName, kBool_FlagType, helpString));
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000262 info->fBoolValue = pBool;
263 *info->fBoolValue = info->fDefaultBool = defaultValue;
264 return true;
265 }
266
scroggo@google.com58104a92013-04-24 19:25:26 +0000267 /**
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 */
scroggo@google.com09fd4d22013-03-20 14:20:18 +0000273 static bool CreateStringFlag(const char* name, const char* shortName,
scroggo@google.comb7dbf632013-04-23 15:38:09 +0000274 SkCommandLineFlags::StringArray* pStrings,
scroggo@google.com58104a92013-04-24 19:25:26 +0000275 const char* defaultValue, const char* helpString);
skia.committer@gmail.com075b0892013-03-05 07:09:08 +0000276
scroggo@google.com58104a92013-04-24 19:25:26 +0000277 /**
278 * See comments for CreateBoolFlag.
279 */
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000280 static bool CreateIntFlag(const char* name, int32_t* pInt,
281 int32_t defaultValue, const char* helpString) {
scroggo@google.com604e0c22013-04-09 21:25:46 +0000282 SkFlagInfo* info = SkNEW_ARGS(SkFlagInfo, (name, NULL, kInt_FlagType, helpString));
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000283 info->fIntValue = pInt;
284 *info->fIntValue = info->fDefaultInt = defaultValue;
285 return true;
286 }
287
scroggo@google.com58104a92013-04-24 19:25:26 +0000288 /**
289 * See comments for CreateBoolFlag.
290 */
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000291 static bool CreateDoubleFlag(const char* name, double* pDouble,
292 double defaultValue, const char* helpString) {
scroggo@google.com604e0c22013-04-09 21:25:46 +0000293 SkFlagInfo* info = SkNEW_ARGS(SkFlagInfo, (name, NULL, kDouble_FlagType, helpString));
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000294 info->fDoubleValue = pDouble;
295 *info->fDoubleValue = info->fDefaultDouble = defaultValue;
296 return true;
297 }
298
299 /**
scroggo@google.com5dc4ca12013-03-21 13:10:59 +0000300 * 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
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000311 */
scroggo@google.com5dc4ca12013-03-21 13:10:59 +0000312 bool match(const char* string);
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000313
314 FlagTypes getFlagType() const { return fFlagType; }
315
316 void resetStrings() {
317 if (kString_FlagType == fFlagType) {
318 fStrings->reset();
319 } else {
mtklein@google.com330313a2013-08-22 15:37:26 +0000320 SkDEBUGFAIL("Can only call resetStrings on kString_FlagType");
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000321 }
322 }
323
324 void append(const char* string) {
325 if (kString_FlagType == fFlagType) {
scroggo@google.comb7dbf632013-04-23 15:38:09 +0000326 fStrings->append(string);
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000327 } else {
mtklein@google.com330313a2013-08-22 15:37:26 +0000328 SkDEBUGFAIL("Can only append to kString_FlagType");
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000329 }
330 }
331
332 void setInt(int32_t value) {
333 if (kInt_FlagType == fFlagType) {
334 *fIntValue = value;
335 } else {
mtklein@google.com330313a2013-08-22 15:37:26 +0000336 SkDEBUGFAIL("Can only call setInt on kInt_FlagType");
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000337 }
338 }
339
340 void setDouble(double value) {
341 if (kDouble_FlagType == fFlagType) {
342 *fDoubleValue = value;
343 } else {
mtklein@google.com330313a2013-08-22 15:37:26 +0000344 SkDEBUGFAIL("Can only call setDouble on kDouble_FlagType");
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000345 }
346 }
347
scroggo@google.com5dc4ca12013-03-21 13:10:59 +0000348 void setBool(bool value) {
349 if (kBool_FlagType == fFlagType) {
350 *fBoolValue = value;
351 } else {
mtklein@google.com330313a2013-08-22 15:37:26 +0000352 SkDEBUGFAIL("Can only call setBool on kBool_FlagType");
scroggo@google.com5dc4ca12013-03-21 13:10:59 +0000353 }
354 }
355
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000356 SkFlagInfo* next() { return fNext; }
357
358 const SkString& name() const { return fName; }
359
scroggo@google.com8366df02013-03-20 19:50:41 +0000360 const SkString& shortName() const { return fShortName; }
361
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000362 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:
mtklein@google.com330313a2013-08-22 15:37:26 +0000379 SkDEBUGFAIL("Invalid flag type");
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000380 }
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:
mtklein@google.com330313a2013-08-22 15:37:26 +0000395 SkDEBUGFAIL("Invalid flag type");
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000396 return SkString();
397 }
398 }
399
400private:
scroggo@google.com604e0c22013-04-09 21:25:46 +0000401 SkFlagInfo(const char* name, const char* shortName, FlagTypes type, const char* helpString)
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000402 : fName(name)
scroggo@google.com604e0c22013-04-09 21:25:46 +0000403 , fShortName(shortName)
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000404 , 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) {
scroggo@google.comd9ba9a02013-03-21 19:43:15 +0000413 fNext = SkCommandLineFlags::gHead;
414 SkCommandLineFlags::gHead = this;
scroggo@google.com604e0c22013-04-09 21:25:46 +0000415 SkASSERT(NULL != name && strlen(name) > 1);
416 SkASSERT(NULL == shortName || 1 == strlen(shortName));
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000417 }
scroggo@google.com58104a92013-04-24 19:25:26 +0000418
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
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000428 // Name of the flag, without initial dashes
429 SkString fName;
scroggo@google.com09fd4d22013-03-20 14:20:18 +0000430 SkString fShortName;
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000431 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;
scroggo@google.comb7dbf632013-04-23 15:38:09 +0000439 SkCommandLineFlags::StringArray* fStrings;
scroggo@google.com161e1ba2013-03-04 16:41:06 +0000440 // 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};
scroggo@google.comd9ba9a02013-03-21 19:43:15 +0000446#endif // SK_COMMAND_LINE_FLAGS_H