nl::ArgParser

ניתוח קבוצה של ארגומנטים בסגנון שורת פקודה, קריאה לפונקציות טיפול כדי לעבד כל אפשרות וארגומנט שהוא לא אפשרות.

הפונקציה ParseArgs() מקבלת רשימה של ארגומנטים (argv) ומנתחת אותם בהתאם לקבוצה של הגדרות האפשרויות שסופקו. הפונקציה תומכת גם באפשרויות ארוכות (אופציונליות) וגם באפשרויות קצרות (-o), ומממשת את אותו תחביר של אפשרויות כמו הפונקציה getopt_long(3) של GNU.

הגדרות האפשרויות מועברות אל ParseArgs() כמערך מבני OptionSet (optSets). כל OptionSet מכיל מערך של הגדרות אפשרויות ופונקציית handler. ParseArgs() מעבד ארגומנטים של אפשרויות בסדר הנתון, מבצע קריאה לפונקציית ה-handler המתאימה לכל אפשרות שזוהתה. אחרי ניתוח כל האפשרויות, נשלחת פעם אחת פונקציה נפרדת שאינה של אפשרויות handler (nonOptArgHandler) כדי לעבד את הארגומנטים שנותרו.

קבוצות של אפשרויות

OptionSet מכיל קבוצה של הגדרות אפשרויות יחד עם מצביע אל פונקציית handler שתיקרא כאשר תופיע אחת מהאפשרויות המשויכות. קבוצות אפשרויות מכילות גם טקסט עזרה שמתאר את התחביר והמטרה של כל אפשרות (ראו 'עזרה באפשרות' בהמשך). קבוצות אפשרויות נועדו לאפשר יצירה של אוספים לשימוש חוזר של אפשרויות קשורות. התכונה הזו מפשטת את המאמץ שנדרש כדי לתחזק אפליקציות מרובות שמקבלות אפשרויות דומות (למשל, בקשות לבדיקה).

יש שתי תבניות להגדרת OptionSetsone כדי לאתחל מופע של המבנה OptionSet עצמו, למשל. בתור OptionSetBase סטטי, או מחלקה משנית, ומספק constructor. התהליך הזה משתמש בפונקציה HandleOption() וירטואלית בלבד כדי להאציל טיפול באפשרויות למחלקה המשנית.

רשימות של OptionSets מועברות לפונקציה ParseArgs() כמערך מצביעים שמסתיים ב-NULL. 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, כאשר כל רכיב מכיל: את שם האפשרות, מזהה של מספר שלם המשמש לזיהוי האפשרות, והאם האפשרות מצפה או מאפשרת ארגומנט. הסוף של מערך האפשרויות מסומן על ידי שדה NULL Name. 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 שבו הם מופיעים, ולכן ניתן לעשות בו שימוש חוזר בקבוצות Option שונות (עם זאת, ראו בהמשך 'אפשרויות Shorts'). המוסכמה הנפוצה היא להתחיל מספור המזהים ב-1000, אך בכל מספר > 128. ניתן ליצור אפשרויות כינויים על ידי שימוש באותו מזהה אפשרות עם שמות אפשרויות שונים.

אפשרויות סרטון Shorts

בניגוד ל-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";

קבוצות עזרה בנושא אפשרויות

קבוצות האפשרויות מכילות מחרוזת 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
)