projcet url:
https://github.com/schuhschuh/gflags
usage: commandline flags processing
DEFINE: Defining Flags In Program
DEFINE_bool: boolean
DEFINE_int32: 32-bit integer
DEFINE_int64: 64-bit integer
DEFINE_uint64: unsigned 64-bit integer
DEFINE_double: double
DEFINE_string: C++ string
DECLARE: Using the Flag in a Different File
If the flag does span multiple files, DECLARE it in theassociated .h file, and make others #include that .h file if they want to access the flag. The #include will make explicit the dependency between the two files. This causes the flag to be a global variable.
RegisterFlagValidator: Sanity-checking Flag Values
Here is an example use of this functionality:
static bool ValidatePort(const char* flagname, int32 value) {
if (value > 0 && value < 32768) // value is ok
return true;
printf("Invalid value for --%s: %d ", flagname, (int)value);
return false;
}
DEFINE_int32(port, 0, "What port to listen on");
static const bool port_dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort);
By doing the registration at global initialization time (right after the DEFINE), we ensure that the registration happens before the commandline is parsed at the beginning of main().
Putting It Together: How to Set Up Flags
gflags::ParseCommandLineFlags(&argc, &argv, true);
The last argument is called "remove_flags". If true, then ParseCommandLineFlags removes the flags and their arguments from argv, and modifies argc appropriately. In this case, after the function call, argv will hold only commandline arguments, and not commandline flags.
If, on the other hand, remove_flags is false, then ParseCommandLineFlags will leave argc unchanged, butwill rearrange the arguments in argv so that the flags are all at the beginning.
Setting Flags on the Command Line
Here's an example of all the ways to specify the "languages" flag:
app_containing_foo --languages="chinese,japanese,korean"
app_containing_foo -languages="chinese,japanese,korean"
app_containing_foo --languages "chinese,japanese,korean"
app_containing_foo --big_menu
app_containing_foo --nobig_menu
app_containing_foo --big_menu=true
app_containing_foo --big_menu=false
Changing the Default Flag Value
It's simple to do this: just assign a new value to the flag in main(), before calling ParseCommandLineFlags():
DECLARE_bool(lib_verbose); // mylib has a lib_verbose flag, default is false
int main(int argc, char** argv) {
FLAGS_lib_verbose = true; // in my app, I want a verbose lib by default
ParseCommandLineFlags(...);
}
For this application, users can still set the flag value on the commandline, but if they do not, the flag's value will default to true.
Special Flags
--helpshows all flags from all files, sorted by file and then by name; shows the flagname, its default value, and its help string
--helpfullsame as -help, but unambiguously asks for all flags (in case -help changes in the future)
--helpshortshows only flags for the file with the same name as the executable (usually the one containing main())
--helpxmllike --help, but output is in xml for easier parsing
--helpon=FILE shows only flags defined in FILE.*
--helpmatch=Sshows only flags defined in *S*.*
--helppackageshows flags defined in files in same directory as main()
--versionprints version info for the executable
--fromenv
--fromenv=foo,bar says to read the values for the foo and bar flags from the environment.
--tryfromenv
--tryfromenv is exactly like --fromenv, except it is not a fatal error to say --tryfromenv=foo if FLAGS_foo is not actually defined in the environment.
--flagfile
--flagfile=f tells the commandlineflags module to read the file f, and to run all the flag-assignments found in that file as if these flags had been specified on the commandline.
The API
For more information about these routines, and other useful helper methods such asgflags::SetUsageMessage() andgflags::SetVersionString, seegflags.h.
Miscellaneous Notes
If your application has code like this:
#define STRIP_FLAG_HELP 1 // this must go before the #include!
#include <gflags/gflags.h>
we will remove the help messages from the compiled source. This canreduce the size of the resulting binary somewhat, and mayalso be useful for security reasons.
usage: commandline flags processing
DEFINE: Defining Flags In Program
DEFINE_bool: boolean
DEFINE_int32: 32-bit integer
DEFINE_int64: 64-bit integer
DEFINE_uint64: unsigned 64-bit integer
DEFINE_double: double
DEFINE_string: C++ string
DECLARE: Using the Flag in a Different File
If the flag does span multiple files, DECLARE it in theassociated .h file, and make others #include that .h file if they want to access the flag. The #include will make explicit the dependency between the two files. This causes the flag to be a global variable.
RegisterFlagValidator: Sanity-checking Flag Values
Here is an example use of this functionality:
static bool ValidatePort(const char* flagname, int32 value) {
if (value > 0 && value < 32768) // value is ok
return true;
printf("Invalid value for --%s: %d ", flagname, (int)value);
return false;
}
DEFINE_int32(port, 0, "What port to listen on");
static const bool port_dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort);
By doing the registration at global initialization time (right after the DEFINE), we ensure that the registration happens before the commandline is parsed at the beginning of main().
Putting It Together: How to Set Up Flags
gflags::ParseCommandLineFlags(&argc, &argv, true);
The last argument is called "remove_flags". If true, then ParseCommandLineFlags removes the flags and their arguments from argv, and modifies argc appropriately. In this case, after the function call, argv will hold only commandline arguments, and not commandline flags.
If, on the other hand, remove_flags is false, then ParseCommandLineFlags will leave argc unchanged, butwill rearrange the arguments in argv so that the flags are all at the beginning.
Setting Flags on the Command Line
Here's an example of all the ways to specify the "languages" flag:
app_containing_foo --languages="chinese,japanese,korean"
app_containing_foo -languages="chinese,japanese,korean"
app_containing_foo --languages "chinese,japanese,korean"
app_containing_foo -languages "chinese,japanese,korean"
For boolean flags, the possibilities are slightly different:app_containing_foo --big_menu
app_containing_foo --nobig_menu
app_containing_foo --big_menu=true
app_containing_foo --big_menu=false
Changing the Default Flag Value
It's simple to do this: just assign a new value to the flag in main(), before calling ParseCommandLineFlags():
DECLARE_bool(lib_verbose); // mylib has a lib_verbose flag, default is false
int main(int argc, char** argv) {
FLAGS_lib_verbose = true; // in my app, I want a verbose lib by default
ParseCommandLineFlags(...);
}
For this application, users can still set the flag value on the commandline, but if they do not, the flag's value will default to true.
Special Flags
--helpshows all flags from all files, sorted by file and then by name; shows the flagname, its default value, and its help string
--helpfullsame as -help, but unambiguously asks for all flags (in case -help changes in the future)
--helpshortshows only flags for the file with the same name as the executable (usually the one containing main())
--helpxmllike --help, but output is in xml for easier parsing
--helpon=FILE shows only flags defined in FILE.*
--helpmatch=Sshows only flags defined in *S*.*
--helppackageshows flags defined in files in same directory as main()
--versionprints version info for the executable
--fromenv
--fromenv=foo,bar says to read the values for the foo and bar flags from the environment.
--tryfromenv
--tryfromenv is exactly like --fromenv, except it is not a fatal error to say --tryfromenv=foo if FLAGS_foo is not actually defined in the environment.
--flagfile
--flagfile=f tells the commandlineflags module to read the file f, and to run all the flag-assignments found in that file as if these flags had been specified on the commandline.
The API
For more information about these routines, and other useful helper methods such asgflags::SetUsageMessage() andgflags::SetVersionString, seegflags.h.
Miscellaneous Notes
If your application has code like this:
#define STRIP_FLAG_HELP 1 // this must go before the #include!
#include <gflags/gflags.h>
we will remove the help messages from the compiled source. This canreduce the size of the resulting binary somewhat, and mayalso be useful for security reasons.