nl::ArgParser

Parsen Sie eine Reihe von Befehlszeilenargumenten und rufen Sie Verarbeitungsfunktionen zur Verarbeitung der einzelnen Optionen und Nicht-Options-Argumente auf.

ParseArgs() nimmt eine Liste von Argumenten (argv) und parst sie gemäß einem Satz von bereitgestellten Optionsdefinitionen. Die Funktion unterstützt die Optionen long (opt) und kurz (-o) und implementiert dieselbe Optionssyntax wie die GNU-Funktion getopt_long(3).

Optionsdefinitionen werden als Array von OptionSet-Strukturen (optSets) an ParseArgs() übergeben. Jedes OptionSet enthält ein Array von Optionsdefinitionen und eine Handler-Funktion. ParseArgs() verarbeitet Optionsargumente in der angegebenen Reihenfolge und ruft für jede erkannte Option die entsprechende Handler-Funktion auf. Nachdem alle Optionen geparst wurden, wird einmal eine separate Nicht-Options-Handler-Funktion (nonOptArgHandler) 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 Hilfetext zur Syntax und zum Zweck der einzelnen Optionen (siehe OPTION-HILFE unten). Mit Optionssätzen können wiederverwendbare Sammlungen verwandter Optionen erstellt werden. Dies vereinfacht die Verwaltung mehrerer Anwendungen, die ähnliche Optionen akzeptieren (z.B. Testanwendungen).

Es gibt zwei Muster für die Definition von OptionSetsone. Sie können entweder eine Instanz der OptionSet-Struktur selbst initialisieren, z. B. als statische globale, oder eine Unterklasse von OptionSetBase und einen Konstruktor bereitstellen. Letzteres verwendet eine reine virtuelle HandleOption()-Funktion, um die Optionenverarbeitung an die Unterklasse zu delegieren.

Listen von OptionSets werden als NULL-terminiertes Array von Zeigern an die Funktion ParseArgs() ü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 Folgendes enthält: den Namen der Option, eine Ganzzahl-ID zur Identifizierung der Option und ob die Option ein Argument erwartet oder zulässt. Das Ende des Optionsarrays wird durch ein NULL-Name-Feld 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 }
};

OPTION-IDs

Mit Options-IDs werden Optionen für den Code identifiziert, der sie verarbeitet (Funktion OptionHandler). Options-IDs beziehen sich auf das OptionSet, in dem sie erscheinen, und können daher in verschiedenen OptionSets wiederverwendet werden (siehe KURZOPTIONEN unten). Üblicherweise beginnen Nummerierungsoptionen bei 1000, es kann jedoch auch eine beliebige Zahl > 128 verwendet werden. Alias-Optionen können mithilfe derselben Options-ID mit unterschiedlichen Optionsnamen erstellt werden.

KURZ OPTIONEN

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

ParseArgs() erfordert, dass kurze Optionszeichen in allen OptionSets eindeutig sind. Aus diesem Grund wird von der Verwendung kurzer Optionen für OptionsSets abgeraten, die programmübergreifend genutzt werden, da die Gefahr von Kollisionen sehr hoch ist. Kurze Optionszeichen können in einem einzelnen OptionSet wiederverwendet werden, um das Erstellen langer Optionsnamen mit Aliasnamen zu ermöglichen.

HILFE ZU OPTIONEN

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

Konventionsgemäß bestehen Optionshilfestrings aus einem Syntaxbeispiel, gefolgt von einer Textbeschreibung der Option. Wenn die Option eine Kurzversion oder einen Aliasnamen hat, wird sie vor dem primären Langnamen angegeben. Aus Konsistenzgründen werden Syntaxzeilen mit 2 Leerzeichen eingerückt, Textzeilen mit 7 Leerzeichen. 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";

OPTION-HILFEGRUPPEN

OptionSets enthalten einen HelpGroupName-String, mit dem Optionen in der Hilfeausgabe gruppiert werden. Die Funktion PrintOptionHelp() verwendet HelpGroupName als Abschnittstitel in der generierten Nutzungsausgabe. Wenn mehrere OptionSets denselben HelpGroupName haben, druckt PrintOptionHelp() die Hilfe zu den verschiedenen OptionSets 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
)