nl::ArgParser

Phân tích cú pháp một tập hợp các đối số kiểu dòng lệnh, gọi hàm xử lý để xử lý từng tuỳ chọn và đối số không phải tuỳ 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 tuỳ chọn đã cung cấp. Hàm này hỗ trợ cả tuỳ chọn dài (opt) và ngắn (-o), đồng thời triển khai cú pháp tuỳ chọn tương tự như hàm GNU getopt_long(3).

Các định nghĩa tuỳ 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 các định nghĩa tuỳ chọn và một hàm xử lý. ParseArgs() xử lý các đối số tuỳ chọn theo thứ tự nhất định, gọi hàm xử lý tương ứng cho mỗi tuỳ chọn được nhận dạng. Sau khi tất cả các tuỳ chọn đã được phân tích cú pháp, một hàm trình xử lý không phải tuỳ chọn (nonOptArgHandler) riêng biệt sẽ được gọi một lần để xử lý mọi đối số còn lại.

BỘ LỰA CHỌN

Một OptionSet chứa một tập hợp các định nghĩa tuỳ 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 tuỳ chọn liên quan. Bộ 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 NỘI DUNG TRỢ GIÚP LỰA CHỌN bên dưới). Các nhóm tuỳ chọn được thiết kế để cho phép tạo các tập hợp tuỳ chọn có thể sử dụng lại cho các tuỳ chọn có liên quan. Điều này giúp đơn giản hoá công sức duy trì nhiều ứng dụng chấp nhận các tuỳ chọn tương tự (ví dụ: ứng dụng kiểm thử).

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

Danh sách OptionSets được chuyển đến hàm ParseArgs() dưới dạng một mảng con trỏ kết thúc 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))
    {
        ...
    }
}

ĐỊNH NGHĨA VỀ LỰA CHỌN

Các tuỳ chọn được xác định bằng cấu trúc OptionDef. Các định nghĩa của tuỳ 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 tuỳ chọn, một mã nhận dạng bằng số nguyên dùng để xác định tuỳ chọn và liệu tuỳ chọn có yêu cầu/cho phép đối số hay không. Điểm cuối của mảng tuỳ chọn được báo hiệu bằng trường Tên 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 }
};

ID LỰA CHỌN

Mã tuỳ chọn giúp xác định các tuỳ chọn cho mã xử lý các tuỳ chọn đó (hàm OptionHandler). Mã lựa 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 OptionSet khác nhau (tuy nhiên, bạn có thể xem các Lựa chọn NGẮN bên dưới). Quy ước phổ biến là bắt đầu đánh số mã tuỳ chọn ở mức 1000, tuy nhiên, bạn có thể sử dụng bất kỳ số nào lớn hơn 128. Bạn có thể tạo các tuỳ chọn bí danh bằng cách sử dụng cùng một mã tuỳ chọn với các tên tuỳ chọn khác nhau.

CÁC LỰA CHỌN VIDEO NGẮN

Không giống như getopt_long(3), ParseArgs() không lấy một chuỗi riêng biệt chỉ định danh sách các ký tự tuỳ chọn ngắn. Đúng hơn, bất kỳ tuỳ chọn nào có giá trị mã nằm trong phạm vi ký tự ASCII đồ hoạ đều sẽ cho phép sử dụng ký tự đó dưới dạng tuỳ chọn ngắn.

ParseArgs() yêu cầu các ký tự tuỳ chọn ngắn phải là duy nhất trên tất cả OptionSet. Do đó, bạn không nên sử dụng các tuỳ chọn ngắn cho mọi OptionSet được dùng chung trên các chương trình do có nhiều khả năng xảy ra xung đột. Bạn có thể sử dụng lại các ký tự tuỳ chọn ngắn trong một OptionSet duy nhất để cho phép tạo tên đại diện cho tuỳ chọn dài.

TRỢ GIÚP VỀ 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 tuỳ chọn liên kết. Các chuỗi này được hàm PrintOptionHelp() dùng để tạo thông tin về việc sử dụng tuỳ chọn.

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

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

NHÓM TRỢ GIÚP LỰA CHỌN

OptionSets chứa một chuỗi HelpGroupName dùng để nhóm các tuỳ chọn lại với nhau trong kết quả trợ giúp. Hàm PrintOptionHelp() dùng HelpGroupName làm tiêu đề phần trong kết quả sử dụng được tạo. Nếu nhiều OptionSet có cùng HelpGroupName, thì PrintOptionHelp() sẽ in thông tin trợ giúp tuỳ chọn cho các OptionSet khác nhau cùng nhau dưới một tiêu đề phần chung.

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
)