nl::ArgParser

Przeanalizować zestaw argumentów w stylu wiersza poleceń, wywołując funkcje obsługi w celu przetworzenia poszczególnych opcji oraz argumentów niebędących opcjami.

ParseArgs() pobiera listę argumentów (argv) i analizuje je zgodnie z zestawem podanych definicji opcji. Funkcja ta obsługuje zarówno opcje długie (opt), jak i Short (-o), a także implementuje tę samą składnię opcji co funkcja GNU getopt_long(3).

Definicje opcji są przekazywane do ParseArgs() w postaci tablicy struktur OptionSet (optSets). Każdy element OptionSet zawiera tablicę definicji opcji i funkcję obsługi. ParseArgs() przetwarza argumenty opcji w podanej kolejności, wywołując odpowiednią funkcję obsługi dla każdej rozpoznanej opcji. Po przeanalizowaniu wszystkich opcji do przetworzenia pozostałych argumentów wywoływana jest jednorazowa funkcja obsługi innej niż opcja (nonOptArgHandler).

ZESTAW OPCJI

Element OptionSet zawiera zestaw definicji opcji wraz ze wskaźnikiem do funkcji obsługi, która zostanie wywołana po napotkaniu jednej z powiązanych opcji. Zestawy opcji zawierają również tekst pomocy opisujący składnię i przeznaczenie każdej opcji (patrz OPCJA POMOCY poniżej). Zestawy opcji umożliwiają tworzenie kolekcji powiązanych opcji do wielokrotnego użytku. Ułatwia to utrzymanie wielu aplikacji, które akceptują podobne opcje (np. aplikacje testowe).

Istnieją 2 wzorce definiowania OptionSetsone.Mogą to być albo zainicjowanie wystąpienia samej struktury OptionSet, np. jako statyczny element globalny lub podklasę OptionSetBase i udostępnić konstruktor. W tym drugim przypadku użyto czysto wirtualnej funkcji HandleOption() do przekazania obsługi opcji do podklasy.

Listy wartości OptionSet są przekazywane do funkcji ParseArgs() w postaci tablicy wskaźników z zakończeniem NULL. 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))
    {
        ...
    }
}

DEFINICJE OPCJI

Opcje definiuje się za pomocą struktury OptionDef. Definicje opcji są uporządkowane w postaci tablicy elementów OptionDef, z których każdy element zawiera: nazwę opcji, identyfikator będący liczbą całkowitą służącą do jej identyfikacji oraz informację, czy opcja oczekuje na argument. Koniec tablicy „option” jest sygnalizowany przez pole Nazwa NULL. 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 }
};

IDENTYFIKATORY OPCJI

Identyfikatory opcji identyfikują opcje w kodzie, które je obsługuje (funkcja OptionHandler). Identyfikatory opcji odnoszą się do elementów OptionSet, w których występują, i dlatego mogą być wielokrotnie wykorzystywane w różnych elementach OptionSet (zobacz jednak OPCJE SHORTS poniżej). Zazwyczaj stosuje się, aby identyfikatory opcji numerowania zaczynały się od wartości 1000, ale każda liczba > 128. Opcje aliasu można utworzyć, używając tego samego identyfikatora opcji z różnymi nazwami opcji.

OPCJE SHORT

W przeciwieństwie do metody getopt_long(3) funkcja ParseArgs() nie pobiera osobnego ciągu znaków określającego listę krótkich znaków opcji. W przypadku każdej opcji, której identyfikator mieści się w zakresie graficznych znaków ASCII, można użyć tego znaku jako krótkiej opcji.

Parametr ParseArgs() wymaga, aby krótkie znaki opcji były niepowtarzalne wśród wszystkich obiektów OptionSet. Z tego powodu odradzamy korzystanie z opcji krótkich w przypadku obiektów OptionSets, które są udostępniane między programami, ze względu na znaczne ryzyko kolizji. Krótkie znaki opcji można stosować ponownie w pojedynczym elemencie OptionSet, aby umożliwić tworzenie długich nazw opcji będących aliasami.

POMOC W OPCJI

Każdy element OptionSet zawiera ciąg znaków OptionHelp opisujący przeznaczenie i składnię powiązanych opcji. Funkcja PrintOptionHelp() używa tych ciągów znaków do generowania informacji o wykorzystaniu opcji.

Zgodnie z konwencją ciągi pomocy dotyczące opcji składają się z przykładu składni, po którym następuje opis opcji. Jeśli opcja ma krótką wersję lub nazwę aliasu, jest ona umieszczona przed długą nazwą podstawową. Dla zachowania spójności linie składni zostaną dodane do 2 spacji, a wiersze opisu – po 7 spacji. Pod każdym opisem opcji, w tym ostatnim, znajduje się jeden pusty wiersz.

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

GRUPY POMOCY W PRZYPADKU OPCJI

Zestawy OptionSet zawierają ciąg znaków HelpGroupName, który służy do grupowania opcji w danych wyjściowych pomocy. Funkcja PrintOptionHelp() wykorzystuje HelpGroupName jako tytuł sekcji w wygenerowanych danych wyjściowych dotyczących wykorzystania. Jeśli wiele zestawów OptionSet ma taką samą nazwę grupy pomocy, funkcja PrintOptionHelp() wyświetli pomoc dotyczącą opcji dla różnych zestawów opcji razem pod wspólnym tytułem sekcji.

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
)