nl::ArgParser

Parse a set of command line-style arguments, calling handling functions to process each option and non-option argument.

ParseArgs() takes a list of arguments (argv) and parses them according to a set of supplied option definitions. The function supports both long (opt) and short (-o) options and implements the same option syntax as the GNU getopt_long(3) function.

Option definitions are passed to ParseArgs() as an array of OptionSet structures (optSets). Each OptionSet contains an array of option definitions and a handler function. ParseArgs() processes option arguments in the given order, calling the respective handler function for each recognized option. Once all options have been parsed, a separate non-option handler function (nonOptArgHandler) is called once to process any remaining arguments.

OPTION SETS

An OptionSet contains a set of option definitions along with a pointer to a handler function that will be called when one of the associated options is encountered. Option sets also contain help text describing the syntax and purpose of each option (see OPTION HELP below). Option sets are designed to allow the creation of re-usable collections of related options. This simplifies the effort needed to maintain multiple applications that accept similar options (e.g. test applications).

There are two patterns for defining OptionSetsone can either initialize an instance of the OptionSet struct itself, e.g. as a static global, or subclass OptionSetBase and provide a constructor. The latter uses a pure virtual HandleOption() function to delegate option handling to the subclass.

Lists of OptionSets are passed to the ParseArgs() function as a NULL-terminated array of pointers. E.g.:

static OptionSet gToolOptions =
{
    HandleOption,        // handler function
    gToolOptionDefs,  // array of option definitions
    "GENERAL OPTIONS",   // help group
    gToolOptionHelp   // option help text
};

static OptionSet *gOptionSets[] =
{
    &gToolOptions,
    &gNetworkOptions,
    &gTestingOptions,
    &gHelpOptions,
    NULL
};

int main(int argc, char *argv[])
{
    if (!ParseArgs("test-app", argc, argv, gOptionSets))
    {
        ...
    }
}

OPTION DEFINITIONS

Options are defined using the OptionDef structure. Option definitions are organized as an array of OptionDef elements, where each element contains: the name of the option, a integer id that is used to identify the option, and whether the option expects/allows an argument. The end of the option array is signaled by a NULL Name field. E.g.:

enum
{
    kOpt_Listen = 1000,
    kOpt_Length,
    kOpt_Count,
};

static OptionDef gToolOptionDefs[] =
{
    // NAME         REQUIRES/ALLOWS ARG?  ID/SHORT OPTION CHAR
    // ============================================================
    {  "listen",    kNoArgument,          kOpt_Listen     },
    {  "length",    kArgumentRequired,    kOpt_Length     },
    {  "count",     kArgumentRequired,    kOpt_Count      },
    {  "num",       kArgumentRequired,    kOpt_Count      }, // alias for --count
    {  "debug",     kArgumentOptional,    'd'             },
    {  "help",      kNoArgument,          'h'             },
    {  NULL }
};

OPTION IDS

Option ids identify options to the code that handles them (the OptionHandler function). Option ids are relative to the OptionSet in which they appear, and thus may be reused across different OptionSets (however see SHORT OPTIONS below). Common convention is to start numbering option ids at 1000, however any number > 128 can be used. Alias options can be created by using the same option id with different option names.

SHORT OPTIONS

Unlike getopt_long(3), ParseArgs() does not take a separate string specifying the list of short option characters. Rather, any option whose id value falls in the range of graphical ASCII characters will allow that character to be used as a short option.

ParseArgs() requires that short option characters be unique across all OptionSets. Because of this, the use of short options is discouraged for any OptionSets that are shared across programs due to the significant chance for collisions. Short options characters may be reused within a single OptionSet to allow for the creation of alias long option names.

OPTION HELP

Each OptionSet contains an OptionHelp string that describes the purpose and syntax of the associated options. These strings are used by the PrintOptionHelp() function to generate option usage information.

By convention, option help strings consist of a syntax example following by a textual description of the option. If the option has a short version, or an alias name, it is given before primary long name. For consistency, syntax lines are indented with 2 spaces, while description lines are indented with 7 spaces. A single blank line follows each option description, including the last one.

E.g.:

static const char *const gToolOptionHelp =
    "  --listen\n"
    "       Listen and respond to requests sent from another node.\n"
    "\n"
    "  --length \n"
    "       Send requests with the specified number of bytes in the payload.\n"
    "\n"
    "  --num, --count \n"
    "       Send the specified number of requests and exit.\n"
    "\n"
    "  -d, --debug []\n"
    "       Set debug logging to the given level. (Default: 1)\n"
    "\n"
    "  -h, --help\n"
    "       Print help information.\n"
    "\n";

OPTION HELP GROUPS

OptionSets contain a HelpGroupName string which is used to group options together in the help output. The PrintOptionHelp() function uses the HelpGroupName as a section title in the generated usage output. If multiple OptionSets have the same HelpGroupName, PrintOptionHelp() will print the option help for the different OptionSets together under a common section title.

ParseArgs

bool ParseArgs(
  const char *progName,
  int argc,
  char *argv[],
  OptionSet *optSets[]
)

bool ParseArgsFromEnvVar(
  const char *progName,
  const char *varName,
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler,
  bool ignoreUnknown
)

bool ParseArgsFromEnvVar(
  const char *progName,
  const char *varName,
  OptionSet *optSets[]
)

bool ParseArgsFromEnvVar(
  const char *progName,
  const char *varName,
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler
)

bool ParseArgsFromString(
  const char *progName,
  const char *argStr,
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler,
  bool ignoreUnknown
)

--listen --count 10 --sw-version '1.0 (DEVELOPMENT)' "--hostname=nest.com"

bool ParseArgsFromString(
  const char *progName,
  const char *argStr,
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler
)

bool ParseArgsFromString(
  const char *progName,
  const char *argStr,
  OptionSet *optSets[]
)

bool ParseBoolean(
  const char *str,
  bool & output
)

bool ParseFabricId(
  const char *str,
  uint64_t & fabricId,
  bool allowReserved
)

bool ParseHexString(
  const char *hexStr,
  uint32_t strLen,
  uint8_t *outBuf,
  uint32_t outBufSize,
  uint32_t & outDataLen
)

bool ParseIPAddress(
  const char *str,
  IPAddress & output
)

bool ParseInt(
  const char *str,
  uint64_t & output,
  int base
)

bool ParseInt(
  const char *str,
  uint32_t & output,
  int base
)

bool ParseInt(
  const char *str,
  int32_t & output,
  int base
)

bool ParseInt(
  const char *str,
  uint64_t & output
)

bool ParseInt(
  const char *str,
  uint32_t & output
)

bool ParseInt(
  const char *str,
  int32_t & output
)

bool ParseInt(
  const char *str,
  uint16_t & output
)

bool ParseInt(
  const char *str,
  int16_t & output
)

bool ParseInt(
  const char *str,
  uint8_t & output
)

bool ParseNodeId(
  const char *str,
  uint64_t & nodeId
)

bool ParseSubnetId(
  const char *str,
  uint16_t & subnetId
)

void PrintOptionHelp(
  OptionSet *optSets[],
  FILE *s
)

void PutStringWithBlankLine(
  FILE *s,
  const char *str
)

void PutStringWithNewLine(
  FILE *s,
  const char *str
)

int32_t SplitArgs(
  char *argStr,
  char **& argList,
  char *initialArg
)