nl::ArgParser

Her bir seçeneği ve seçenek olmayan bağımsız değişkeni işlemek için işleme işlevlerini çağırarak komut satırı stili bağımsız değişkenleri ayrıştırın.

ParseArgs(), bir bağımsız değişkenler listesi (argv) alır ve bunları sağlanan seçenek tanımlarına göre ayrıştırır. İşlev, hem uzun (opt) hem de kısa (-o) seçeneklerini destekler ve GNU getopt_long(3) işleviyle aynı seçenek söz dizimini uygular.

Seçenek tanımları, ParseArgs()'ya bir OptionSet yapısı dizisi (optSets) olarak iletilir. Her OptionSet, bir seçenek tanımları dizisi ve bir işleyici işlevi içerir. ParseArgs(), seçenek bağımsız değişkenlerini verilen sırada işler ve tanınan her seçenek için ilgili işleyici işlevini çağırır. Tüm seçenekler ayrıştırıldıktan sonra, kalan bağımsız değişkenleri işlemek için bir kez seçenek olmayan ayrı bir işleyici işlevi (nonOptArgHandler) çağrılır.

SEÇENEK GRUPLARI

OptionSet, ilişkili seçeneklerden biriyle karşılaşıldığında çağrılacak işleyici işlevine işaret eden bir işaretçiyle birlikte bir dizi seçenek tanımı içerir. Seçenek grupları, her bir seçeneğin söz dizimini ve amacını açıklayan yardım metni de içerir (aşağıdaki SEÇENEK YARDIMI'na bakın). Seçenek grupları, ilgili seçeneklerden oluşan tekrar kullanılabilir koleksiyonların oluşturulmasına olanak tanıyacak şekilde tasarlanmıştır. Bu sayede, benzer seçenekleri (ör. test uygulamaları) kabul eden birden çok uygulamayı kullanmaya devam etmek için gereken çaba basitleştirilir.

OptionSetsone tanımlamak için kullanılan iki kalıp vardır.Örneğin, OptionSet yapılandırmasının bir örneğini başlatabilirsiniz (ör. veya bir alt sınıf OptionSetBase olarak ayarlayıp bir oluşturucu sağlayın. İkincisi ise seçenek işleme yetkisini alt sınıfa vermek için yalnızca sanal bir HandleOption() işlevi kullanır.

OptionSet listeleri, NULL ile sonlandırılmış bir işaretçi dizisi olarak ParseArgs() işlevine iletilir. 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))
    {
        ...
    }
}

SEÇENEK TANIMLARI

Seçenekler, OptionDef yapısı kullanılarak tanımlanır. Seçenek tanımları, her bir öğenin şunları içerdiği bir OptionDef dizisi şeklinde düzenlenir: seçeneğin adı, seçeneği tanımlamak için kullanılan tam sayı kimliği ve seçeneğin bir bağımsız değişken bekleyip beklemeyeceği/izin verip vermemesi. Seçenek dizisinin sonuna bir NULL Adı alanı işaret eder. 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 }
};

SEÇENEK KİMLİĞİ

Option kimlikleri, bunları işleyen koddaki seçenekleri tanımlar (OptionHandler işlevi). Seçenek kimlikleri, göründükleri OptionSet ile ilişkilidir ve bu nedenle farklı OptionSet'lerde yeniden kullanılabilir (ancak aşağıdaki KISA SEÇENEKLER bölümüne bakın). Genel kural, seçenek kimliklerini 1000 olarak numaralandırmaya başlamaktır ancak herhangi bir sayı > 128 kullanılabilir. Takma ad seçenekleri, farklı seçenek adlarıyla aynı seçenek kimliği kullanılarak oluşturulabilir.

KISA SEÇENEKLER

getopt_long(3) değerinden farklı olarak ParseArgs(), kısa seçenek karakterlerinin listesini belirten ayrı bir dize almaz. Bunun yerine, kimlik değeri grafik ASCII karakter aralığında olan herhangi bir seçenek, o karakterin kısa bir seçenek olarak kullanılmasına izin verir.

ParseArgs(), kısa seçenek karakterlerinin tüm OptionSet'lerde benzersiz olmasını gerektirir. Bu nedenle, büyük çakışma olasılığı nedeniyle programlar arasında paylaşılan OptionSet'ler için kısa seçeneklerin kullanılması önerilmez. Takma ad uzun seçenek adlarının oluşturulmasına olanak tanımak için kısa seçenek karakterleri tek bir OptionSet içinde yeniden kullanılabilir.

SEÇENEK YARDIM

Her OptionSet, ilgili seçeneklerin amacını ve söz dizimini açıklayan bir OptionHelp dizesi içerir. Bu dizeler, seçenek kullanım bilgilerini oluşturmak için PrintOptionHelp() işlevi tarafından kullanılır.

Kural olarak, seçenek yardım dizeleri bir söz dizimi örneğinin ardından seçeneğin metinsel açıklamasını içerir. Seçeneğin kısa bir sürümü veya takma adı varsa birincil uzun addan önce verilir. Tutarlılık için söz dizimi satırlarına 2 boşluk, açıklama satırlarına ise 7 boşluk girin. Sonuncusu da dahil olmak üzere her seçenek açıklamasının ardından tek bir boş satır gelir.

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

SEÇENEK YARDIM GRUPLARI

OptionSets, yardım çıkışında seçenekleri birlikte gruplandırmak için kullanılan bir HelpGroupName dizesi içerir. PrintOptionHelp() işlevi, oluşturulan kullanım çıktısında bölüm başlığı olarak HelpGroupName değerini kullanır. Birden fazla OptionSet aynı HelpGroupName'e sahipse, PrintOptionHelp() farklı OptionSets için seçenek yardımını ortak bir bölüm başlığı altında birlikte yazdırır.

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
)