nl::ArgParser

แยกวิเคราะห์ชุดอาร์กิวเมนต์รูปแบบบรรทัดคำสั่ง เรียกใช้ฟังก์ชันการจัดการ เพื่อประมวลผลแต่ละตัวเลือกและอาร์กิวเมนต์ที่ไม่ใช่ตัวเลือก

ParseArgs() จะแสดงรายการของอาร์กิวเมนต์ (argv) และแยกวิเคราะห์ตามชุดของคำนิยามตัวเลือกที่ให้ไว้ ฟังก์ชันนี้รองรับตัวเลือกทั้งแบบยาว (opt) และแบบสั้น (-o) และใช้ไวยากรณ์ตัวเลือกเดียวกันกับฟังก์ชัน GNU getopt_long(3)

ระบบจะส่งคำนิยามตัวเลือกไปยัง ParseArgs() เป็นอาร์เรย์ของโครงสร้าง OptionSet (optSets) OptionSet แต่ละรายการจะมีอาร์เรย์ของคำจำกัดความตัวเลือกและฟังก์ชันของเครื่องจัดการ ParseArgs() จะประมวลผลอาร์กิวเมนต์ตัวเลือกตามลำดับที่ระบุ โดยเรียกใช้ฟังก์ชันของตัวแฮนเดิลที่เกี่ยวข้องสำหรับแต่ละตัวเลือกที่รู้จัก เมื่อแยกวิเคราะห์ตัวเลือกทั้งหมดแล้ว จะมีการเรียกใช้ฟังก์ชันตัวแฮนเดิลที่ไม่ใช่ตัวเลือก (nonOptArgHandler) แยกต่างหาก 1 ครั้งเพื่อประมวลผลอาร์กิวเมนต์ที่เหลือ

ชุดตัวเลือก

OptionSet ประกอบด้วยชุดคำจำกัดความของตัวเลือก พร้อมด้วยตัวชี้ไปยังฟังก์ชันของเครื่องจัดการที่จะถูกเรียกเมื่อพบหนึ่งในตัวเลือกที่เชื่อมโยงกัน นอกจากนี้ ชุดตัวเลือกยังมีข้อความช่วยเหลือที่อธิบายไวยากรณ์และวัตถุประสงค์ของแต่ละตัวเลือก (ดู OPTION HELP ด้านล่าง) ชุดตัวเลือกได้รับการออกแบบมาเพื่ออนุญาตการสร้างคอลเล็กชันตัวเลือกที่เกี่ยวข้องซึ่งสามารถนำมาใช้ซ้ำได้ ซึ่งช่วยลดความยุ่งยากในการจัดการแอปพลิเคชันหลายรายการที่ยอมรับตัวเลือกที่คล้ายกัน (เช่น แอปพลิเคชันทดสอบ)

การกำหนด OptionSetsone มีอยู่ 2 รูปแบบด้วยกันที่สามารถทำให้อินสแตนซ์ของโครงสร้าง 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 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

ParseArgs() ไม่ได้ใช้สตริงแยกต่างหากในการระบุรายการอักขระตัวเลือกแบบสั้น ซึ่งแตกต่างจาก getopt_long(3) แต่ตัวเลือกใดๆ ที่มีค่ารหัสอยู่ในช่วงอักขระ ASCII แบบกราฟิก จะทำให้สามารถใช้อักขระนั้นเป็นตัวเลือกแบบสั้นได้

ParseArgs() กำหนดให้อักขระตัวเลือกสั้นๆ ไม่ซ้ำกันใน OptionSets ทั้งหมด ด้วยเหตุนี้ จึงไม่แนะนำให้ใช้ตัวเลือกสั้นๆ สำหรับชุดตัวเลือกที่มีการใช้งานร่วมกันในโปรแกรมต่างๆ เนื่องจากมีโอกาสสูงที่จะเกิดการชนกัน อักขระตัวเลือกแบบสั้นสามารถใช้ซ้ำภายใน OptionSet เดียวเพื่อสร้างชื่อตัวเลือกแบบยาวของชื่อแทนได้

ความช่วยเหลือเกี่ยวกับตัวเลือก

OptionSet แต่ละรายการจะมีสตริง OptionHelp ที่อธิบายวัตถุประสงค์และไวยากรณ์ของตัวเลือกที่เกี่ยวข้อง ฟังก์ชัน PrintOptionHelp() จะใช้สตริงเหล่านี้เพื่อสร้างข้อมูลการใช้งานตัวเลือก

ตามกฎแล้ว สตริงความช่วยเหลือเกี่ยวกับตัวเลือกจะประกอบด้วยตัวอย่างไวยากรณ์ซึ่งตามมาด้วยคำอธิบายที่เป็นข้อความของตัวเลือก หากตัวเลือกมีชื่อย่อหรือชื่อชื่อแทน ตัวเลือกดังกล่าวจะมีให้ก่อนชื่อแบบยาวหลัก เพื่อความสอดคล้อง บรรทัดไวยากรณ์จะมีการเยื้องโดยเว้นวรรค 2 ช่อง ส่วนบรรทัดรายละเอียดจะเยื้อง 7 ช่อง บรรทัดว่าง 1 บรรทัดจะตามหลังคำอธิบายตัวเลือกแต่ละรายการ ซึ่งรวมถึงบรรทัดสุดท้ายด้วย

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
)