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:

• bool, uint8, uint16, uint32, int8, int16, int32 & string types.
• short options (e.g. -x).
• inverted bools, e.g. –nofoo

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_*:

DECLARE_bool(foo);
DECLARE_bool(bar);
// 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

name	the name of the flag to reuse

#define DECLARE_int16

(

name

)

DECLARE_flag(int16_t, name)

Reuse an int16_t flag from another file.

Parameters

name	the name of the flag to reuse

#define DECLARE_int32

(

name

)

DECLARE_flag(int32_t, name)

Reuse an int32_t flag from another file.

Parameters

name	the name of the flag to reuse

#define DECLARE_int8

(

name

)

DECLARE_flag(int8_t, name)

Reuse an int8_t flag from another file.

Parameters

name	the name of the flag to reuse

#define DECLARE_string

(

name

)

DECLARE_flag(std::string, name)

Reuse a string flag from another file.

Parameters

name	the name of the flag to reuse

#define DECLARE_uint16

(

name

)

DECLARE_flag(uint16_t, name)

Reuse a uint16_t flag from another file.

Parameters

name	the name of the flag to reuse

#define DECLARE_uint32

(

name

)

DECLARE_flag(uint32_t, name)

Reuse a uint32_t flag from another file.

Parameters

name	the name of the flag to reuse

#define DECLARE_uint8

(

name

)

DECLARE_flag(uint8_t, name)

Reuse a uint8_t flag from another file.

Parameters

name	the 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

name	the name of the flag to create
default_value	the default value for the flag. Either true, or false.
help_str	the 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

name	the name of the flag to create
default_value	the default value for the flag.
help_str	the 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

name	the name of the flag to create
default_value	the default value for the flag.
help_str	the 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

name	the name of the flag to create
default_value	the default value for the flag.
help_str	the 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

name	the full name of the flag to create
short_opt	the short name of the flag. For example "-h", or "-d".
default_value	the default value for the flag. Either true, or false
help_str	the 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

name	the full name of the flag to create
short_opt	the short name of the flag. For example "-h", or "-d".
default_value	the default value for the flag.
help_str	the 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

name	the full name of the flag to create
short_opt	the short name of the flag. For example "-h", or "-d".
default_value	the default value for the flag.
help_str	the 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

name	the full name of the flag to create
short_opt	the short name of the flag. For example "-h", or "-d".
default_value	the default value for the flag.
help_str	the 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

name	the full name of the flag to create
short_opt	the short name of the flag. For example "-h", or "-d".
default_value	the default value for the flag.
help_str	the 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

name	the full name of the flag to create
short_opt	the short name of the flag. For example "-h", or "-d".
default_value	the default value for the flag.
help_str	the 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

name	the full name of the flag to create
short_opt	the short name of the flag. For example "-h", or "-d".
default_value	the default value for the flag.
help_str	the 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

name	the full name of the flag to create
short_opt	the short name of the flag. For example "-h", or "-d".
default_value	the default value for the flag.
help_str	the 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

name	the name of the flag to create
default_value	the default value for the flag.
help_str	the 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

name	the name of the flag to create
default_value	the default value for the flag.
help_str	the 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

name	the name of the flag to create
default_value	the default value for the flag.
help_str	the 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

name	the name of the flag to create
default_value	the default value for the flag.
help_str	the 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

argc	the argument count taken straight from your main()
argv	the argument vector which holds the actual arguments from the command line. Also comes from main().