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. --no-foo

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 --no-bar
--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

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 responsible 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

◆ DECLARE_bool

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

Reuse a bool flag from another file.

Parameters

name	the name of the flag to reuse

◆ DECLARE_int16

#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

◆ DECLARE_int32

#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

◆ DECLARE_int8

#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

◆ DECLARE_string

#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

◆ DECLARE_uint16

#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

◆ DECLARE_uint32

#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

◆ DECLARE_uint8

#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_bool

#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

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_default_bool

#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

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_int16

#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

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_int32

#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

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_int8

#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

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_s_bool

#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

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

#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

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_s_int16

#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

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_s_int32

#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

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_s_int8

#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

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_s_string

#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

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_s_uint16

#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

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_s_uint32

#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

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_s_uint8

#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

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_string

#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

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_uint16

#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

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_uint32

#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

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_uint8

#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

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

◆ ParseFlags()

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

◆ SetHelpString()

void ola::SetHelpString	(	const std::string &	first_line,
		const std::string &	description
	)

Set the help string for the program.

Parameters

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

Detailed Description

Files

Namespaces

Classes

Macros

Functions

Macro Definition Documentation

◆ DECLARE_bool

◆ DECLARE_int16

◆ DECLARE_int32

◆ DECLARE_int8

◆ DECLARE_string

◆ DECLARE_uint16

◆ DECLARE_uint32

◆ DECLARE_uint8

◆ DEFINE_bool

◆ DEFINE_default_bool

◆ DEFINE_int16

◆ DEFINE_int32

◆ DEFINE_int8

◆ DEFINE_s_bool

◆ DEFINE_s_default_bool

◆ DEFINE_s_int16

◆ DEFINE_s_int32

◆ DEFINE_s_int8

◆ DEFINE_s_string

◆ DEFINE_s_uint16

◆ DEFINE_s_uint32

◆ DEFINE_s_uint8

◆ DEFINE_string

◆ DEFINE_uint16

◆ DEFINE_uint32

◆ DEFINE_uint8

Function Documentation

◆ ParseFlags()

◆ SetHelpString()