nl::ArgParser

يمكنك تحليل مجموعة من وسيطات نمط سطر الأوامر، مع وظائف استدعاء الطلبات لمعالجة كل خيار ووسيطة غير خيار.

تأخذ ParseArgs() قائمة بالوسيطات (argv) وتحللها وفقًا لمجموعة من تعريفات الخيارات المقدمة. تدعم الدالة كلاً من الخيارات الطويلة (المحسّنة) والقصيرة (o) وتنفّذ بنية الخيار نفسها التي تستخدم دالة GNU getopt_long(3).

يتم تمرير تعريفات الخيارات إلى ParseArgs() كمصفوفة لبنية OptionSet (optSets). يحتوي كل OptionSet على مصفوفة من تعريفات الخيارات ودالة المعالج. تعالج ParseArgs() وسيطات الخيارات بالترتيب المحدّد، واستدعاء وظيفة المعالج ذات الصلة لكل خيار تم التعرّف عليه. بعد تحليل جميع الخيارات، يتم استدعاء وظيفة معالج غير مستقلة (nonOptArgHandler) مرة واحدة لمعالجة أي وسيطات متبقية.

مجموعات الخيارات

تحتوي OptionSet على مجموعة من تعريفات الخيارات مع مؤشر لدالة المعالج سيتم طلبها عند ظهور أحد الخيارات المرتبطة. وتحتوي مجموعات الخيارات أيضًا على نص مساعدة يصف بنية كل خيار وغرضه (راجع المساعدة "الخيار" أدناه). تم تصميم مجموعات الخيارات للسماح بإنشاء مجموعات قابلة لإعادة الاستخدام من الخيارات ذات الصلة. ويعمل ذلك على تبسيط الجهد اللازم للاحتفاظ بعدة تطبيقات تقبل الخيارات المشابهة (مثل التطبيقات التجريبية).

هناك نمطان لتحديد OptionSetsone يمكنهما إعداد مثيل للبنية OptionSet نفسها، على سبيل المثال، كعالم ثابت، أو فئة فرعية من OptionSetBase وتقديم أداة إنشاء. يستخدم العنصر الأخير وظيفة HandleOption() افتراضية لتفويض معالجة الخيار للفئة الفرعية.

يتم تمرير قوائم OptionSets إلى دالة ParseArgs() كمصفوفة مؤشرات تم إنهاؤها فارغًا. مثال:

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 في الاسم. مثال:

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 التي تظهر فيها، وبالتالي يمكن إعادة استخدامها من خلال مختلف خيارات الخيارات (على الرغم من أن هذا هو الخيار "يُرجى الاطّلاع على الخيارات القصيرة" أدناه). من الشائع أن يبدأ معرّف خيار الرقم بـ 1000، ولكن يمكن استخدام أي رقم &gt؛ أي 128. يمكن إنشاء خيارات الاسم المستعار باستخدام رقم تعريف الخيار نفسه مع أسماء خيارات مختلفة.

خيارات فيديوهات Shorts

وعلى عكس getopt_long(3)، لا يأخذ ParseArgs() سلسلة منفصلة تحدد قائمة أحرف الخيارات القصيرة. وبدلاً من ذلك، سيتيح أي خيار تقع قيمة رقم التعريف الخاص به في نطاق أحرف ASCII الرسومية أن يتم استخدام هذا الحرف كخيار قصير.

تتطلب ParseArgs() أن تكون أحرف الخيارات القصيرة فريدة في جميع مجموعات الخيارات. ونتيجة لذلك، لا يُنصح باستخدام الخيارات القصيرة لأي من مجموعات الخيارات التي تتم مشاركتها عبر البرامج بسبب الفرصة الكبيرة للتصادمات. يمكن إعادة استخدام أحرف الخيارات القصيرة ضمن OptionSet واحدة للسماح بإنشاء أسماء خيارات طويلة طويلة.

مساعدة على الخيار

تحتوي كل OptionSet على سلسلة OptionHelp تصف غرض وبنية الخيارات المرتبطة. تستخدم دالة PrintOptionHelp() هذه السلاسل لإنشاء معلومات استخدام الخيار.

تعني الاتفاقية أن سلاسل مساعدة الخيارات تتألف من مثال على البنية يتبعه وصف نصي للخيار. إذا كان الخيار يحتوي على نسخة مختصرة أو اسم مستعار، يتم تقديمه قبل الاسم الطويل الأساسي. للحفاظ على الاتساق، تمت إضافة مسافة بادئة لسطرَي البنية مع ترك 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";

خيار مجموعات المساعدة

تحتوي OptionSets على سلسلة HelpGroupName يتم استخدامها لتجميع الخيارات معًا في مخرجات المساعدة. تستخدم الدالة PrintOptionHelp() HelpHelpName كعنوان قسم في مخرجات الاستخدام التي تم إنشاؤها. وإذا كانت OptionSets متعددة لها نفس HelpGroupName، سيطبع PrintOptionHelp() مساعدة الخيار لمختلف خيارات الخيارات معًا ضمن عنوان قسم شائع.

التحليل

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
)