nl::ArgParser

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

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

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

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

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

יש שתי תבניות להגדרה של OptionSetsone. הן יכולות לאתחל מופע של ה-OptionSet עצמו, למשל כמערך גלובלי סטטי או כמחלקה משנית OptionSetBase ולספק בנאי. הפונקציה השנייה משתמשת בפונקציה 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 שונים (אבל כדאי לעיין ב'אפשרויות קצרות' בהמשך). המוסכמה המקובלת היא להתחיל מספור של מזהי אפשרויות מ-1,000, אך ניתן להשתמש בכל מספר שגדול מ-128. ניתן ליצור אפשרויות כינוי על ידי שימוש באותו מזהה אפשרות עם שמות אפשרויות שונים.

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

שלא כמו getopt_long(3), ב-ParseArgs() לא נלקח מחרוזת נפרדת שמציינת את רשימת התווים הקצרים של האפשרות. לעומת זאת, כל אפשרות שערך המזהה שלה נופל בטווח של תווי ASCII גרפיים תאפשר להשתמש בתו הזה כאפשרות קצרה.

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

עזרה באפשרות

כל OptionSet מכיל מחרוזת OptionHelp שמתארת את המטרה ואת התחביר של האפשרויות המשויכות. המחרוזות האלה משמשות את הפונקציה PrintOptionHelp() כדי ליצור מידע על השימוש באפשרויות.

לפי המוסכמה, מחרוזות העזרה של אפשרויות מורכבות מדוגמה לתחביר שאחריה תיאור טקסטואלי של האפשרות. אם לאפשרות יש גרסה מקוצרת או שם חלופי, הוא יופיע לפני השם הארוך הראשי. כדי לשמור על עקביות, שורות התחביר מוכנסות עם 2 רווחים, ואילו בשורות התיאור יש 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
)