Open Lighting Architecture  Latest Git
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Files | Namespaces | Classes | Macros | Functions
Command Line Flags

Detailed Description

Command line flag processing.

This is based on gflags (https://code.google.com/p/gflags/) but we reduce the feature set to make things simpler.

Features:

Note
  • Setting flags is not thread safe
  • Flags cannot be used at global construction time.
  • DEFINE_ and DECLARE_ must be outside of any namespaces.
Example
#include <ola/base/Flags.h>
#include <iostream>
using std::cout;
using std::endl;
// These options are --foo and --no-bar.
DEFINE_default_bool(foo, false, "Enable feature foo");
DEFINE_default_bool(bar, true, "Disable feature bar");
// FLAGS_name defaults to "simon" and can be changed with --name bob
DEFINE_string(name, "simon", "Specify the name");
// Short options can also be specified:
// FLAGS_baz can be set with --baz or -b
DEFINE_s_int8(baz, b, 0, "Sets the value of baz");
int main(int argc, char* argv[]) {
ola::SetHelpString("[options]", "Description of binary");
ola::ParseFlags(&argc, argv);
cout << "--foo is " << FLAGS_foo << endl;
cout << "--bar is " << FLAGS_bar << endl;
cout << "--name is " << FLAGS_name.str() << endl;
cout << "--baz (-b) is " << static_cast<int>(FLAGS_baz) << endl;
}
When ./flags is run, this produces:
--foo is 0
--bar is 1
--name is simon
--baz (-b) is 0
Compare with ./flags –foo –name bob -b 10 –nobar
--foo is 1
--bar is 0
--name is bob
--baz (-b) is 10
Example - Use flags from other files
You can access flags from files other than the one they were DEFINE_*'d in by using DECLARE_*:
// Can now use FLAGS_foo and FLAGS_bar
Collaboration diagram for Command Line Flags:

Files

file  Flags.cpp
 
file  Flags.h
 Defines macros to ease creation of command line flags.
 
file  FlagsPrivate.h
 Internal functionality for the flags.
 

Namespaces

 ola
 The namespace containing all OLA symbols.
 

Classes

class  ola::FlagInterface
 The interface for the Flag classes. More...
 
class  ola::BaseFlag
 The common implementation. More...
 
class  ola::Flag< T >
 A templated Flag class. More...
 
class  ola::Flag< bool >
 a bool flag More...
 
class  ola::Flag< std::string >
 a string flag More...
 
class  ola::FlagRegistry
 This class holds all the flags, and is responsbile for parsing the command line. More...
 
class  ola::FlagRegisterer
 This class is responsible for registering a flag. More...
 

Macros

#define DECLARE_bool(name)   DECLARE_flag(bool, name)
 Reuse a bool flag from another file. More...
 
#define DECLARE_int8(name)   DECLARE_flag(int8_t, name)
 Reuse an int8_t flag from another file. More...
 
#define DECLARE_int16(name)   DECLARE_flag(int16_t, name)
 Reuse an int16_t flag from another file. More...
 
#define DECLARE_int32(name)   DECLARE_flag(int32_t, name)
 Reuse an int32_t flag from another file. More...
 
#define DECLARE_uint8(name)   DECLARE_flag(uint8_t, name)
 Reuse a uint8_t flag from another file. More...
 
#define DECLARE_uint16(name)   DECLARE_flag(uint16_t, name)
 Reuse a uint16_t flag from another file. More...
 
#define DECLARE_uint32(name)   DECLARE_flag(uint32_t, name)
 Reuse a uint32_t flag from another file. More...
 
#define DECLARE_string(name)   DECLARE_flag(std::string, name)
 Reuse a string flag from another file. More...
 
#define DEFINE_bool(name, default_value, help_str)   DEFINE_flag(bool, name, \0, default_value, help_str, true)
 Create a new longname bool flag. More...
 
#define DEFINE_s_bool(name, short_opt, default_value, help_str)   DEFINE_flag_with_short(bool, name, short_opt, default_value, help_str, true)
 Create a new bool flag with a long and short name. More...
 
#define DEFINE_default_bool(name, default_value, help_str)   DEFINE_flag(bool, name, \0, default_value, help_str, false)
 Create a new longname bool flag that doesn't require an argument. More...
 
#define DEFINE_s_default_bool(name, short_opt, default_value, help_str)   DEFINE_flag_with_short(bool, name, short_opt, default_value, help_str, false)
 Create a new bool flag with a long and short name that doesn't require an argument. More...
 
#define DEFINE_int8(name, default_value, help_str)   DEFINE_flag(int8_t, name, \0, default_value, help_str, true)
 Create a new longname int8_t flag. More...
 
#define DEFINE_s_int8(name, short_opt, default_value, help_str)
 Create a new int8_t flag with a long and short name. More...
 
#define DEFINE_uint8(name, default_value, help_str)   DEFINE_flag(uint8_t, name, \0, default_value, help_str, true)
 Create a new longname uint8_t flag. More...
 
#define DEFINE_s_uint8(name, short_opt, default_value, help_str)
 Create a new uint8_t flag with a long and short name. More...
 
#define DEFINE_int16(name, default_value, help_str)   DEFINE_flag(int16_t, name, \0, default_value, help_str, true)
 Create a new longname int16_t flag. More...
 
#define DEFINE_s_int16(name, short_opt, default_value, help_str)
 Create a new int16_t flag with a long and short name. More...
 
#define DEFINE_uint16(name, default_value, help_str)   DEFINE_flag(uint16_t, name, \0, default_value, help_str, true)
 Create a new longname uint16_t flag. More...
 
#define DEFINE_s_uint16(name, short_opt, default_value, help_str)
 Create a new uint16_t flag with a long and short name. More...
 
#define DEFINE_int32(name, default_value, help_str)   DEFINE_flag(int32_t, name, \0, default_value, help_str, true)
 Create a new longname int32_t flag. More...
 
#define DEFINE_s_int32(name, short_opt, default_value, help_str)
 Create a new int32_t flag with a long and short name. More...
 
#define DEFINE_uint32(name, default_value, help_str)   DEFINE_flag(uint32_t, name, \0, default_value, help_str, true)
 Create a new longname uint32_t flag. More...
 
#define DEFINE_s_uint32(name, short_opt, default_value, help_str)
 Create a new int32_t flag with a long and short name. More...
 
#define DEFINE_string(name, default_value, help_str)   DEFINE_flag(std::string, name, \0, default_value, help_str, true)
 Create a new longname string flag. More...
 
#define DEFINE_s_string(name, short_opt, default_value, help_str)
 Create a new string flag with a long and short name. More...
 

Functions

void ola::SetHelpString (const std::string &first_line, const std::string &description)
 Set the help string for the program. More...
 
void ola::DisplayUsage ()
 Print the usage text to stdout.
 
void ola::DisplayUsageAndExit ()
 Print the usage text to stdout then exit.
 
void ola::DisplayVersion ()
 Print the version text to stdout.
 
void ola::GenManPage ()
 
void ola::ParseFlags (int *argc, char **argv)
 Parses the command line flags up to the first non-flag value. argv is re-arranged so that it only contains non-flag arguments. More...
 
FlagRegistry * ola::GetRegistry ()
 Get the global FlagRegistry.
 
bool ola::Flag< T >::SetValue (const std::string &input)
 Used to set the value of a flag.
 

Macro Definition Documentation

#define DECLARE_bool (   name)    DECLARE_flag(bool, name)

Reuse a bool flag from another file.

Parameters
namethe name of the flag to reuse
#define DECLARE_int16 (   name)    DECLARE_flag(int16_t, name)

Reuse an int16_t flag from another file.

Parameters
namethe name of the flag to reuse
#define DECLARE_int32 (   name)    DECLARE_flag(int32_t, name)

Reuse an int32_t flag from another file.

Parameters
namethe name of the flag to reuse
#define DECLARE_int8 (   name)    DECLARE_flag(int8_t, name)

Reuse an int8_t flag from another file.

Parameters
namethe name of the flag to reuse
#define DECLARE_string (   name)    DECLARE_flag(std::string, name)

Reuse a string flag from another file.

Parameters
namethe name of the flag to reuse
#define DECLARE_uint16 (   name)    DECLARE_flag(uint16_t, name)

Reuse a uint16_t flag from another file.

Parameters
namethe name of the flag to reuse
#define DECLARE_uint32 (   name)    DECLARE_flag(uint32_t, name)

Reuse a uint32_t flag from another file.

Parameters
namethe name of the flag to reuse
#define DECLARE_uint8 (   name)    DECLARE_flag(uint8_t, name)

Reuse a uint8_t flag from another file.

Parameters
namethe name of the flag to reuse
#define DEFINE_bool (   name,
  default_value,
  help_str 
)    DEFINE_flag(bool, name, \0, default_value, help_str, true)

Create a new longname bool flag.

By default the flag is undefined, the same as the string and int ones, that is is_present() returns false. If the flag is provided on the command line, is_present() will be true, and operator bool() returns the value of the flag.

Note
The value must be parseable by StringToBoolTolerant.
Parameters
namethe name of the flag to create
default_valuethe default value for the flag. Either true, or false.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_default_bool (   name,
  default_value,
  help_str 
)    DEFINE_flag(bool, name, \0, default_value, help_str, false)

Create a new longname bool flag that doesn't require an argument.

By default the flag is set to default_value. If the flag is provided on the command line, the value of the flag becomes !default_value.

Parameters
namethe name of the flag to create
default_valuethe default value for the flag. Either true, or false.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_int16 (   name,
  default_value,
  help_str 
)    DEFINE_flag(int16_t, name, \0, default_value, help_str, true)

Create a new longname int16_t flag.

Parameters
namethe name of the flag to create
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_int32 (   name,
  default_value,
  help_str 
)    DEFINE_flag(int32_t, name, \0, default_value, help_str, true)

Create a new longname int32_t flag.

Parameters
namethe name of the flag to create
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_int8 (   name,
  default_value,
  help_str 
)    DEFINE_flag(int8_t, name, \0, default_value, help_str, true)

Create a new longname int8_t flag.

Parameters
namethe name of the flag to create
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_s_bool (   name,
  short_opt,
  default_value,
  help_str 
)    DEFINE_flag_with_short(bool, name, short_opt, default_value, help_str, true)

Create a new bool flag with a long and short name.

By default the flag is undefined, the same as the string and int ones, that is is_present() returns false. If the flag is provided on the command line, is_present() will be true, and operator bool() returns the value of the flag.

Note
The value must be parseable by StringToBoolTolerant.
Parameters
namethe name of the flag to create
short_optthe short name of the flag. For example "-h", or "-d".
default_valuethe default value for the flag. Either true, or false.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_s_default_bool (   name,
  short_opt,
  default_value,
  help_str 
)    DEFINE_flag_with_short(bool, name, short_opt, default_value, help_str, false)

Create a new bool flag with a long and short name that doesn't require an argument.

By default the flag is set to default_value. If the flag is provided on the command line, the value of the flag becomes !default_value.

Parameters
namethe full name of the flag to create
short_optthe short name of the flag. For example "-h", or "-d".
default_valuethe default value for the flag. Either true, or false.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_s_int16 (   name,
  short_opt,
  default_value,
  help_str 
)
Value:
DEFINE_flag_with_short(int16_t, name, short_opt, default_value, help_str, \
true)

Create a new int16_t flag with a long and short name.

Parameters
namethe full name of the flag to create
short_optthe short name of the flag. For example "-h", or "-d".
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_s_int32 (   name,
  short_opt,
  default_value,
  help_str 
)
Value:
DEFINE_flag_with_short(int32_t, name, short_opt, default_value, help_str, \
true)

Create a new int32_t flag with a long and short name.

Parameters
namethe full name of the flag to create
short_optthe short name of the flag. For example "-h", or "-d".
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_s_int8 (   name,
  short_opt,
  default_value,
  help_str 
)
Value:
DEFINE_flag_with_short(int8_t, name, short_opt, default_value, help_str, \
true)

Create a new int8_t flag with a long and short name.

Parameters
namethe full name of the flag to create
short_optthe short name of the flag. For example "-h", or "-d".
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_s_string (   name,
  short_opt,
  default_value,
  help_str 
)
Value:
DEFINE_flag_with_short(std::string, name, short_opt, default_value, \
help_str, true)

Create a new string flag with a long and short name.

Parameters
namethe full name of the flag to create
short_optthe short name of the flag. For example "-h", or "-d".
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_s_uint16 (   name,
  short_opt,
  default_value,
  help_str 
)
Value:
DEFINE_flag_with_short(uint16_t, name, short_opt, default_value, help_str, \
true)

Create a new uint16_t flag with a long and short name.

Parameters
namethe full name of the flag to create
short_optthe short name of the flag. For example "-h", or "-d".
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_s_uint32 (   name,
  short_opt,
  default_value,
  help_str 
)
Value:
DEFINE_flag_with_short(uint32_t, name, short_opt, default_value, help_str, \
true)

Create a new int32_t flag with a long and short name.

Parameters
namethe full name of the flag to create
short_optthe short name of the flag. For example "-h", or "-d".
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_s_uint8 (   name,
  short_opt,
  default_value,
  help_str 
)
Value:
DEFINE_flag_with_short(uint8_t, name, short_opt, default_value, help_str, \
true)

Create a new uint8_t flag with a long and short name.

Parameters
namethe full name of the flag to create
short_optthe short name of the flag. For example "-h", or "-d".
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_string (   name,
  default_value,
  help_str 
)    DEFINE_flag(std::string, name, \0, default_value, help_str, true)

Create a new longname string flag.

Parameters
namethe name of the flag to create
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_uint16 (   name,
  default_value,
  help_str 
)    DEFINE_flag(uint16_t, name, \0, default_value, help_str, true)

Create a new longname uint16_t flag.

Parameters
namethe name of the flag to create
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_uint32 (   name,
  default_value,
  help_str 
)    DEFINE_flag(uint32_t, name, \0, default_value, help_str, true)

Create a new longname uint32_t flag.

Parameters
namethe name of the flag to create
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen
#define DEFINE_uint8 (   name,
  default_value,
  help_str 
)    DEFINE_flag(uint8_t, name, \0, default_value, help_str, true)

Create a new longname uint8_t flag.

Parameters
namethe name of the flag to create
default_valuethe default value for the flag.
help_strthe string displayed when the program is asked to display the help screen

Function Documentation

void ola::ParseFlags ( int *  argc,
char **  argv 
)

Parses the command line flags up to the first non-flag value. argv is re-arranged so that it only contains non-flag arguments.

Parameters
argcthe argument count taken straight from your main()
argvthe argument vector which holds the actual arguments from the command line. Also comes from main().
void ola::SetHelpString ( const std::string &  first_line,
const std::string &  description 
)

Set the help string for the program.

Parameters
first_linethe initial line that is displayed in the help section. This is displayed after argv[0].
descriptiona multiline description of the program