nl::ArgParser

Analizuj zestaw argumentów w stylu wiersza poleceń, wywołując funkcje obsługi w celu przetworzenia każdej opcji i argumentu niebędącego opcją.

Funkcja ParseArgs() pobiera listę argumentów (argv) i analizuje je zgodnie z zestawem podanych definicji opcji. Funkcja obsługuje zarówno opcje długie (opt), jak i krótkie (-o) oraz implementuje taką samą składnię opcji jak w przypadku funkcji GNU getopt_long(3).

Definicje opcji są przekazywane do ParseArgs() w postaci tablicy struktur OptionSet (optSets). Każdy element OptionSet zawiera tablicę definicji opcji oraz 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 jednokrotnie wywoływana jest osobna funkcja obsługi niebędąca opcją (nonOptArgHandler), aby przetworzyć pozostałe argumenty.

ZBIORY OPCJI

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

Istnieją 2 wzorce do definiowania OptionSetsone, które mogą zainicjować instancję konstrukcji OptionSet, np. jako globalną statyczną, lub podklasę OptionSetBase i udostępnić konstruktor. Wykorzystuje ona czystą wirtualną funkcję HandleOption() do delegowania obsługi opcji do podklasy.

Listy pozycji OptionSet są przekazywane do funkcji ParseArgs() jako tablica wskaźników z wartością 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 mają postać tablicy elementów OptionDef, w której każdy element zawiera: nazwę opcji, liczbę całkowitą służącą do jej zidentyfikowania oraz informację o tym, czy dana opcja oczekuje lub zezwala na argument. Koniec tablicy opcji jest sygnalizowany przez pole Nazwa o wartości 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 określają opcje w kodzie, który je obsługuje (funkcja OptionHandler). Identyfikatory opcji odnoszą się do elementu OptionSet, w którym się pojawiają, i dlatego można ich używać ponownie w różnych parametrach OptionSet (jednak patrz KRÓTKIE OPCJE poniżej). Zazwyczaj identyfikatory opcji numerowania zaczynają się od 1000, ale można użyć dowolnej liczby > 128. Opcje aliasów możesz utworzyć, korzystając z tego samego identyfikatora opcji z różnymi nazwami opcji.

OPCJE KRÓTKIE

W przeciwieństwie do getopt_long(3) funkcja ParseArgs() nie pobiera osobnego ciągu tekstowego zawierającego listę krótkich znaków opcji. Dowolna opcja, której wartość identyfikatora mieści się w zakresie graficznych znaków ASCII, umożliwia użycie tego znaku jako krótkiej opcji.

Funkcja ParseArgs() wymaga, aby krótkie znaki opcji były niepowtarzalne we wszystkich elementach OptionSet. Z tego względu odradzamy stosowanie krótkich opcji w przypadku korzystania z zbiorów OptionSets współdzielonych przez różne programy ze względu na wysokie ryzyko kolizji. Krótkich znaków opcji można używać w pojedynczym elemencie OptionSet, aby tworzyć długie aliasy nazw opcji.

POMOC DOTYCZĄCA OPCJI

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

Zgodnie z konwencją ciągi pomocy dotyczące opcji składają się z przykładowej składni, po której następuje jej opis tekstowy. Jeśli opcja ma krótką wersję lub nazwę aliasu, jest ona podana przed podstawową długą nazwą. Aby zachować spójność, wiersze składni są wcięte po 2 spacjami, a linie tekstu – po 7 spacji. Po każdym opisie 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 OPCJI

Zestawy OptionSets zawierają ciąg znaków HelpGroupName, który służy do grupowania opcji w danych wyjściowych pomocy. Funkcja PrintOptionHelp() używa nazwy Grupy Pomocy jako tytułu sekcji w wygenerowanych danych wyjściowych dotyczących użycia. Jeśli wiele parametrów OptionSet ma tę samą nazwę HelpGroupName, funkcja PrintOptionHelp() wyświetla pomoc dotyczącą różnych OptionSets 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
)