nl::ArgParser

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

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

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

ชุดตัวเลือก

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

การกำหนด OptionSetsone สามารถกำหนดค่าเริ่มต้นอินสแตนซ์ของ OptionSet ด้วยตัวเองได้ 2 รูปแบบ เช่น เป็นคลาสสากลแบบคงที่ หรือ คลาสย่อย 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 ที่ปรากฏ ดังนั้นจึงสามารถนำมาใช้ซ้ำได้ใน OptionSets ที่ต่างกัน (แต่จะเห็น "ตัวเลือก Shorts" ด้านล่าง) โดยทั่วไปจะใช้ตัวเลขรหัสตัวเลือกเป็น 1000 แต่คุณใช้ตัวเลขใดก็ได้ที่มากกว่า 128 คุณสร้างตัวเลือกชื่อแทนโดยใช้รหัสตัวเลือกเดียวกันที่มีชื่อตัวเลือกต่างกันได้

ตัวเลือก Shorts

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

ParseArgs() กำหนดให้อักขระตัวเลือกแบบสั้นต้องไม่ซ้ำกันใน OptionSets ทั้งหมด ด้วยเหตุนี้ จึงไม่แนะนำให้ใช้ตัวเลือกสั้นๆ กับ OptionSet ที่แชร์ในโปรแกรม เนื่องจากมีโอกาสเกิดข้อขัดข้องอย่างมาก สามารถนำอักขระตัวเลือกสั้นมาใช้ซ้ำภายใน 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";

กลุ่มช่วยเหลือตัวเลือก

OptionSet ประกอบด้วยสตริง 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
)