nl::ArgParser

مجموعه‌ای از آرگومان‌های سبک خط فرمان را تجزیه می‌کند و توابع مدیریت را برای پردازش هر گزینه و آرگومان غیرگزینه‌ای فراخوانی می‌کند.

‫ParseArgs()‎ فهرستی از آرگومان‌ها (argv) را می‌گیرد و آن‌ها را براساس مجموعه‌ای از تعاریف گزینه ارائه‌شده تجزیه می‌کند. این تابع از هر دو گزینه طولانی (opt) و کوتاه (-o) پشتیبانی می‌کند و همان نحو گزینه تابع GNU getopt_long(3) را پیاده‌سازی می‌کند.

تعاریف گزینه به‌عنوان آرایه‌ای از ساختارهای OptionSet‏ (optSets) به ParseArgs()‎ ارسال می‌شوند. هر OptionSet حاوی آرایه‌ای از تعاریف گزینه و یک تابع گرداننده است. ParseArgs()‎ آرگومان‌های گزینه را به ترتیب داده‌شده پردازش می‌کند و تابع گرداننده مربوطه را برای هر گزینه شناسایی‌شده فراخوانی می‌کند. وقتی همه گزینه‌ها تجزیه شدند، یک تابع گرداننده غیرگزینه‌ای جداگانه (nonOptArgHandler) یک‌بار فراخوانی می‌شود تا هر آرگومان باقی‌مانده را پردازش کند.

مجموعه‌های گزینه

OptionSet حاوی مجموعه‌ای از تعاریف گزینه به‌همراه اشاره‌گری به تابع کنترل‌کننده است که هنگام مواجهه با یکی از گزینه‌های مرتبط فراخوانده می‌شود. مجموعه‌های گزینه همچنین حاوی نوشتار راهنمایی هستند که نحو و هدف هر گزینه را شرح می‌دهد (به «راهنمای گزینه» در زیر مراجعه کنید). مجموعه‌های گزینه برای ایجاد مجموعه‌های بازکاربردپذیر از گزینه‌های مرتبط طراحی شده‌اند. این کار تلاش لازم برای نگهداری چندین برنامه را که گزینه‌های مشابهی را می‌پذیرند (مثلاً برنامه‌های آزمایشی) ساده می‌کند.

دو الگو برای تعریف OptionSet وجود دارد: می‌توان نمونه‌ای از ساختار OptionSet را مقداردهی اولیه کرد، مثلاً به‌عنوان یک سراسری ایستا، یا زیرکلاس OptionSetBase و ارائه یک سازنده. مورد دوم از تابع مجازی خالص HandleOption() برای واگذاری مدیریت گزینه به زیرکلاس استفاده می‌کند.

فهرست‌های OptionSets به‌عنوان آرایه‌ای از اشاره‌گرها با پایان NULL به تابع 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 سازمان‌دهی شده‌اند، که هر عنصر شامل موارد زیر است: نام گزینه، شناسه عدد صحیحی که برای شناسایی گزینه استفاده می‌شود، و اینکه آیا گزینه انتظار آرگومان دارد یا اجازه آن را می‌دهد. پایان آرایه گزینه با فیلد «نام» 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 که در آن ظاهر می‌شوند، هستند و بنابراین ممکن است در OptionSetهای مختلف دوباره استفاده شوند (اما به «گزینه‌های کوتاه» در زیر مراجعه کنید). قرارداد معمول این است که شماره‌گذاری شناسه‌های گزینه از ۱۰۰۰ شروع شود، اما هر عددی بزرگ‌تر از ۱۲۸ می‌تواند استفاده شود. گزینه‌های نام مستعار را می‌توان بااستفاده از شناسه گزینه یکسان با نام‌های گزینه متفاوت ایجاد کرد.

گزینه‌های کوتاه

برخلاف 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";

گروه‌های راهنمایی اختیاری

OptionSets حاوی رشته HelpGroupName است که برای گروه‌بندی گزینه‌ها در خروجی راهنما استفاده می‌شود. تابع PrintOptionHelp() از HelpGroupName به‌عنوان عنوان بخش در برونداد استفاده تولیدشده استفاده می‌کند. اگر چند OptionSet دارای HelpGroupName یکسان باشند، PrintOptionHelp()‎ راهنمای گزینه را برای OptionSetهای مختلف باهم تحت عنوان بخش مشترک چاپ می‌کند.

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
)