нл:: АргПарсер

Проанализируйте набор аргументов в стиле командной строки, вызывая функции обработки для обработки каждого параметра и аргумента, не являющегося параметром.

ParseArgs() принимает список аргументов ( argv ) и анализирует его в соответствии с набором предоставленных определений опций. Функция поддерживает как длинные (opt), так и короткие (-o) параметры и реализует тот же синтаксис параметров, что и функция GNU getopt_long(3).

Определения опций передаются в ParseArgs() как массив структур OptionSet ( optSets ). Каждый OptionSet содержит массив определений опций и функцию-обработчик. ParseArgs() обрабатывает аргументы опций в заданном порядке, вызывая соответствующую функцию-обработчик для каждой распознанной опции. После того, как все параметры проанализированы, отдельная функция-обработчик, не являющаяся параметром ( nonOptArgHandler ), вызывается один раз для обработки любых оставшихся аргументов.

НАБОРЫ ОПЦИЙ

OptionSet содержит набор определений опций вместе с указателем на функцию-обработчик, которая будет вызываться при обнаружении одной из связанных опций. Наборы опций также содержат текст справки, описывающий синтаксис и назначение каждой опции (см. СПРАВКА ПО ОПЦИИ ниже). Наборы опций предназначены для создания повторно используемых коллекций связанных опций. Это упрощает усилия, необходимые для поддержки нескольких приложений, которые принимают одинаковые параметры (например, тестовые приложения).

Существует два шаблона для определения OptionSetsone: он может либо инициализировать экземпляр самой структуры OptionSet , например, как статический глобальный объект, либо подкласс OptionSetBase и предоставить конструктор. Последний использует чисто виртуальную функцию HandleOption() для делегирования обработки опций подклассу.

Списки наборов параметров передаются в функцию ParseArgs() как массив указателей, завершающийся NULL. Например:

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 , где каждый элемент содержит: имя параметра, целочисленный идентификатор, который используется для идентификации параметра, а также сведения о том, ожидает ли параметр/разрешает аргумент. Конец массива опций обозначается полем NULL Name. Например:

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

ИДЕНТИФИКАТОРЫ ОПЦИИ

Идентификаторы опций идентифицируют опции для кода, который их обрабатывает (функция OptionHandler). Идентификаторы опций относятся к набору опций , в котором они появляются, и поэтому могут повторно использоваться в разных наборах опций (однако см. КРАТКИЕ ОПЦИИ ниже). Общепринятым соглашением является нумерация идентификаторов опций с 1000, однако можно использовать любое число > 128. Параметры псевдонима можно создать, используя один и тот же идентификатор параметра с разными именами параметров.

КОРОТКИЕ ВАРИАНТЫ

В отличие от getopt_long(3), ParseArgs() не принимает отдельную строку, определяющую список коротких символов опций. Скорее, любой параметр, значение идентификатора которого попадает в диапазон графических символов ASCII, позволит использовать этот символ в качестве короткого параметра.

ParseArgs() требует, чтобы короткие символы опций были уникальными во всех наборах опций. По этой причине не рекомендуется использовать короткие параметры для любых наборов параметров, которые используются в разных программах, из-за значительной вероятности коллизий. Символы коротких параметров можно повторно использовать в одном наборе параметров , чтобы можно было создавать псевдонимы длинных имен параметров.

ОПЦИЯ ПОМОЩИ

Каждый набор параметров содержит строку 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";

ОПЦИЯ ГРУПП ПОМОЩИ

Наборы параметров содержат строку 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
)