nl::ArgParser

Parsen Sie eine Reihe von Befehlszeilenargumenten und rufen Sie Verarbeitungsfunktionen auf, um alle Optionen und Nicht-Optionsargumente zu verarbeiten.

ParseArgs() verwendet eine Liste von Argumenten (argv) und parst sie gemäß einer Reihe von bereitgestellten Optionsdefinitionen. Die Funktion unterstützt sowohl lange (opt) als auch kurze (-o) Optionen und implementiert dieselbe Optionssyntax wie die GNU getopt_long(3)-Funktion.

Optionsdefinitionen werden an ParseArgs() als Array von OptionSet-Strukturen (optSets) übergeben. Jedes OptionSet enthält ein Array mit Optionsdefinitionen und eine Handler-Funktion. ParseArgs() verarbeitet Optionsargumente in der angegebenen Reihenfolge und ruft die entsprechende Handler-Funktion für jede erkannte Option auf. Sobald alle Optionen geparst wurden, wird eine separate Handler-Funktion ohne Optionen (nonOptArgHandler) einmal aufgerufen, um alle verbleibenden Argumente zu verarbeiten.

OPTIONEN

Ein OptionSet enthält eine Reihe von Optionsdefinitionen sowie einen Zeiger auf eine Handler-Funktion, die aufgerufen wird, wenn eine der verknüpften Optionen erkannt wird. Optionssätze enthalten auch Hilfetexte zur Syntax und zum Zweck der einzelnen Optionen (siehe OPTIONEN HILFE unten). Mit Optionssätzen lassen sich wiederverwendbare Sammlungen verwandter Optionen erstellen. Dies vereinfacht die Verwaltung mehrerer Anwendungen, die ähnliche Optionen akzeptieren (z.B. Testanwendungen).

Es gibt zwei Muster zum Definieren von OptionSetsone, die entweder eine Instanz der OptionSet-Struktur selbst initialisieren können, z.B. als statische globale oder Unterklasse OptionSetBase erstellen und einen Konstruktor bereitstellen. Letzteres verwendet eine rein virtuelle HandleOption()-Funktion, um die Optionsbehandlung an die Unterklasse zu delegieren.

Listen von OptionSets werden als NULL-terminiertes Zeiger-Array an die ParseArgs()-Funktion übergeben. 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))
    {
        ...
    }
}

OPTIONENDEFINITIONEN

Optionen werden mithilfe der OptionDef-Struktur definiert. Optionsdefinitionen sind als Array von OptionDef-Elementen organisiert, wobei jedes Element den Namen der Option, eine Ganzzahl-ID zum Identifizieren der Option und die Angabe, ob die Option ein Argument erwartet oder zulässt, enthält. Das Ende des Optionsarrays wird durch ein NULL-Namensfeld signalisiert. 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 }
};

OPTIONEN-IDS

Options-IDs kennzeichnen Optionen für den Code, mit dem sie verarbeitet werden (die Option Handler-Funktion). Options-IDs beziehen sich auf das OptionSet, in dem sie angezeigt werden, und können daher für verschiedene OptionSets wiederverwendet werden (siehe KURZOPTIONEN weiter unten). Üblicherweise beginnt die Nummerierungsoption mit 1000, es kann jedoch > 128 kann verwendet werden. Alias-Optionen können erstellt werden, indem dieselbe Options-ID mit unterschiedlichen Optionsnamen verwendet wird.

KURZOPTIONEN

Im Gegensatz zu getopt_long(3) verwendet ParseArgs() keinen separaten String, der die Liste der kurzen Optionszeichen angibt. Stattdessen kann jede Option, deren ID-Wert in den Bereich der grafischen ASCII-Zeichen fällt, dieses Zeichen als kurze Option verwenden.

Für ParseArgs() müssen kurze Optionszeichen in allen OptionSets eindeutig sein. Aus diesem Grund wird von der Verwendung kurzer Optionen für OptionSets, die von mehreren Programmen gemeinsam genutzt werden, abgeraten, da die Gefahr von Kollisionen sehr hoch ist. Kurze Optionszeichen können in einem einzelnen OptionSet wiederverwendet werden, um die Erstellung von langen Alias-Optionsnamen zu ermöglichen.

OPTIONENHILFE

Jedes OptionSet enthält einen OptionHelp-String, der den Zweck und die Syntax der zugehörigen Optionen beschreibt. Diese Strings werden von der Funktion PrintOptionHelp() verwendet, um Informationen zur Nutzung von Optionen zu generieren.

Konventionsgemäß bestehen Optionshilfe-Zeichenfolgen aus einem Syntaxbeispiel, auf das eine Textbeschreibung der Option folgt. Falls die Option eine Kurzversion oder einen Aliasnamen hat, wird sie vor dem primären langen Namen angegeben. Aus Konsistenzgründen werden Syntaxzeilen mit zwei Leerzeichen und Beschreibungszeilen mit 7 Leerzeichen eingerückt. Nach jeder Optionsbeschreibung, einschließlich der letzten, folgt eine einzelne Leerzeile.

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";

OPTIONEN-HILFEGRUPPEN

OptionSets enthalten einen HelpGroupName-String, mit dem Optionen in der Hilfeausgabe gruppiert werden. Die Funktion PrintOptionHelp() verwendet den HelpGroupName als Abschnittstitel in der generierten Nutzungsausgabe. Wenn mehrere OptionSets denselben HelpGroupName haben, gibt PrintOptionHelp() die Optionshilfe für die verschiedenen OptionSets zusammen unter einem gemeinsamen Abschnittstitel aus.

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
)