nl::ArgParser

الملخّص

تعداد

OptionArgumentType تعداد
تحدد متطلبات الوسيطة لخيار سطر الأوامر.

رفوف النوع

NonOptionArgHandlerFunct)(const char *progName, int argc, char *argv[]) typedef
bool(*
دالة يمكن استدعاءها للتعامل مع أي وسيطات سطر أوامر متبقية وغير اختيارية.
OptionHandlerFunct)(const char *progName, OptionSet *optSet, int id, const char *name, const char *arg) typedef
bool(*
دالة يمكن استدعاءها للتعامل مع مجموعة من خيارات سطر الأوامر.

المتغيّرات

PrintArgError = DefaultPrintArgError)(const char *msg,...)
void(*
الإشارة إلى الدالة المستخدمة لطباعة الأخطاء التي تحدث أثناء تحليل الوسيطة.
gActiveOptionSets = NULL
تم تمرير قائمة OptionSets إلى استدعاء ParseArgs() النشط حاليًا.

الدوال

CountAllOptions(OptionSet *optSets[])
size_t
CountAllOptions(OptionSet **optSets)
size_t
CountOptionSets(OptionSet *optSets[])
size_t
CountOptionSets(OptionSet **optSets)
size_t
DefaultPrintArgError(const char *msg, ...)
void
طباعة رسالة خطأ مرتبطة بتحليل الوسيطة.
FindOptionById(OptionSet **optSets, int optId, OptionSet *& optSet, OptionDef *& optDef)
void
FindOptionByIndex(OptionSet **optSets, int optIndex, OptionSet *& optSet, OptionDef *& optDef)
void
GetNextArg(char *& parsePoint)
bool
IsShortOptionChar(int ch)
bool
MakeLongOptions(OptionSet **optSets)
struct option *
MakeShortOptions(OptionSet **optSets)
char *
MakeUniqueHelpGroupNamesList(OptionSet *optSets[])
const char **
ParseArgs(const char *progName, int argc, char *argv[], OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler, bool ignoreUnknown)
bool
يمكنك تحليل مجموعة من وسيطات نمط سطر الأوامر، مع وظائف استدعاء الطلبات لمعالجة كل خيار ووسيطة غير خيار.
ParseArgs(const char *progName, int argc, char *argv[], OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler)
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)
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
تحليل معرّف قماش Weave في شكل نصي.
ParseHexString(const char *hexStr, uint32_t strLen, uint8_t *outBuf, uint32_t outBufSize, uint32_t & outDataLen)
bool
تحليل سلسلة وحدات البايت التي يتم تقديمها على شكل سداسي عشري
ParseIPAddress(const char *str, IPAddress & output)
bool
تحليل عنوان IP في نموذج نصي.
ParseInt(const char *str, uint64_t & output, int base)
bool
حلِّل محاولة تحويل سلسلة إلى عدد صحيح غير مُوقَّع 64 بت، وذلك من خلال تطبيق التفسير المناسب استنادًا إلى المَعلمة الأساسية.
ParseInt(const char *str, uint32_t & output, int base)
bool
التحليل ومحاولة تحويل سلسلة إلى عدد صحيح غير مُوقَّع 32 بت، مع تطبيق التفسير المناسب استنادًا إلى المعلّمة الأساسية
ParseInt(const char *str, int32_t & output, int base)
bool
التحليل ومحاولة تحويل سلسلة إلى عدد صحيح موقَّع 32 بت، مع تطبيق التفسير المناسب استنادًا إلى المعلّمة الأساسية
ParseInt(const char *str, uint64_t & output)
bool
حلِّل محاولة تحويل سلسلة كقيمة عشرية إلى عدد صحيح غير مُوقَّع 64 بت، وذلك من خلال تطبيق التفسير المناسب استنادًا إلى المعلَمة الأساسية.
ParseInt(const char *str, uint32_t & output)
bool
حلِّل محاولة تحويل سلسلة كقيمة نصية إلى عدد صحيح غير مُوقَّع 32 بت، وذلك من خلال تطبيق التفسير المناسب استنادًا إلى المعلَمة الأساسية.
ParseInt(const char *str, int32_t & output)
bool
يمكنك التحليل ومحاولة تحويل سلسلة نصية باعتبارها قيمة عشرية إلى عدد صحيح موقَّع 32 بت، وذلك بتطبيق التفسير المناسب استنادًا إلى المعلّمة الأساسية.
ParseInt(const char *str, uint16_t & output)
bool
التحليل ومحاولة تحويل سلسلة تفسيرية كقيمة عشرية إلى عدد صحيح غير موقَّع 16 بت، تطبيق التفسير المناسب استنادًا إلى المعلّمة الأساسية.
ParseInt(const char *str, int16_t & output)
bool
يمكنك تحليل سلسلة وتحويلها باعتبارها قيمة عشرية إلى عدد صحيح موقَّع 16 بت، وذلك بتطبيق التفسير المناسب استنادًا إلى المعلمة الأساسية.
ParseInt(const char *str, uint8_t & output)
bool
التحليل ومحاولة تحويل سلسلة تفسيرية كقيمة عشرية إلى عدد صحيح غير مُوقَّع 8 بت، مع تطبيق التفسير المناسب استنادًا إلى المَعلمة الأساسية
ParseNodeId(const char *str, uint64_t & nodeId)
bool
تحليل رقم تعريف عقدة Weave في نموذج نصي.
ParseSubnetId(const char *str, uint16_t & subnetId)
bool
حلِّل سلسلة وحاول تحويلها إلى رقم تعريف شبكة فرعية غير موقَّعة 16 بت، مع تفسير السلسلة على أنها سداسية عشرية.
PrintOptionHelp(OptionSet *optSets[], FILE *s)
void
يمكنك طباعة نص المساعدة لقائمة محددة من الخيارات لبث مباشر.
PutStringWithBlankLine(FILE *s, const char *str)
void
PutStringWithNewLine(FILE *s, const char *str)
void
SplitArgs(char *argStr, char **& argList, char *initialArg)
int32_t

صفوف

nl::ArgParser::HelpOptions

OptionSet الشائعة للتعامل مع خيارات المعلومات (مساعدة، الإصدار).

nl::ArgParser::OptionSetBase

OptionSet حيث يكون المعالج دالة افتراضية.

الهياكل

nl::ArgParser::OptionDef

تحديد خيار سطر أوامر.

nl::ArgParser::OptionSet

لتعريف مجموعة من خيارات سطر الأوامر ذات الصلة بالمنطق وإعادة الاستخدام.

تعداد

نوع وسيطة الخيار

 OptionArgumentType

تحدد متطلبات الوسيطة لخيار سطر الأوامر.

رفوف النوع

NonOptionArgHandlerFunct

bool(* NonOptionArgHandlerFunct)(const char *progName, int argc, char *argv[])

دالة يمكن استدعاءها للتعامل مع أي وسيطات سطر أوامر متبقية وغير اختيارية.

OptionHandlerFunct

bool(* OptionHandlerFunct)(const char *progName, OptionSet *optSet, int id, const char *name, const char *arg)

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

المتغيّرات

خطأ في الطباعة

void(* PrintArgError)(const char *msg,...) = DefaultPrintArgError

الإشارة إلى الدالة المستخدمة لطباعة الأخطاء التي تحدث أثناء تحليل الوسيطة.

يجب على التطبيقات استدعاء PrintArgError() للإبلاغ عن أخطاء في الخيار الخاص بها ودوال معالجة الخيارات غير الاختيارية، بدلاً من الطباعة مباشرةً إلى stdout/stderr.

يتم ضبط الإعدادات التلقائية على مؤشر الدالة DefaultPrintArgError().

gActiveOptionSets

OptionSet ** gActiveOptionSets = NULL

تم تمرير قائمة OptionSets إلى استدعاء ParseArgs() النشط حاليًا.

ستكون هذه القيمة فارغًا عندما لا يكون هناك استدعاء لـ ParseArgs().

الدوال

عدّ الخيارات

size_t CountAllOptions(
  OptionSet *optSets[]
)

عدّ الخيارات

size_t CountAllOptions(
  OptionSet **optSets
)

عدد الخيارات

size_t CountOptionSets(
  OptionSet *optSets[]
)

عدد الخيارات

size_t CountOptionSets(
  OptionSet **optSets
)

خطأ في الطباعة التلقائية

void DefaultPrintArgError(
  const char *msg,
  ...
)

طباعة رسالة خطأ مرتبطة بتحليل الوسيطة.

الدالة التلقائية المستخدمة لطباعة رسائل الخطأ التي تنشأ بسبب تحليل الوسيطات.

التفاصيل
المعلَمات
[in] msg
الرسالة التي ستتم طباعتها.

يجب أن تستخدم التطبيقات استدعاء مؤشر دالة PrintArgError، بدلاً من استدعاء هذه الدالة مباشرةً.

FindOptionById

void FindOptionById(
  OptionSet **optSets,
  int optId,
  OptionSet *& optSet,
  OptionDef *& optDef
)

بحث حسب الخيار

void FindOptionByIndex(
  OptionSet **optSets,
  int optIndex,
  OptionSet *& optSet,
  OptionDef *& optDef
)

GetNextArg

bool GetNextArg(
  char *& parsePoint
)

IsShortOptionChar

bool IsShortOptionChar(
  int ch
)

خيارات Makelong

struct option * MakeLongOptions(
  OptionSet **optSets
)

خيارات تحقيق الربح

char * MakeShortOptions(
  OptionSet **optSets
)

MakeMakeHelpGroupNamesList

const char ** MakeUniqueHelpGroupNamesList(
  OptionSet *optSets[]
)

التحليل

bool ParseArgs(
  const char *progName,
  int argc,
  char *argv[],
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler,
  bool ignoreUnknown
)

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

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

التفاصيل
المعلَمات
[in] progName
اسم البرنامج أو السياق الذي يتم فيه تحليل الوسيطات. سيتم استخدام هذه السلسلة لبادئة رسائل الخطأ والتحذيرات.
[in] argc
عدد الوسيطات المطلوب تحليلها، بالإضافة إلى 1.
[in] argv
مصفوفة من سلاسل الوسيطة المراد تحليلها. يجب أن يكون طول المصفوفة أكبر من القيمة المحددة لـ argc، ويجب ضبط argv[argc] على NULL. يبدأ تحليل الوسيطة بعنصر المصفوفة second (argv[1])، ويتم تجاهل العنصر 0.
[in] optSets
قائمة بالمؤشرات إلى بُنى OptionSet التي تحدّد الخيارات القانونية يجب إنهاء القائمة التي تتضمن قيمة فارغة.
[in] nonOptArgHandler
مؤشر إلى دالة سيتم استدعاءها عند اكتمال تحليل الخيارات مع أي وسيطات غير اختيارية متبقية . يتم استدعاء الدالة بغض النظر عما إذا كانت هناك أي وسيطات متبقية. إذا تم تجاوز السياسة "فارغ"، ستُبلِغ ParseArgs() عن وجود خطأ في حال ظهور أي وسيطات غير اختيارية.
[in] ignoreUnknown
في حال اختيار "صحيح"، سيتم تجاهل أي خيارات لم يتم التعرّف عليها.
المرتجعات
true إذا تم تحليل جميع الخيارات والوسيطات غير الخيارات بنجاح؛ false إذا لم يتم التعرّف على خيار أو إذا أخفقت إحدى وظائف المعالج (أي عرض خطأ)

يتم تمرير تعريفات الخيارات إلى 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[],
  NonOptionArgHandlerFunct nonOptArgHandler
)

التحليل

bool ParseArgs(
  const char *progName,
  int argc,
  char *argv[],
  OptionSet *optSets[]
)

ParseArgsFromEnvVar

bool ParseArgsFromEnvVar(
  const char *progName,
  const char *varName,
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler,
  bool ignoreUnknown
)

تحليل مجموعة من الوسيطات من متغيّر بيئة مُسمّى.

يقرأ ParseArgsFromEnvVar() متغيّر بيئة مُسمّى ويمرّر القيمة ParseArgsFromString() إلى التحليل. في حال عدم ضبط متغيِّر البيئة، لن تتخذ الدالة أي إجراء.

التفاصيل
المعلَمات
[in] progName
اسم البرنامج أو السياق الذي يتم فيه تحليل الوسيطات. سيتم استخدام هذه السلسلة لبادئة رسائل الخطأ والتحذيرات.
[in] varName
اسم متغيّر البيئة.
[in] optSets
قائمة بالمؤشرات إلى بُنى OptionSet التي تحدّد الخيارات القانونية يجب إنهاء القائمة التي تتضمن قيمة فارغة.
[in] nonOptArgHandler
مؤشر إلى دالة سيتم استدعاءها عند اكتمال تحليل الخيارات مع أي وسيطات غير اختيارية متبقية . يتم استدعاء الدالة بغض النظر عما إذا كانت هناك أي وسيطات متبقية. إذا تم تجاوز السياسة "فارغ"، ستُبلِغ ParseArgs() عن وجود خطأ في حال ظهور أي وسيطات غير اختيارية.
[in] ignoreUnknown
في حال اختيار "صحيح"، سيتم تجاهل أي خيارات لم يتم التعرّف عليها.
المرتجعات
true إذا تم تحليل جميع الخيارات والوسيطات غير الاختيارية بنجاح، أو إذا لم يتم ضبط متغير البيئة المحددة، أو false إذا لم يتم التعرّف على خيار معيّن، أو إذا تعذّرت إحدى وظائف المعالج (أي تم عرضها كخطأ) أو إذا حدث خطأ داخلي.

ParseArgsFromEnvVar

bool ParseArgsFromEnvVar(
  const char *progName,
  const char *varName,
  OptionSet *optSets[]
)

ParseArgsFromEnvVar

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
)

تحليل مجموعة من الوسيطات من سلسلة معينة.

تُقسِّم ParseArgsFromString() سلسلة معيّنة (argStr) إلى مجموعة من الوسيطات وتحلل الوسيطات باستخدام الدالة ParseArgs().

التفاصيل
المعلَمات
[in] progName
اسم البرنامج أو السياق الذي يتم فيه تحليل الوسيطات. سيتم استخدام هذه السلسلة لبادئة رسائل الخطأ والتحذيرات.
[in] argStr
سلسلة تتضمّن خيارات ووسيطات ليتم تحليلها.
[in] optSets
قائمة بالمؤشرات إلى بُنى OptionSet التي تحدّد الخيارات القانونية يجب إنهاء القائمة التي تتضمن قيمة فارغة.
[in] nonOptArgHandler
مؤشر إلى دالة سيتم استدعاءها عند اكتمال تحليل الخيارات مع أي وسيطات غير اختيارية متبقية . يتم استدعاء الدالة بغض النظر عما إذا كانت هناك أي وسيطات متبقية. إذا تم تجاوز السياسة"فارغ"، ستُبلِغ ParseArgs() عن وجود خطأ في حال ظهور أي وسيطات غير اختيارية.
[in] ignoreUnknown
في حال اختيار "صحيح"، سيتم تجاهل أي خيارات لم يتم التعرّف عليها.
المرتجعات
true إذا تم تحليل جميع الخيارات والوسيطات غير المستندة إلى الخيارات بنجاح؛ false في حال عدم التعرّف على أحد الخيارات، أو في حال تعذّر تنفيذ إحدى وظائف المعالج (أي عرض الخطأ) أو حدوث خطأ داخلي.

تشبه بنية سلاسل الإدخال بنية أوامر أوامر Unix، ولكن مع نظام عروض أسعار مبسّط. وهذه القيود تحديدًا هي كالآتي:

  • يتم تحديد الوسيطات بمسافة بيضاء، ما لم يتم وضع علامة على المسافة البيضاء بين علامتَي اقتباس أو تم تخطيها.
  • تلغي الشرطة المائلة للخلف الحرف التالي، مما يؤدي إلى التعامل معها كحرف عادي. تتم إزالة الشرطة المائلة للخلف نفسها.
  • تبدأ/تضع علامات الاقتباس المفردة أو المزدوجة. داخل السلسلة الفرعية، الأحرف الخاصة الوحيدة هي شرطة مائلة للخلف، تتخطى الحرف التالي، وعلامة الاقتباس النهائية المقابلة. تتم إزالة أحرف علامة الاقتباس للبداية/النهاية.

مثال:

--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[]
)

ParseBoolean

bool ParseBoolean(
  const char *str,
  bool & output
)

تحليل سلسلة كقيمة منطقية

تقبل هذه الدالة قيم الإدخال التالية (غير حساسة لحالة الأحرف): &"true","yes","t",&&;;&","1",&&;;&&;;;&&;;&&;;ٍّ فضلاً&;;&;كما يحلو لك.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل القيمة المطلوب تحليلها.
[out] output
مرجع إلى سعة التخزين التي يتم تخزين القيمة التي تم تحليلها عند نجاح العملية.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

رقم تعريف ParseFabric

bool ParseFabricId(
  const char *str,
  uint64_t & fabricId,
  bool allowReserved
)

تحليل معرّف قماش Weave في شكل نصي.

تقبل دالة ParseFabricId() معرّف قماش 64 بت يتم تقديمه بتنسيق سداسي عشري، مع أو بدون زاوية '0x'.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C تم إنهاؤها فارغة والتي تحتوي على معرّف قماش للتحليل.
[out] output
مرجع إلى قيمة uint64_t lvalue حيث سيتم تخزين القيمة التي تم تحليلها عند النجاح.
[in] allowReserved
إذا كانت القيمة true، يجب السماح بتحليل أرقام تعريف الأقمشة في النطاق المحجوز.
المرتجعات
صحيح إذا تم تحليل القيمة بنجاح؛ خطأ إذا لم تكن كذلك.

سلسلة التحليل

bool ParseHexString(
  const char *hexStr,
  uint32_t strLen,
  uint8_t *outBuf,
  uint32_t outBufSize,
  uint32_t & outDataLen
)

تحليل سلسلة وحدات البايت التي يتم تقديمها على شكل سداسي عشري

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

التفاصيل
المعلَمات
[in] hexStr
مؤشر إلى السلسلة للتحليل.
[in] strLen
عدد الأحرف في السداسي العشري للتحليل.
[in] outBuf
مؤشر إلى مخزن مؤقت يتم فيه تخزين وحدات البايت للتحليل.
[in] outBufSize
حجم المخزن المؤقت المُشار إليه من خلال outBuf.
[out] outDataLen
مرجع إلى عدد صحيح يتلقّى إجمالي عدد وحدات البايت التي تم تحليلها. في حال لم يكن outBuf كبيرًا بما يكفي للاحتفاظ بعدد وحدات البايت المحدّد، سيتم ضبط outDataLen على UINT32_MAX.
المرتجعات
صحيح إذا تم تحليل القيمة بنجاح؛ أو خطأ إذا كانت بيانات الإدخال غير صحيحة، أو إذا كانت القيمة outBuf صغيرة جدًا.

عنوان ParseIP

bool ParseIPAddress(
  const char *str,
  IPAddress & output
)

تحليل عنوان IP في نموذج نصي.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C تم إنهاؤها فارغة والتي تحتوي على العنوان المطلوب تحليله.
[out] output
مرجع إلى عنصر IPAddress حيث يتم تخزين القيمة التي تم تحليلها بنجاح.
المرتجعات
صحيح إذا تم تحليل القيمة بنجاح؛ خطأ إذا لم تكن كذلك.

ParseInt

bool ParseInt(
  const char *str,
  uint64_t & output,
  int base
)

حلِّل محاولة تحويل سلسلة إلى عدد صحيح غير مُوقَّع 64 بت، وذلك من خلال تطبيق التفسير المناسب استنادًا إلى المَعلمة الأساسية.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل العدد الصحيح المطلوب تحليله.
[out] output
مرجع إلى تخزين عدد صحيح غير موقَّع 64 بت، حيث يتم تخزين القيمة التي تم تحليلها بنجاح.
[in] base
القاعدة التي يجب تفسير السلسلة وتحليلها وفقًا لها. إذا كان الرقم 0 أو 16، يمكن أن تكون السلسلة سداسية عشرية مسبوقة بـ "0x". وبخلاف ذلك، تتم الإشارة إلى 0 باعتباره 10 ما لم تتم مواجهة 0 بادٍ ويكون 8 ضمنيًا فيه.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

ParseInt

bool ParseInt(
  const char *str,
  uint32_t & output,
  int base
)

التحليل ومحاولة تحويل سلسلة إلى عدد صحيح غير مُوقَّع 32 بت، مع تطبيق التفسير المناسب استنادًا إلى المعلّمة الأساسية

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل العدد الصحيح المطلوب تحليله.
[out] output
مرجع لتخزين عدد صحيح غير موقَّع 32 بت، حيث يتم تخزين القيمة التي تم تحليلها بنجاح.
[in] base
القاعدة التي يجب تفسير السلسلة وتحليلها وفقًا لها. إذا كان الرقم 0 أو 16، يمكن أن تكون السلسلة سداسية عشرية مسبوقة بـ "0x". وبخلاف ذلك، تتم الإشارة إلى 0 باعتباره 10 ما لم تتم مواجهة 0 بادٍ ويكون 8 ضمنيًا فيه.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

ParseInt

bool ParseInt(
  const char *str,
  int32_t & output,
  int base
)

التحليل ومحاولة تحويل سلسلة إلى عدد صحيح موقَّع 32 بت، مع تطبيق التفسير المناسب استنادًا إلى المعلّمة الأساسية

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل العدد الصحيح المطلوب تحليله.
[out] output
مرجع لتخزين عدد صحيح موقَّع 32 بت، حيث يتم تخزين القيمة التي تم تحليلها بنجاح.
[in] base
القاعدة التي يجب تفسير السلسلة وتحليلها وفقًا لها. إذا كان الرقم 0 أو 16، يمكن أن تكون السلسلة سداسية عشرية مسبوقة بـ "0x". وبخلاف ذلك، تتم الإشارة إلى 0 باعتباره 10 ما لم تتم مواجهة 0 بادٍ ويكون 8 ضمنيًا فيه.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

ParseInt

bool ParseInt(
  const char *str,
  uint64_t & output
)

حلِّل محاولة تحويل سلسلة كقيمة عشرية إلى عدد صحيح غير مُوقَّع 64 بت، وذلك من خلال تطبيق التفسير المناسب استنادًا إلى المعلَمة الأساسية.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل العدد الصحيح المطلوب تحليله.
[out] output
مرجع إلى تخزين عدد صحيح غير موقَّع 64 بت، حيث يتم تخزين القيمة التي تم تحليلها بنجاح.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

ParseInt

bool ParseInt(
  const char *str,
  uint32_t & output
)

حلِّل محاولة تحويل سلسلة كقيمة نصية إلى عدد صحيح غير مُوقَّع 32 بت، وذلك من خلال تطبيق التفسير المناسب استنادًا إلى المعلَمة الأساسية.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل العدد الصحيح المطلوب تحليله.
[out] output
مرجع لتخزين عدد صحيح غير موقَّع 32 بت، حيث يتم تخزين القيمة التي تم تحليلها بنجاح.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

ParseInt

bool ParseInt(
  const char *str,
  int32_t & output
)

يمكنك التحليل ومحاولة تحويل سلسلة نصية باعتبارها قيمة عشرية إلى عدد صحيح موقَّع 32 بت، وذلك بتطبيق التفسير المناسب استنادًا إلى المعلّمة الأساسية.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل العدد الصحيح المطلوب تحليله.
[out] output
مرجع لتخزين عدد صحيح موقَّع 32 بت، حيث يتم تخزين القيمة التي تم تحليلها بنجاح.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

ParseInt

bool ParseInt(
  const char *str,
  uint16_t & output
)

التحليل ومحاولة تحويل سلسلة تفسيرية كقيمة عشرية إلى عدد صحيح غير موقَّع 16 بت، تطبيق التفسير المناسب استنادًا إلى المعلّمة الأساسية.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل العدد الصحيح المطلوب تحليله.
[out] output
مرجع إلى تخزين عدد صحيح غير موقَّع 16 بت، حيث يتم تخزين القيمة التي تم تحليلها بنجاح.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

ParseInt

bool ParseInt(
  const char *str,
  int16_t & output
)

يمكنك تحليل سلسلة وتحويلها باعتبارها قيمة عشرية إلى عدد صحيح موقَّع 16 بت، وذلك بتطبيق التفسير المناسب استنادًا إلى المعلمة الأساسية.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل العدد الصحيح المطلوب تحليله.
[out] output
مرجع لتخزين عدد صحيح موقَّع 16 بت، حيث يتم تخزين القيمة التي تم تحليلها بنجاح.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

ParseInt

bool ParseInt(
  const char *str,
  uint8_t & output
)

التحليل ومحاولة تحويل سلسلة تفسيرية كقيمة عشرية إلى عدد صحيح غير مُوقَّع 8 بت، مع تطبيق التفسير المناسب استنادًا إلى المَعلمة الأساسية

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا والتي تمثل العدد الصحيح المطلوب تحليله.
[out] output
مرجع إلى تخزين عدد صحيح غير مُوقَّع 8 بت سيتم تخزين القيمة المُحلَّلة عليه بنجاح.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

رقم تعريف ParseNode

bool ParseNodeId(
  const char *str,
  uint64_t & nodeId
)

تحليل رقم تعريف عقدة Weave في نموذج نصي.

تقبل دالة ParseNodeId() معرّف عُقدة 64 بت متوفّرًا بتنسيق سداسي عشري (مع أو بدون '0x') أو الكلمات 'any' أو 'all' حيث يتم تفسيرها على أنها معرّف أي عُقدة (0xFFFFFFFFFFFFFF).

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C التي تم إنهاؤها فارغًا وتحتوي على معرّف العقدة للتحليل.
[out] output
مرجع إلى قيمة uint64_t lvalue حيث سيتم تخزين القيمة التي تم تحليلها عند النجاح.
المرتجعات
صحيح إذا تم تحليل القيمة بنجاح؛ خطأ إذا لم تكن كذلك.

رقم تعريف ParseSubnet

bool ParseSubnetId(
  const char *str,
  uint16_t & subnetId
)

حلِّل سلسلة وحاول تحويلها إلى رقم تعريف شبكة فرعية غير موقَّعة 16 بت، مع تفسير السلسلة على أنها سداسية عشرية.

التفاصيل
المعلَمات
[in] str
مؤشر إلى سلسلة C تم إنهاؤها فارغًا يمثل رقم تعريف الشبكة الفرعية، منسق كرقم سداسي عشري، للتحليل.
[in,out] subnetId
مرجع لتخزين عدد صحيح غير موقَّع بتنسيق 16 بت، حيث يتم تخزين قيمة رقم تعريف الشبكة الفرعية التي تم تحليلها بنجاح.
المرتجعات
صحيح عند النجاح، أو خطأ عند الإخفاق.

مساعدة في خيار الطباعة

void PrintOptionHelp(
  OptionSet *optSets[],
  FILE *s
)

يمكنك طباعة نص المساعدة لقائمة محددة من الخيارات لبث مباشر.

التفاصيل
المعلَمات
[in] optSets
قائمة مؤشرات إلى بُنى OptionSet التي تحتوي على نص المساعدة المطلوب طباعته.
[in] s
دفق FILE الذي يجب طباعة نص المساعدة إليه.

وضع سلسلة مع خط فارغ

void PutStringWithBlankLine(
  FILE *s,
  const char *str
)

وضع سلسلة مع خط جديد

void PutStringWithNewLine(
  FILE *s,
  const char *str
)

سبليت آركس

int32_t SplitArgs(
  char *argStr,
  char **& argList,
  char *initialArg
)