nl::ArgParser

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

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

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

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

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

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

خيارات قصيرة

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

تتطلب ParseArgs() أن تكون أحرف الخيارات القصيرة فريدة في جميع OptionSets. ولهذا السبب، لا يُنصح باستخدام خيارات قصيرة لأي مجموعة OptionSets تتم مشاركتها عبر البرامج نظرًا لاحتمالية حدوث تصادمات. ويمكن إعادة استخدام أحرف الخيارات القصيرة داخل عنصر 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";

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

تحتوي OptionSets على سلسلة 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
)