nl::อาร์การ์ด

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

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

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

ชุดตัวเลือก

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

การกําหนดรูปแบบ SetSetsone จะมี 2 รูปแบบที่จะเริ่มใช้อินสแตนซ์ของโครงสร้าง OptionSet เอง เช่น เป็นค่าคงที่แบบคงที่ หรือคลาสย่อย OptionSetBase และระบุเครื่องมือสร้าง การทํางานหลังจะใช้ฟังก์ชัน HandleOption() เสมือนอย่างเดียวเพื่อมอบสิทธิ์การจัดการตัวเลือกไปยังคลาสย่อย

ระบบจะส่งรายการของ OptionSet ไปยังฟังก์ชัน ParseArgs() เป็นอาร์เรย์ของ NULL ที่สิ้นสุด เช่น

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

ตัวเลือกวิดีโอสั้น

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

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

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

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

ตามปกติแล้ว สตริงความช่วยเหลือเกี่ยวกับตัวเลือกจะประกอบด้วยตัวอย่างไวยากรณ์ตามด้วยคําอธิบายข้อความของตัวเลือก หากตัวเลือกมีเวอร์ชันแบบสั้นหรือชื่อแทน ระบบจะระบุไว้ก่อนชื่อยาวๆ หลัก เพื่อความสอดคล้องกัน ที่มีการเยื้องไวยากรณ์ไวยากรณ์ด้วยช่องว่าง 2 บรรทัด ขณะที่บรรทัดรายละเอียดมีการเยื้องด้วย 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";

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

OptionSet คือสตริง HelpGroupName ที่ใช้เพื่อจัดกลุ่มตัวเลือกเข้าด้วยกันในเอาต์พุตความช่วยเหลือ ฟังก์ชัน PrintOptionHelp() จะใช้ HelpGroupName เป็นชื่อส่วนในเอาต์พุตการใช้งานที่สร้างขึ้น หาก OptionSet หลายรายการมี HelpGroupName เดียวกัน PrintPrintHelp() จะพิมพ์ความช่วยเหลือสําหรับตัวเลือกของ OptionSet ต่างๆ ร่วมกันภายใต้ชื่อส่วนทั่วไป

พาร์ซอาร์ก

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
)