nl::ArgParser (Quảng cáo của Google)

Phân tích cú pháp một tập hợp đối số kiểu dòng lệnh, gọi các hàm xử lý để xử lý từng tùy chọn và đối số không tùy chọn.

ParseArgs() lấy danh sách các đối số (argv) và phân tích cú pháp các đối số đó theo một tập hợp các định nghĩa tùy chọn được cung cấp. Hàm hỗ trợ cả tùy chọn dài (tối ưu hóa) và ngắn (-o) và triển khai cú pháp tùy chọn giống như hàm GNU getopt_long(3).

Các định nghĩa tùy chọn được chuyển đến ParseArgs() dưới dạng một mảng các cấu trúc OptionSet (optSets). Mỗi OptionSet chứa một mảng định nghĩa tùy chọn và một hàm xử lý. ParseArgs() xử lý các đối số tùy chọn theo thứ tự đã cho, gọi hàm trình xử lý tương ứng cho mỗi tùy chọn được nhận dạng. Sau khi tất cả các tùy chọn được phân tích cú pháp, hàm xử lý không tùy chọn riêng (nonOptArgHandler) được gọi một lần để xử lý các đối số còn lại.

BỘ GÓI LỰA CHỌN

OptionSet chứa một tập hợp các định nghĩa tùy chọn cùng với một con trỏ đến hàm xử lý sẽ được gọi khi gặp một trong các tùy chọn liên quan. Các tập hợp tuỳ chọn cũng chứa văn bản trợ giúp mô tả cú pháp và mục đích của từng tuỳ chọn (xem GÓI TÙY CHỈNH bên dưới). Tập hợp tùy chọn được thiết kế để cho phép tạo các bộ sưu tập có thể sử dụng lại của các tùy chọn có liên quan. Điều này giúp đơn giản hóa nỗ lực cần thiết để duy trì nhiều ứng dụng chấp nhận các tùy chọn tương tự nhau (ví dụ: các ứng dụng thử nghiệm).

Có 2 mẫu để xác định OptionSetsone có thể khởi tạo một thực thể của cấu trúc OptionSet, ví dụ: dưới dạng toàn cầu tĩnh hoặc OptionSetBase và cung cấp một hàm dựng. Lớp thứ hai sử dụng một hàm HandleOption() ảo thuần túy để ủy quyền xử lý tùy chọn cho lớp con.

Danh sách các OptionSet được chuyển đến hàm ParseArgs() dưới dạng một mảng con trỏ kết thúc bằng NULL. Ví dụ:

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))
    {
        ...
    }
}

CÁC KHIẾM KHUYẾT TÙY CHỌN

Các tùy chọn được xác định bằng cấu trúc OptionDef. Các định nghĩa về tùy chọn được sắp xếp dưới dạng một mảng các phần tử OptionDef, trong đó mỗi phần tử chứa: tên của tùy chọn, mã nhận dạng số nguyên được dùng để xác định tùy chọn và liệu tùy chọn có chấp nhận/cho phép đối số hay không. Phần cuối của mảng tùy chọn sẽ được báo hiệu bằng trường Tên NULL. Ví dụ:

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 }
};

Mã TÙY CHỌN

Id tùy chọn xác định các tùy chọn đối với mã xử lý các mã đó (hàm OptionHandler). Mã tùy chọn có liên quan đến OptionSet mà chúng xuất hiện và do đó có thể được sử dụng lại trên các Nhóm tùy chọn khác nhau (tuy nhiên, bạn có thể xem các TÙY CHỌN NGẮN HẠN ở bên dưới). Quy ước chung là bắt đầu mã tuỳ chọn đánh số ở số 1000. Tuy nhiên, bạn có thể dùng số 128 và số 128. Bạn có thể tạo tùy chọn bí danh bằng cách sử dụng cùng một mã tùy chọn có các tên tùy chọn khác nhau.

CÁC LỰA CHỌN NGỪNG

Không giống như getopt_long(3), ParseArgs() không lấy một chuỗi riêng chỉ định danh sách các ký tự tùy chọn ngắn. Thay vào đó, bất kỳ tùy chọn nào có giá trị id nằm trong dải ký tự ASCII đồ họa sẽ cho phép sử dụng ký tự đó làm tùy chọn ngắn.

ParseArgs() yêu cầu các ký tự tùy chọn ngắn phải là duy nhất trên all OptionSets. Do đó, bạn không nên sử dụng các tùy chọn ngắn cho bất kỳ Cài đặt tùy chọn nào được chia sẻ trên các chương trình do có nhiều khả năng xảy ra va chạm. Bạn có thể sử dụng lại các ký tự tùy chọn ngắn trong một OptionSet duy nhất để cho phép tạo tên tùy chọn dài của bí danh.

GIÚP LỰA CHỌN

Mỗi OptionSet chứa một chuỗi OptionHelp mô tả mục đích và cú pháp của các tùy chọn được liên kết. Những chuỗi này được hàm PrintOptionHelp() sử dụng để tạo thông tin sử dụng tùy chọn.

Theo quy ước, chuỗi trợ giúp tùy chọn bao gồm một ví dụ về cú pháp sau phần mô tả bằng văn bản về tùy chọn. Nếu tùy chọn có phiên bản ngắn hoặc tên bí danh, thì tùy chọn này sẽ được đặt trước tên dài chính. Để đảm bảo tính nhất quán, các dòng cú pháp được thụt lề 2 dấu cách, còn các dòng mô tả được thụt lề 7 dấu cách. Một dòng trống sẽ tuân theo từng nội dung mô tả tùy chọn, bao gồm cả dòng cuối cùng.

Ví dụ:

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";

NHÓM HỖ TRỢ TÙY CHỌN

OptionSets chứa một chuỗi HelpGroupName dùng để nhóm các tùy chọn với nhau trong dữ liệu đầu ra trợ giúp. Hàm PrintOptionHelp() sử dụng HelpGroupName làm tiêu đề mục trong dữ liệu sử dụng đã tạo. Nếu nhiều OptionSets có cùng một GroupGroupName, PrintOptionHelp() sẽ in trợ giúp tùy chọn cho các OptionSets khác nhau cùng nhau trong một tiêu đề phần chung.

Phô mai 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
)