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 tùy chọn và đối số không phải tùy chọn.

ParseArgs () nhận một danh sách các đối số ( argv ) và phân tích cú pháp chúng 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 (opt) và ngắn (-o) và thực hiện cùng một cú pháp tùy chọn như hàm getopt_long (3) của GNU.

Định nghĩa tùy chọn được truyền cho ParseArgs () như là một mảng của OptionSet cấu trúc ( optSets ). Mỗi OptionSet chứa một loạt các đị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 xử lý tương ứng cho mỗi tùy chọn được công nhận. Khi tất cả các tùy chọn đã được phân tích cú pháp, một hàm xử lý không tùy chọn riêng biệt ( nonOptArgHandler ) được gọi một lần để xử lý bất kỳ đối số còn lại nào.

BỘ LỰA CHỌN

Một 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 một hàm xử lý sẽ được gọi khi gặp một trong các tùy chọn liên quan. Bộ tùy 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 tùy chọn (xem TRỢ GIÚP TÙY CHỌN bên dưới). Các bộ 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ác tùy chọn liên quan. Điều này đơ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ự (ví dụ: ứng dụng thử nghiệm).

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

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

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 ĐỊNH NGHĨA LỰA CHỌN

Các tùy chọn được xác định bằng cấu trúc OptionDef . Định nghĩa tùy chọn được tổ chức 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, id số nguyên được sử dụng để xác định tùy chọn và liệu tùy chọn có mong muốn / cho phép đối số hay không. Phần cuối của mảng tùy chọn được báo hiệu bằng trường NULL Name. Vd:

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

TÙY CHỌN IDS

Id tùy chọn xác định các tùy chọn đối với mã xử lý chúng (chức năng OptionHandler). Id tùy chọn có liên quan đến OptionSet nơi chúng xuất hiện và do đó có thể được sử dụng lại trên các OptionSets khác nhau (tuy nhiên hãy xem TÙY CHỌN NGẮN HẠN bên dưới). Quy ước chung là bắt đầu đánh số id tùy chọn ở 1000, tuy nhiên bất kỳ số nào> 128 đều có thể được sử dụng. Các tùy chọn bí danh có thể được tạo bằng cách sử dụng cùng một id tùy chọn với các tên tùy 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ự 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 phạm vi ký tự ASCII đồ họa sẽ cho phép ký tự đó được sử dụng như một tùy chọn ngắn.

ParseArgs () yêu cầu các ký tự tùy chọn ngắn là duy nhất trên tất cả các OptionSets. Do đó, việc sử dụng các tùy chọn ngắn không được khuyến khích đối với bất kỳ Bộ tùy chọn nào được chia sẻ trên các chương trình do cơ hội va chạm đáng kể. Các ký tự tùy chọn ngắn có thể được sử dụng lại trong một OptionSet duy nhất để cho phép tạo các tên tùy chọn dài 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 liên quan. Các chuỗi này được sử dụng bởi hàm PrintOptionHelp() để 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ụ cú pháp theo sau bởi mô tả văn bản của tùy chọn. Nếu tùy chọn có phiên bản ngắn hoặc tên bí danh, nó sẽ được đặt trước tên dài chính. Để nhất quán, các dòng cú pháp được thụt lề với 2 khoảng trắng, trong khi các dòng mô tả được thụt vào với 7 khoảng trắng. Một dòng trống duy nhất theo sau mỗi mô tả tùy chọn, bao gồm cả dòng cuối cùng.

Vd:

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

TÙY CHỌN NHÓM TRỢ GIÚP

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