nl::ArgParser

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

ParseArgs(), bir bağımsız değişkenler listesi (argv) alır ve bunları sağlanan seçenek tanımları grubuna 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()'ye bir OptionSet yapısı (optSets) dizisi olarak aktarılır. 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 başka bir seçenek olmayan işleyici işlevi (nonOptArgHandler) çağrılır.

SEÇENEK GÜCÜLER

OptionSet, ilişkilendirilmiş seçeneklerden biriyle karşılaşıldığında çağrılacak bir işleyici işlevinin işaretçisiyle birlikte bir dizi seçenek tanımı içerir. Seçenek kümeleri, her seçeneğin söz dizimini ve amacını açıklayan yardım metni de içerir (aşağıdaki SEÇENEK YARDIM'ına bakın). Seçenek kümeleri, ilgili seçeneklerin yeniden kullanılabilir koleksiyonlarının oluşturulmasına olanak tanıyacak şekilde tasarlanmıştır. Bu sayede, benzer seçenekleri (ör. test uygulamaları) kabul eden birden fazla uygulamanın bakımı için gereken çabayı basitleştirir.

OptionSetsone'u tanımlamak için iki kalıp vardır: OptionSet struct'ın kendisinin bir örneğini statik global olarak veya OptionSetBase alt sınıfı olarak başlatarak kurucu sağlayabilir. İkincisi, seçenek işleme yetkisini alt sınıfa vermek için tamamen sanal bir HandleOption() işlevi kullanır.

OptionSet listeleri, NULL ile sonlandırılmış bir işaretçi dizisi olarak ParseArgs() işlevine aktarılır. 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ı, OptionDef öğelerinden oluşan bir dizi olarak düzenlenir. Bu öğelerde her öğe, 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şkeni bekleyip beklemediğine/izin verip vermediğine ilişkin bilgileri içerir. Seçenek dizisinin sonu, NULL Name alanı ile işaretleniyor. 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İKLERİ

Seçenek kimlikleri, bunları işleyen koda yönelik seçenekleri tanımlar (OptionHandler işlevi). Seçenek kimlikleri, içinde göründükleri OptionSet'e bağlıdır ve bu nedenle farklı OptionSet'lerde yeniden kullanılabilir (ancak aşağıdaki KISA SEÇENEKLER bölümüne bakın). Numaralandırmaya seçenek kimliklerinin 1000'den başlanması genel kuraldır. Ancak 128'den büyük herhangi bir sayı da kullanılabilir. Takma ad seçenekleri, aynı seçenek kimliği ve farklı seçenek adları kullanılarak oluşturulabilir.

KISA SEÇENEKLER

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

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

SEÇENEK YARDIMI

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

Kural olarak, seçenek yardım dizeleri seçeneğin metin biçiminde bir açıklamasının ardından söz dizimi örneğinden oluşur. Seçeneğin kısa 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ı ise 7 boşlukla girintilendirilir. 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

OptionSet'ler, yardım çıktısında seçenekleri 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 öğesini kullanır. Birden çok OptionSet aynı HelpGroupName değerine sahipse PrintOptionHelp(), farklı OptionSet'lere ilişkin 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
)