Open Lighting Architecture  0.9.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Files | Namespaces | 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 --nobar.
DEFINE_bool(foo, false, "Enable feature foo");
DEFINE_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

Files

file  Flags.cpp
file  Flags.h
 Defines macros to ease creation of command line flags.

Namespaces

namespace  ola
 The namespace containing all OLA symbols.

Macros

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

Functions

void ola::SetHelpString (const string &first_line, const string &description)
void ola::DisplayUsage ()
 Print the usage text to stdout.
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.

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)

Create a new longname bool flag.

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)

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)

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)

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)

Create a new 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. 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 
)    DEFINE_flag_with_short(int16_t, name, short_opt, default_value, help_str)

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 
)    DEFINE_flag_with_short(int32_t, name, short_opt, default_value, help_str)

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 
)    DEFINE_flag_with_short(int8_t, name, short_opt, default_value, help_str)

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 
)    DEFINE_flag_with_short(std::string, name, short_opt, default_value, help_str)

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 
)    DEFINE_flag_with_short(uint16_t, name, short_opt, default_value, help_str)

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 
)    DEFINE_flag_with_short(uint32_t, name, short_opt, default_value, help_str)

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 
)    DEFINE_flag_with_short(uint8_t, name, short_opt, default_value, help_str)

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)

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)

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)

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)

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().