nl::ArgParser

Mengurai kumpulan argumen bergaya command line, yang memanggil fungsi penanganan untuk memproses setiap opsi dan argumen non-opsi.

ParseArgs() mengambil daftar argumen (argv) dan mengurainya sesuai dengan kumpulan definisi opsi yang disediakan. Fungsi ini mendukung opsi panjang (opt) dan pendek (-o) dan mengimplementasikan sintaksis opsi yang sama seperti fungsi GNU getopt_long(3).

Definisi opsi diteruskan ke ParseArgs() sebagai array struktur OptionSet (optSets). Setiap OptionSet berisi array definisi opsi dan fungsi pengendali. ParseArgs() memproses argumen opsi dalam urutan tertentu, memanggil fungsi pengendali masing-masing untuk setiap opsi yang dikenal. Setelah semua opsi diuraikan, fungsi pengendali non-opsi (nonOptArgHandler) yang terpisah akan dipanggil sekali untuk memproses argumen yang tersisa.

SET OPSI

OptionSet berisi kumpulan definisi opsi beserta pointer ke fungsi pengendali yang akan dipanggil saat salah satu opsi terkait ditemukan. Kumpulan opsi juga berisi teks bantuan yang menjelaskan sintaksis dan tujuan setiap opsi (lihat BANTUAN OPSI di bawah). Kumpulan opsi didesain untuk memungkinkan pembuatan kumpulan opsi terkait yang dapat digunakan kembali. Hal ini menyederhanakan upaya yang diperlukan untuk mengelola beberapa aplikasi yang menerima opsi serupa (misalnya, aplikasi pengujian).

Ada dua pola untuk menentukan OptionSetsone yang dapat menginisialisasi instance struct OptionSet itu sendiri, misalnya sebagai global statis, atau subclass OptionSetBase dan menyediakan konstruktor. Yang kedua menggunakan fungsi HandleOption() murni murni untuk mendelegasikan penanganan opsi ke subclass.

Daftar OptionSets diteruskan ke fungsi ParseArgs() sebagai array pointer yang dihentikan NULL. Misalnya:

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))
    {
        ...
    }
}

DEFINISI OPSI

Opsi ditentukan menggunakan struktur OptionDef. Definisi opsi disusun sebagai array elemen OptionDef, dengan setiap elemen berisi: nama opsi, ID integer yang digunakan untuk mengidentifikasi opsi, dan apakah opsi mengharapkan/mengizinkan argumen. Akhir array opsi ditandai oleh kolom Nama NULL. Misalnya:

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

OPSI IDS

ID opsi mengidentifikasi opsi pada kode yang menanganinya (fungsi OptionHandler). ID opsi bersifat relatif terhadap OptionSet tempat ID tersebut muncul, sehingga dapat digunakan kembali di berbagai OptionSets (namun lihat OPSI SHORT di bawah). Konvensi umumnya adalah memulai ID opsi penomoran pada 1000, tetapi angka apa pun > 128 dapat digunakan. Opsi alias dapat dibuat dengan menggunakan ID opsi yang sama dengan nama opsi yang berbeda.

OPSI SHORT

Tidak seperti getopt_long(3), ParseArgs() tidak menggunakan string terpisah yang menentukan daftar karakter opsi pendek. Sebaliknya, opsi apa pun yang nilai ID-nya berada dalam rentang karakter ASCII grafis akan memungkinkan karakter tersebut digunakan sebagai opsi singkat.

ParseArgs() mengharuskan karakter opsi pendek bersifat unik di semua OptionSet. Oleh karena itu, penggunaan opsi singkat tidak disarankan untuk segala Set Opsi yang dibagikan lintas program karena besar kemungkinan terjadi benturan. Karakter opsi pendek dapat digunakan kembali dalam satu OptionSet untuk memungkinkan pembuatan nama opsi panjang alias.

OPSI BANTUAN

Setiap OptionSet berisi string OptionHelp yang menjelaskan tujuan dan sintaksis opsi terkait. String ini digunakan oleh fungsi PrintOptionHelp() untuk menghasilkan informasi penggunaan opsi.

Berdasarkan konvensi, string bantuan opsi terdiri dari contoh sintaksis yang diikuti dengan deskripsi tekstual opsi. Jika opsi memiliki versi singkat, atau nama alias, nama tersebut akan diberikan sebelum nama panjang utama. Agar konsisten, baris sintaksis diberi indentasi dengan 2 spasi, sementara baris deskripsi diindentasi dengan 7 spasi. Satu baris kosong akan mengikuti setiap deskripsi opsi, termasuk yang terakhir.

Misalnya:

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

OPSI GRUP BANTUAN

OptionSet berisi string HelpGroupName yang digunakan untuk mengelompokkan opsi dalam output bantuan. Fungsi PrintOptionHelp() menggunakan HelpGroupName sebagai judul bagian dalam output penggunaan yang dihasilkan. Jika beberapa OptionSets memiliki HelpGroupName yang sama, PrintOptionHelp() akan mencetak opsi bantuan untuk OptionSets yang berbeda dalam satu judul bagian yang sama.

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
)