nl::ArgParser

Analizzare un insieme di argomenti in stile riga di comando, chiamando le funzioni di gestione per elaborare ogni opzione e 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 sia l'opzione lunga (opt) che quella breve (-o) e implementa la stessa sintassi dell'opzione della funzione getopt_long(3) di GNU.

Le definizioni delle opzioni vengono passate a ParseArgs() come array di strutture OptionSet (optSets). Ogni elemento OptionSet contiene un array di definizioni di opzioni e una funzione gestore. ParseArgs() elabora gli argomenti delle opzioni nell'ordine specificato, chiamando la rispettiva funzione gestore per ogni opzione riconosciuta. Una volta analizzate tutte le opzioni, viene chiamata una funzione separata di gestore non opzione (nonOptArgHandler) per elaborare gli eventuali argomenti rimanenti.

SET DI OPZIONE

Un elemento OptionSet contiene un insieme di definizioni di opzioni, oltre a un puntatore a una funzione gestore che verrà richiamata quando verrà rilevata una delle opzioni associate. Gli insiemi di opzioni contengono anche testo di supporto che descrive la sintassi e lo scopo di ciascuna opzione (consulta la Guida per l'opzione di seguito). Gli insiemi di opzioni sono progettati per consentire la creazione di raccolte riutilizzabili di opzioni correlate. Ciò semplifica l'impegno necessario per gestire più applicazioni che accettano opzioni simili (ad es. applicazioni di test).

Esistono due pattern per definire l'elementoOptionSetsone può inizializzare un'istanza dello struct OptionSet stesso, ad esempio come globale statico o come sottoclasse OptionSetBase e fornisce un costruttore. Quest'ultimo utilizza una funzione HandleOption() virtuale puro per delegare la gestione delle opzioni alla sottoclasse.

Gli elenchi di set 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 DI 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 Name 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 OPZIONE

Gli ID opzione identificano le opzioni del codice che li gestisce (la funzione OpzioneGestione). Gli ID delle opzioni sono relativi all'OptionSet in cui appaiono e quindi possono essere riutilizzati in diversi set di opzioni (ma vedi OPZIONI BREVE di seguito). La convenzione comune è iniziare a inserire ID delle opzioni di numerazione a partire da 1000, ma qualsiasi numero > È possibile usare 128. Le opzioni di alias possono essere create utilizzando lo stesso ID opzione con nomi di opzioni diversi.

OPZIONI BREVE

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

ParseArgs() richiede che i caratteri di opzione brevi siano univoci in tutti i set di opzioni. Per questo motivo, l'uso di opzioni brevi è sconsigliato per gli opzioni condivisi tra i 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 OPZIONE

Ogni elemento 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 sono costituite da un esempio di sintassi seguito da una descrizione testuale dell'opzione. Se l'opzione ha una versione breve o un nome alias, viene inserito prima del nome lungo principale. Per coerenza, le righe di sintassi sono rientrate con 2 spazi, mentre le righe descrittive sono rientrate con 7 spazi. Una singola riga vuota segue ogni descrizione dell'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";

GRUPPI DI ASSISTENZA OPZIONE

Gli optional contengono una stringa HelpGroupName che viene utilizzata per raggruppare le opzioni nell'output della guida. La funzione PrintOptionHelp() utilizza il valore HelpGroupName come titolo della sezione nell'output di utilizzo generato. Se più opzioni hanno lo stesso HelpGroupName, PrintOptionHelp() stampa la guida per le opzioni diverse 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
)