Open Lighting Architecture: Command Line Flags

| Open Lighting Architecture 0.10.9

Loading...
Searching...
No Matches
Files | Namespaces | Classes | Macros | Functions | Variables
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. --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
  DECLARE_bool
  #define DECLARE_bool(name)
  Reuse a bool flag from another file.
  Definition Flags.h:121

## 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
namespace | 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)
| Reuse a bool flag from another file.
#define | DECLARE_int8(name)
| Reuse an int8_t flag from another file.
#define | DECLARE_int16(name)
| Reuse an int16_t flag from another file.
#define | DECLARE_int32(name)
| Reuse an int32_t flag from another file.
#define | DECLARE_uint8(name)
| Reuse a uint8_t flag from another file.
#define | DECLARE_uint16(name)
| Reuse a uint16_t flag from another file.
#define | DECLARE_uint32(name)
| Reuse a uint32_t flag from another file.
#define | DECLARE_string(name)
| Reuse a string flag from another file.
#define | DEFINE_bool(name, default_value, help_str)
| Create a new longname bool flag.
#define | DEFINE_s_bool(name, short_opt, default_value, help_str)
| Create a new bool flag with a long and short name.
#define | DEFINE_default_bool(name, default_value, help_str)
| Create a new longname bool flag that doesn't require an argument.
#define | DEFINE_s_default_bool(name, short_opt, default_value, help_str)
| Create a new bool flag with a long and short name that doesn't require an argument.
#define | DEFINE_int8(name, default_value, help_str)
| Create a new longname int8_t flag.
#define | DEFINE_s_int8(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)
| Create a new longname uint8_t flag.
#define | DEFINE_s_uint8(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)
| Create a new longname int16_t flag.
#define | DEFINE_s_int16(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)
| Create a new longname uint16_t flag.
#define | DEFINE_s_uint16(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)
| Create a new longname int32_t flag.
#define | DEFINE_s_int32(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)
| Create a new longname uint32_t flag.
#define | DEFINE_s_uint32(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)
| Create a new longname string flag.
#define | DEFINE_s_string(name, short_opt, default_value, help_str)
| Create a new string flag with a long and short name.

## Functions
void | ola::SetHelpString (const std::string &first_line, const std::string &description)
| Set the help string for the program.
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.
FlagRegistry * | ola::GetRegistry ()
| Get the global FlagRegistry.
bool | ola::Flag< T >::SetValue (const std::string &input)
| Used to set the value of a flag.

## Variables
const char | ola::Flag< bool >::NO_PREFIX [] = "no-"

## Macro Definition Documentation

## ◆ DECLARE_bool

#define DECLARE_bool | ( |  | name | ) |

Value:
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 | ) |

Value:
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 | ) |

Value:
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 | ) |

Value:
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 | ) |

Value:
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 | ) |

Value:
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 | ) |

Value:
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 | ) |

Value:
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 )

Value:
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 )

Value:
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 )

Value:
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 )

Value:
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 )

Value:
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 )

Value:
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 )

Value:
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 )

Value:
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 )

Value:
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 )

Value:
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 )

Value:
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

## ◆ SetValue()

template<typename T>

bool ola::Flag< T >::SetValue | ( | const std::string & | input | ) |
| virtual

Used to set the value of a flag.

Implements ola::FlagInterface.

## Variable Documentation

## ◆ Flag< bool >::NO_PREFIX

const char ola::Flag< bool >::NO_PREFIX[] = "no-"

The prefix used on inverted bool flags

Example
  DEFINE_s_default_bool(noMaster, d, false, "Dummy flag to show NO_PREFIX")
  DEFINE_s_default_bool
  #define DEFINE_s_default_bool(name, short_opt, default_value, help_str)
  Create a new bool flag with a long and short name that doesn't require an argument.
  Definition Flags.h:237

Then if you called your application with that flag:

bash$myapplication -d

Then the noMaster flag would be true.