nl::ArgParser

कमांड लाइन-स्टाइल आर्ग्युमेंट के सेट को पार्स करें. साथ ही, हर विकल्प और नॉन-विकल्प आर्ग्युमेंट को प्रोसेस करने के लिए, हैंडलिंग फ़ंक्शन को कॉल करें.

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

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

विकल्प सेट

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

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

विकल्प सेट की सूचियों को ParseArgs() फ़ंक्शन में, पॉइंटर के शून्य-खत्म किए गए कलेक्शन के तौर पर पास किया जाता है. 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 एलिमेंट के कलेक्शन के तौर पर व्यवस्थित होती हैं. यहां हर एलिमेंट में ये चीज़ें शामिल होती हैं: विकल्प का नाम, विकल्प की पहचान करने के लिए इस्तेमाल किया जाने वाला पूर्णांक आईडी, और यह विकल्प कि क्या विकल्प के लिए कोई तर्क मौजूद है/अनुमति है या नहीं. विकल्प अरे के खत्म होने का संकेत, शून्य नाम वाले फ़ील्ड से दिया जाता है. 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 जिसमें वे दिखते हैं, उसके हिसाब से होते हैं और इसलिए अलग-अलग OptionSet में फिर से इस्तेमाल किए जा सकते हैं (हालांकि नीचे छोटा विकल्प देखें). सामान्य तौर पर, विकल्प आईडी को 1,000 पर संख्या से शुरू करना होता है, हालांकि कोई भी संख्या > सिर्फ़ 128 कोड का इस्तेमाल किया जा सकता है. उपनाम के विकल्प, अलग-अलग विकल्प नामों वाले एक ही विकल्प आईडी का इस्तेमाल करके बनाए जा सकते हैं.

छोटे विकल्प

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

ParseArgs() के लिए यह ज़रूरी है कि सभी 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
)