nl::ArgParser

명령줄 스타일 인수 집합을 파싱하여 각 옵션과 비옵션 인수를 처리하기 위한 처리 함수를 호출합니다.

ParseArgs()는 인수 목록 (argv)을 가져와서 제공된 옵션 정의에 따라 파싱합니다. 이 함수는 long (opt) 및 short (-o) 옵션을 모두 지원하며 GNU getopt_long(3) 함수와 동일한 옵션 구문을 구현합니다.

옵션 정의는 OptionSet 구조의 배열(optSets)로 ParseArgs()에 전달됩니다. 각 OptionSet에는 옵션 정의의 배열과 핸들러 함수가 포함되어 있습니다. ParseArgs()는 지정된 순서대로 옵션 인수를 처리하여 인식된 각 옵션에 대해 각 핸들러 함수를 호출합니다. 모든 옵션이 파싱되면 별도의 비옵션 핸들러 함수 (nonOptArgHandler)가 한 번 호출되어 나머지 인수를 처리합니다.

옵션 세트

OptionSet에는 옵션 정의 집합과 함께 연결된 옵션 중 하나가 발생할 때 호출될 핸들러 함수에 대한 포인터가 포함됩니다. 또한 옵션 세트에는 각 옵션의 구문과 목적을 설명하는 도움말 텍스트가 포함되어 있습니다 (아래의 옵션 도움말 참조). 옵션 세트는 재사용 가능한 관련 옵션 모음을 만들 수 있도록 설계되었습니다. 이렇게 하면 유사한 옵션을 허용하는 여러 애플리케이션 (예: 테스트 애플리케이션)을 유지관리하는 데 필요한 작업이 간소화됩니다.

OptionSetsone을 정의하기 위한 두 가지 패턴이 있습니다.다음 예는 OptionSet 구조체 자체의 인스턴스를 초기화할 수 있습니다. 정적 전역 변수로 사용하거나 OptionSetBase 서브클래스로 분류하고 생성자를 제공합니다. 후자는 순수 가상 HandleOption() 함수를 사용하여 옵션 처리를 서브클래스에 위임합니다.

OptionSet의 목록은 NULL로 끝나는 포인터 배열로 ParseArgs() 함수에 전달됩니다. 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))
    {
        ...
    }
}

옵션 정의

옵션은 OptionDef 구조를 사용하여 정의됩니다. 옵션 정의는 OptionDef 요소의 배열로 구성되며, 각 요소에는 옵션 이름, 옵션을 식별하는 데 사용되는 정수 ID, 옵션에서 인수를 예상/허용하는지 여부가 포함됩니다. 옵션 배열의 끝은 NULL Name 필드로 신호를 받습니다. 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

옵션 ID는 옵션을 처리하는 코드 (OptionHandler 함수)에 대한 옵션을 식별합니다. 옵션 ID는 옵션이 표시되는 OptionSet를 기준으로 하므로 여러 OptionSet에서 재사용될 수 있습니다 (단, 아래의 단축 옵션 참조). 일반적으로 1000에서 옵션 ID를 번호 매기기 시작하지만 모든 숫자 > 128을 사용할 수 있습니다. 동일한 옵션 ID와 다른 옵션 이름을 사용하여 별칭 옵션을 만들 수 있습니다.

간단한 옵션

getopt_long(3)과 달리 ParseArgs()는 짧은 옵션 문자 목록을 지정하는 별도의 문자열을 사용하지 않습니다. 대신 ID 값이 그래픽 ASCII 문자 범위에 속하는 모든 옵션은 해당 문자를 짧은 옵션으로 사용할 수 있습니다.

ParseArgs()를 사용하려면 짧은 옵션 문자가 모든 OptionSet에서 고유해야 합니다. 따라서 충돌 가능성이 크므로 프로그램 간에 공유되는 모든 OptionSet에는 짧은 옵션을 사용하지 않는 것이 좋습니다. 짧은 옵션 문자는 단일 OptionSet 내에서 다시 사용하여 긴 별칭 옵션 이름을 만들 수 있습니다.

옵션 도움말

각 OptionSet에는 관련 옵션의 용도와 구문을 설명하는 OptionHelp 문자열이 포함되어 있습니다. 이러한 문자열은 PrintOptionHelp() 함수에서 옵션 사용 정보를 생성하는 데 사용됩니다.

규칙에 따라 옵션 도움말 문자열은 옵션에 대한 텍스트 설명이 뒤따르는 구문 예시로 구성됩니다. 옵션에 짧은 버전이나 별칭 이름이 있는 경우 기본 긴 이름 앞에 지정됩니다. 일관성을 위해 구문 행은 공백 2개로 들여쓰기되고 내용 입력란은 7개의 공백으로 들여쓰기됩니다. 마지막 옵션을 포함하여 각 옵션 설명 뒤에 빈 줄 하나가 표시됩니다.

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

옵션 도움말 그룹

OptionSets에는 도움말 출력에서 옵션을 그룹화하는 데 사용되는 HelpGroupName 문자열이 포함됩니다. PrintOptionHelp() 함수는 생성된 사용 출력에서 HelpGroupName을 섹션 제목으로 사용합니다. 여러 OptionSet의 HelpGroupName이 동일한 경우 PrintOptionHelp()는 공통 섹션 제목 아래에 서로 다른 OptionSet의 옵션 도움말을 함께 출력합니다.

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
)