nl:: ArgParser

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

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

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

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

یک OptionSet شامل مجموعه ای از تعاریف گزینه به همراه یک اشاره گر به یک تابع کنترل کننده است که در صورت مواجهه با یکی از گزینه های مرتبط فراخوانی می شود. مجموعه‌های گزینه‌ها همچنین حاوی متن راهنما هستند که نحو و هدف هر گزینه را توصیف می‌کند (به OPTION HELP زیر مراجعه کنید). مجموعه‌های گزینه‌ای طراحی شده‌اند تا امکان ایجاد مجموعه‌های قابل استفاده مجدد از گزینه‌های مرتبط را فراهم کنند. این امر تلاش لازم برای حفظ چندین برنامه کاربردی را که گزینه های مشابه را می پذیرند (مانند برنامه های آزمایشی) ساده می کند.

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

لیستی از OptionSets به تابع ParseArgs () به عنوان یک آرایه با پایان NULL از اشاره گرها ارسال می شود. به عنوان مثال:

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 Name علامت گذاری می شود. به عنوان مثال:

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

OPTION IDS

شناسه‌های گزینه، گزینه‌های کدی را که آنها را مدیریت می‌کند، شناسایی می‌کنند (عملکرد OptionHandler). شناسه‌های گزینه نسبت به OptionSet که در آن ظاهر می‌شوند هستند، و بنابراین ممکن است در OptionSet‌های مختلف مجدداً مورد استفاده قرار گیرند (اما به گزینه‌های کوتاه در زیر مراجعه کنید). قرارداد معمول این است که شماره گذاری شناسه های گزینه را از 1000 شروع کنیم، با این حال می توان از هر عدد > 128 استفاده کرد. گزینه های مستعار را می توان با استفاده از همان شناسه گزینه با نام گزینه های مختلف ایجاد کرد.

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

برخلاف getopt_long(3)، ParseArgs() یک رشته مجزا برای تعیین لیست کاراکترهای گزینه کوتاه نمی گیرد. در عوض، هر گزینه ای که مقدار شناسه آن در محدوده کاراکترهای ASCII گرافیکی قرار می گیرد، به آن کاراکتر اجازه می دهد تا به عنوان یک گزینه کوتاه استفاده شود.

ParseArgs () مستلزم آن است که کاراکترهای گزینه کوتاه در تمام OptionSets منحصر به فرد باشند. به همین دلیل، استفاده از گزینه‌های کوتاه برای هر OptionSet که در بین برنامه‌ها به اشتراک گذاشته می‌شود، به دلیل احتمال زیاد برخورد، ممنوع است. کاراکترهای گزینه های کوتاه ممکن است در یک OptionSet مورد استفاده مجدد قرار گیرند تا امکان ایجاد نام های طولانی نام مستعار گزینه ها فراهم شود.

OPTION HELP

هر OptionSet شامل یک رشته OptionHelp است که هدف و نحو گزینه های مرتبط را توصیف می کند. این رشته ها توسط تابع PrintOptionHelp() برای تولید اطلاعات استفاده از گزینه استفاده می شوند.

طبق قرارداد، رشته های کمک گزینه شامل یک مثال نحوی است که با توضیح متنی گزینه دنبال می شود. اگر گزینه دارای نسخه کوتاه یا نام مستعار باشد، قبل از نام طولانی اولیه داده می شود. برای هماهنگی، خطوط نحو با 2 فاصله تورفتگی دارند، در حالی که خطوط توضیحات با 7 فاصله فرورفته می شوند. یک خط خالی تنها به دنبال توضیحات هر گزینه، از جمله آخرین مورد، قرار می گیرد.

به عنوان مثال:

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

OPTION HELP GROUPS

OptionSets شامل یک رشته HelpGroupName است که برای گروه بندی گزینه ها با هم در خروجی راهنما استفاده می شود. تابع PrintOptionHelp() از HelpGroupName به عنوان عنوان بخش در خروجی استفاده تولید شده استفاده می کند. اگر چندین OptionSet 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
)