nl::ArgParser

Analizza un insieme di argomenti in stile riga di comando, chiamando le funzioni di gestione per elaborare ogni opzione e ogni argomento non opzione.

ParseArgs() prende un elenco di argomenti (argv) e li analizza in base a un insieme di definizioni di opzioni fornite. La funzione supporta le opzioni long (opt) e short (-o) e implementa la stessa sintassi delle opzioni della funzione GNU getopt_long(3).

Le definizioni di opzione vengono passate a ParseArgs() sotto forma di array di strutture OptionSet (optSets). Ogni OptionSet contiene un array di definizioni di opzioni e una funzione di gestore. ParseArgs() elabora gli argomenti delle opzioni nell'ordine specificato, richiamando la rispettiva funzione di gestore per ogni opzione riconosciuta. Dopo aver analizzato tutte le opzioni, viene richiamata una funzione separata del gestore senza opzioni (nonOptArgHandler) per elaborare eventuali argomenti rimanenti.

SET DI OPZIONI

Un OptionSet contiene un insieme di definizioni di opzioni insieme a un puntatore a una funzione gestore che verrà richiamata quando viene rilevata una delle opzioni associate. I set di opzioni contengono inoltre testo della guida che descrive la sintassi e lo scopo di ciascuna opzione (consulta la GUIDA ALLE OPZIONI di seguito). Gli insiemi di opzioni sono progettati per consentire la creazione di raccolte riutilizzabili di opzioni correlate. In questo modo si semplifica l'impegno necessario per gestire più applicazioni che accettano opzioni simili (ad es. applicazioni di test).

Esistono due pattern per la definizione di optionSets; è possibile inizializzare un'istanza dello struct OptionSet stesso, ad esempio come globale statico, oppure la sottoclasse OptionSetBase e fornire un costruttore. La seconda utilizza una funzione HandleOption() pura virtuale per delegare la gestione delle opzioni alla sottoclasse.

Gli elenchi di opzioni vengono passati alla funzione ParseArgs() come array di puntatori con terminazione 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))
    {
        ...
    }
}

DEFINIZIONI OPZIONE

Le opzioni vengono definite utilizzando la struttura OptionDef. Le definizioni delle opzioni sono organizzate come un array di elementi OptionDef, dove ogni elemento contiene: il nome dell'opzione, un ID intero utilizzato per identificare l'opzione e se l'opzione prevede o consente un argomento. La fine dell'array di opzioni è segnalata da un campo Nome 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 }
};

ID OPZIONI

Gli ID opzione identificano le opzioni del codice che le gestisce (la funzione OpzioneHandler). Gli ID opzione sono relativi al set di opzioni OptionSet in cui appaiono e possono quindi essere riutilizzati in diversi set di opzioni (tuttavia, vedi OPZIONI BREVE di seguito). È prassi comune far iniziare gli ID delle opzioni di numerazione da 1000, tuttavia è possibile utilizzare qualsiasi numero maggiore di 128. Le opzioni di alias possono essere create utilizzando lo stesso ID opzione con nomi diversi per le opzioni.

OPZIONI BREVE

A differenza di getopt_long(3), ParseArgs() non prende una stringa separata che specifica l'elenco di caratteri di opzione brevi. Piuttosto, qualsiasi opzione il cui valore ID rientra nell'intervallo di caratteri ASCII grafici consente di utilizzare quel carattere come opzione breve.

ParseArgs() richiede che i caratteri di opzione brevi siano univoci in tutti gli OpzioneSet. Per questo motivo, è sconsigliato utilizzare opzioni brevi per gli optionSet condivisi tra programmi, a causa della notevole probabilità di collisioni. I caratteri delle opzioni brevi possono essere riutilizzati all'interno di un singolo OptionSet per consentire la creazione di nomi di opzioni lunghi alias.

GUIDA PER L'OPZIONE

Ogni OptionSet contiene una stringa OptionHelp che descrive lo scopo e la sintassi delle opzioni associate. Queste stringhe vengono utilizzate dalla funzione PrintOptionHelp() per generare informazioni sull'utilizzo delle opzioni.

Per convenzione, le stringhe della guida per le opzioni consistono in un esempio di sintassi seguito da una descrizione testuale dell'opzione. Se l'opzione ha una versione breve o un nome alias, questo verrà fornito prima del nome lungo principale. Per coerenza, il rientro delle righe di sintassi è di 2 spazi, mentre quello delle righe descrittive di 7 spazi. Una riga vuota segue la descrizione di ogni opzione, inclusa l'ultima.

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

OPZIONE GRUPPI DI GUIDA

I set di opzioni contengono una stringa HelpGroupName che viene utilizzata per raggruppare le opzioni nell'output della guida. La funzione PrintOptionHelp() utilizza HelpGroupName come titolo di sezione nell'output di utilizzo generato. Se più opzioni hanno lo stesso HelpGroupName, PrintOptionHelp() stamperà la guida per le diverse opzioni con un titolo di sezione comune.

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
)