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

BỘ LỰA CHỌN

OptionSet chứa một tập hợp các định nghĩa tuỳ chọn cùng với con trỏ tới một hàm của trình xử lý. Hàm này sẽ được gọi khi gặp một trong các tuỳ chọn liên quan. Các nhóm lựa chọn cũng chứa văn bản trợ giúp mô tả cú pháp và mục đích của mỗi lựa chọn (xem phần OPTION TRỢ GIÚP bên dưới). Tập hợp lựa chọn được thiết kế để cho phép tạo tập hợp các tuỳ chọn có liên quan có thể sử dụng lại. Việc này giúp đơn giản hoá quá trình cần thiết để duy trì nhiều ứng dụng chấp nhận những tuỳ chọn tương tự nhau (ví dụ: các ứng dụng kiểm thử).

Có hai mẫu để xác định OptionSetsone có thể khởi tạo một thực thể của chính cấu trúc OptionSet, ví dụ: dưới dạng một lớp toàn cục tĩnh hoặc lớp con OptionSetBase và cung cấp một hàm khởi tạo. Hàm 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 các OptionSets được truyề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 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 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 tuỳ chọn, một mã nhận dạng số nguyên dùng để xác định tuỳ chọn và liệu tuỳ chọn đó có mong đợi/cho phép đối số hay không. Điểm kết thúc 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 }
};

IDS

Mã tuỳ chọn 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, do đó có thể được sử dụng lại trên các OptionSet khác nhau (tuy nhiên, hãy xem TÙY CHỌN NGẮN bên dưới). Quy ước chung là bắt đầu đánh số mã lựa chọn ở mức 1000, tuy nhiên, bất kỳ số nào > 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.

TÙY CHỌN NGẮN

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ự tuỳ chọn ngắn. Đúng hơn, bất kỳ tuỳ chọn nào có giá trị id nằm trong khoảng ký tự ASCII đồ hoạ sẽ cho phép sử dụng ký tự đó dưới dạng tuỳ chọn ngắn gọn.

ParseArgs() yêu cầu các ký tự lựa chọn ngắn là duy nhất trên tất cả OptionSets. Do đó, bạn không nên sử dụng tuỳ chọn ngắn cho bất kỳ OptionSet nào được chia sẻ giữa các chương trình do khả năng xảy ra xung đột đáng kể. Bạn có thể sử dụng lại các ký tự tùy chọn ngắn trong một OptionSet để cho phép tạo tên tùy chọn bí danh 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 quan. Hàm PrintOptionHelp() sử dụng các chuỗi này để 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 sẽ bao gồm một 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 đó 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 đầu dòng 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 duy nhất sau mỗi nội dung mô tả về lựa chọn, bao gồm cả dòng 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";

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

OptionSet 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() sử dụng HelpGroupName làm tiêu đề mục trong dữ liệu đầu ra về mức sử dụng đã tạo. Nếu nhiều OptionSets có cùng HelpGroupName, PrintOptionHelp() sẽ in trợ giúp tuỳ chọn cho các OptionSets 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
)