nl::ArgParser

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

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

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

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

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

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

يتم تمرير قوائم OptionSets إلى الدالة 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 المختلفة (ولكن اطّلِع على SHORT OPTIONS أدناه). الاصطلاح الشائع هو بدء أرقام تعريف خيارات الترقيم على 1000، ومع ذلك يمكن استخدام أي رقم أكبر من 128. يمكن إنشاء خيارات الاسم المستعار باستخدام نفس معرّف الخيار مع أسماء خيارات مختلفة.

خيارات الفيديوهات القصيرة

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

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

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

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

حسب الاصطلاح، تتكون سلاسل مساعدة الخيارات من مثال بناء جملة يتبعه وصف نصي للخيار. إذا كان الخيار يتضمن نسخة قصيرة أو اسمًا مستعارًا، يتم منحه قبل الاسم الطويل الأساسي. من أجل الاتساق، يتم وضع مسافة بادئة لسطور بناء الجملة بمسافتين، بينما مسافة بادئة سطور الوصف بـ 7 مسافات. ويتبع سطر فارغ واحد كل وصف للخيار، بما في ذلك الوصف الأخير.

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() ستطبع مساعدة الخيار لمجموعات 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
)