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() 함수에 전달됩니다. 예:

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 이름 필드로 신호를 받습니다. 예:

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에서 재사용될 수 있습니다 (단, 아래의 SHORT OPTIONS 참조). 일반적인 방법은 1, 000에서 번호 지정 옵션 ID를 시작하는 것이지만 모든 숫자 > 128을 사용할 수 있습니다. 다른 옵션 이름과 동일한 옵션 ID를 사용하여 별칭 옵션을 만들 수 있습니다.

Shorts 옵션

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

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

옵션 도움말

각 OptionSet에는 관련 옵션의 목적과 구문을 설명하는 OptionHelp 문자열이 포함됩니다. 이 문자열은 PrintOptionHelp() 함수에서 옵션 사용 정보를 생성하는 데 사용됩니다.

규칙에 따라 옵션 도움말 문자열은 옵션 텍스트 텍스트 뒤에 오는 구문 예시로 구성됩니다. 옵션에 짧은 버전이나 별칭 이름이 있으면 기본 긴 이름보다 먼저 제공됩니다. 일관성을 위해 구문 줄은 공백 2개로 들여쓰기 되지만 설명 줄은 공백 7개로 들여쓰기됩니다. 빈 줄 하나는 마지막 옵션을 포함하여 각 옵션 설명을 따릅니다.

예:

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

옵션 도움말 그룹

OptionSet는 도움말 출력에서 옵션을 그룹화하는 데 사용되는 HelpGroupName 문자열을 포함합니다. PrintOptionHelp() 함수는 생성된 사용 출력에서 HelpGroupName을 섹션 제목으로 사용합니다. 여러 GroupSet의 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
)