nl::ArgParser

कमांड लाइन-स्टाइल वाले तर्कों के सेट को पार्स करें. साथ ही, हर विकल्प और विकल्प के अलावा दूसरी चीज़ों वाले तर्क को प्रोसेस करने के लिए हैंडलिंग फ़ंक्शन को कॉल करें.

ParseArgs(), तर्कों (argv) की एक सूची लेता है. साथ ही, दिए गए विकल्पों की परिभाषाओं के सेट के मुताबिक उन्हें पार्स करता है. यह फ़ंक्शन, लंबा (ऑप्ट) और छोटा (-o) दोनों विकल्प काम करता है. साथ ही, यह एक ही विकल्प सिंटैक्स को GNU getopt_long(3) फ़ंक्शन के रूप में लागू करता है.

विकल्प की परिभाषाएं ParseArgs() को, OptionSet स्ट्रक्चर (optSets) की ऐरे के तौर पर भेजी जाती हैं. हर OptionSet में विकल्प की परिभाषाओं का कलेक्शन और एक हैंडलर फ़ंक्शन होता है. ParseArgs(), दिए गए क्रम में विकल्प के तर्कों को प्रोसेस करता है. साथ ही, पहचाने गए हर विकल्प के लिए, उससे जुड़े हैंडलर फ़ंक्शन को कॉल करता है. सभी विकल्पों को पार्स करने के बाद, बचे हुए आर्ग्युमेंट को प्रोसेस करने के लिए, एक अलग नॉन-विकल्प हैंडलर फ़ंक्शन (nonOptArgHandler) को एक बार कॉल किया जाता है.

विकल्प सेट

OptionSet में विकल्प की परिभाषाओं का एक सेट होता है. साथ ही, हैंडलर फ़ंक्शन के लिए पॉइंटर के साथ-साथ, विकल्प की परिभाषाओं का एक सेट होता है, जिसे तब कॉल किया जाता है, जब कोई दूसरा विकल्प मिलता है. विकल्प सेट में, हर विकल्प के सिंटैक्स और मकसद के बारे में बताने वाला सहायता टेक्स्ट भी होता है (नीचे, 'विकल्प के लिए सहायता' विकल्प देखें). विकल्प के सेट को इस तरह से डिज़ाइन किया गया है कि उनसे मिलते-जुलते विकल्पों के ऐसे कलेक्शन बनाए जा सकें जिन्हें फिर से इस्तेमाल किया जा सके. यह, एक जैसे विकल्प स्वीकार करने वाले कई ऐप्लिकेशन (जैसे, टेस्ट ऐप्लिकेशन) को बनाए रखने की कोशिशों को आसान बनाता है.

OptionSetsone को परिभाषित करने के दो पैटर्न होते हैं. या तो OptionSet स्ट्रक्चर के इंस्टेंस को खुद शुरू कर सकता है, उदाहरण के लिए, स्टैटिक ग्लोबल या सब-क्लास OptionSetBase के तौर पर और कंस्ट्रक्टर दे सकता है. बाद में, सब-क्लास को विकल्प हैंडल करने का ऐक्सेस देने के लिए पूरी तरह वर्चुअल HandleOption() फ़ंक्शन का इस्तेमाल किया जाता है.

OptionSets की सूचियों को ParseArgs() फ़ंक्शन में, पॉइंटर की 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))
    {
        ...
    }
}

विकल्प की परिभाषाएं

विकल्पों को OptionDef स्ट्रक्चर का इस्तेमाल करके तय किया जाता है. विकल्प की परिभाषाएं, OptionDef एलिमेंट की कैटगरी के तौर पर व्यवस्थित की जाती हैं, जहां हर एलिमेंट में ये शामिल होते हैं: विकल्प का नाम, विकल्प की पहचान करने के लिए इस्तेमाल किया जाने वाला पूर्णांक आईडी, और विकल्प के लिए तर्क देना ज़रूरी है या नहीं. विकल्प कलेक्शन का आखिरी हिस्सा, 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 }
};

विकल्प आईडी

विकल्प आईडी, उन्हें मैनेज करने वाले कोड के विकल्पों की पहचान करते हैं (OptionHandler फ़ंक्शन). विकल्प आईडी, उस OptionSet के मुताबिक होते हैं जिसमें वे दिखते हैं. इसलिए, इन्हें अलग-अलग OptionSets पर फिर से इस्तेमाल किया जा सकता है (हालांकि, नीचे Shorts के विकल्प देखें). आम तौर पर, विकल्प आईडी को 1,000 पर नंबर देना शुरू किया जाता है. हालांकि, 128 से ज़्यादा संख्या का इस्तेमाल किया जा सकता है. उपनाम के विकल्प, एक ही विकल्प आईडी का इस्तेमाल करके अलग-अलग विकल्प नामों के साथ बनाए जा सकते हैं.

छोटे विकल्प

getopt_long(3) के उलट, ParseArgs(), छोटे विकल्प वाले वर्णों की सूची के बारे में बताने वाली अलग स्ट्रिंग नहीं लेता है. इसके बजाय, कोई भी विकल्प जिसका आईडी मान ग्राफ़िकल ASCII वर्णों की श्रेणी में आता है, उस वर्ण को एक छोटे विकल्प के रूप में इस्तेमाल करने की अनुमति देगा.

ParseArgs() के लिए ज़रूरी है कि छोटे विकल्प वाले वर्ण, सभी OptionSets के लिए यूनीक हों. इस वजह से, सभी प्रोग्राम में शेयर किए गए ऐसे OptionSets के लिए छोटे विकल्पों का इस्तेमाल नहीं करना चाहिए जिनमें टकराव होने की संभावना ज़्यादा होती है. उपनाम वाले लंबे विकल्पों के नाम बनाने की अनुमति देने के लिए, एक OptionSet के अंदर छोटे विकल्प वाले वर्णों का फिर से इस्तेमाल किया जा सकता है.

विकल्प सहायता

हर OptionSet में एक OptionHelp स्ट्रिंग होती है, जो उससे जुड़े विकल्पों के मकसद और सिंटैक्स की जानकारी देती है. विकल्प के इस्तेमाल की जानकारी जनरेट करने के लिए, PrintOptionHelp() फ़ंक्शन इन स्ट्रिंग का इस्तेमाल करता है.

कन्वेंशन के मुताबिक, विकल्प सहायता स्ट्रिंग में सिंटैक्स का एक उदाहरण होता है. इसके बाद, विकल्प के बारे में टेक्स्ट के रूप में जानकारी दी जाती है. अगर विकल्प का छोटा वर्शन या कोई उपनाम नाम है, तो इसे मुख्य लंबे नाम से पहले दिया जाता है. एक जैसा स्टाइल बनाए रखने के लिए, सिंटैक्स की लाइनों को दो स्पेस से और ब्यौरे में सात स्पेस का इंडेंट किया जाता है. एक खाली लाइन, हर विकल्प की जानकारी के बाद दिखती है. इसमें आखिरी विकल्प भी शामिल होता है.

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

विकल्प सहायता ग्रुप

OptionSet में एक HelpGroupName स्ट्रिंग होती है. इसका इस्तेमाल, सहायता आउटपुट में विकल्पों को एक साथ ग्रुप करने के लिए किया जाता है. PrintOptionHelp() फ़ंक्शन, इस्तेमाल के जनरेट किए गए आउटपुट में, सेक्शन के शीर्षक के तौर पर HelpGroupName का इस्तेमाल करता है. अगर एक से ज़्यादा OptionSets के लिए एक ही HelpGroupName होता है, तो PrintOptionHelp() एक ही सेक्शन के टाइटल में, अलग-अलग OptionSets के लिए, विकल्प से जुड़ी सहायता को एक साथ प्रिंट करता है.

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
)