nl::ArgParser

কমান্ড লাইন-স্টাইল আর্গুমেন্টের সেট পার্স করুন, প্রতিটি বিকল্প এবং বিকল্প নয় এমন আর্গুমেন্ট প্রসেস করার জন্য হ্যান্ডলিং ফাংশন কল করুন।

ParseArgs() আর্গুমেন্টের (argv) একটি তালিকা নেয় এবং প্রদত্ত বিকল্পের সংজ্ঞার সেট অনুযায়ী সেগুলি পার্স করে। ফাংশনটি দীর্ঘ (opt) এবং সংক্ষিপ্ত (-o) উভয় বিকল্পকেই সমর্থন করে এবং GNU getopt_long(3) ফাংশনের মতো একই বিকল্প সিনট্যাক্স প্রয়োগ করে।

বিকল্পের সংজ্ঞা ParseArgs()-এ OptionSet স্ট্রাকচারের (optSets) অ্যারে হিসেবে পাস করা হয়। প্রতিটি OptionSet-এ বিকল্পের সংজ্ঞা ও হ্যান্ডলার ফাংশনের অ্যারে থাকে। ParseArgs() প্রদত্ত ক্রমে বিকল্প আর্গুমেন্ট প্রসেস করে, প্রতিটি স্বীকৃত বিকল্পের জন্য সংশ্লিষ্ট হ্যান্ডলার ফাংশনকে কল করে। সব বিকল্প পার্স করা হয়ে গেলে, বাকি থাকা আর্গুমেন্ট প্রসেস করার জন্য একটি আলাদা নন-অপশন হ্যান্ডলার ফাংশন (nonOptArgHandler) একবার কল করা হয়।

বিকল্পের সেট

OptionSet-এ বিকল্পের সংজ্ঞার সেট থাকে এবং এর সাথে হ্যান্ডলার ফাংশনের পয়েন্টার থাকে যা সংশ্লিষ্ট বিকল্পের মধ্যে কোনও একটির সম্মুখীন হলে কল করা হবে। এছাড়াও, বিকল্প সেটে প্রতিটি বিকল্পের সিনট্যাক্স ও উদ্দেশ্য বর্ণনা করে এমন সহায়তা টেক্সট থাকে (নিচে বিকল্প সংক্রান্ত সহায়তা দেখুন)। সম্পর্কিত বিকল্পের আবার ব্যবহারযোগ্য সংগ্রহ তৈরি করার জন্য বিকল্প সেট ডিজাইন করা হয়েছে। এটি একই ধরনের বিকল্প (যেমন, টেস্ট অ্যাপ্লিকেশন) গ্রহণ করে এমন একাধিক অ্যাপ্লিকেশন বজায় রাখার জন্য প্রয়োজনীয় পরিশ্রমকে সহজ করে তোলে।

OptionSet সংজ্ঞায়িত করার জন্য দুটি প্যাটার্ন আছে, কেউ OptionSet স্ট্রাক্টের ইনস্ট্যান্স নিজেই শুরু করতে পারেন, যেমন স্ট্যাটিক গ্লোবাল হিসেবে অথবা OptionSetBase সাবক্লাস হিসেবে এবং কনস্ট্রাক্টর প্রদান করতে পারেন। পরেরটি সাবক্লাসে বিকল্প হ্যান্ডলিং ডেলিগেট করার জন্য একটি পিওর ভার্চুয়াল HandleOption() ফাংশন ব্যবহার করে।

OptionSets-এর তালিকা ParseArgs() ফাংশনে NULL-টার্মিনেটেড পয়েন্টার অ্যারে হিসেবে পাস করা হয়। 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 এলিমেন্টের অ্যারে হিসেবে সাজানো থাকে, যেখানে প্রতিটি এলিমেন্টে থাকে: বিকল্পের নাম, বিকল্প শনাক্ত করার জন্য ব্যবহৃত একটি পূর্ণসংখ্যা আইডি এবং বিকল্পটি কোনও আর্গুমেন্ট আশা করে/অনুমতি দেয় কিনা। বিকল্প অ্যারের শেষটি একটি NULL নামের ফিল্ড দ্বারা চিহ্নিত করা হয়। 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 }
};

বিকল্পের আইডি

বিকল্প আইডি, বিকল্পগুলিকে সেই কোডে শনাক্ত করে যা তাদের পরিচালনা করে (OptionHandler ফাংশন)। বিকল্প আইডিগুলি যে OptionSet-এ দেখা যায় তার সাথে সম্পর্কিত এবং তাই বিভিন্ন OptionSet জুড়ে আবার ব্যবহার করা যেতে পারে (তবে নিচে সংক্ষিপ্ত বিকল্পগুলি দেখুন)। সাধারণত বিকল্পের আইডি ১০০০ থেকে শুরু হয়, তবে ১২৮-এর বেশি যেকোনও সংখ্যা ব্যবহার করা যেতে পারে। একই বিকল্প আইডি সহ বিভিন্ন বিকল্পের নাম ব্যবহার করে উপনাম বিকল্প তৈরি করা যেতে পারে।

SHORT বিকল্প

getopt_long(3)-এর মতো, ParseArgs() ছোট বিকল্প অক্ষরের তালিকা উল্লেখ করে আলাদা স্ট্রিং নেয় না। বরং, এমন যেকোনও বিকল্প যার আইডি ভ্যালু গ্রাফিক্যাল ASCII অক্ষরের রেঞ্জের মধ্যে পড়ে, সেটি ওই অক্ষরকে শর্ট বিকল্প হিসেবে ব্যবহার করার অনুমতি দেবে।

ParseArgs()-এর জন্য সব OptionSets জুড়ে সংক্ষিপ্ত বিকল্প অক্ষর অনন্য হতে হবে। এই কারণে, প্রোগ্রাম জুড়ে শেয়ার করা যেকোনও OptionSets-এর জন্য সংক্ষিপ্ত বিকল্পের ব্যবহারকে নিরুৎসাহিত করা হয় কারণ এতে সংঘর্ষের সম্ভাবনা অনেক বেশি থাকে। বিকল্পের সংক্ষিপ্ত নামগুলি একটি OptionSet-এর মধ্যে আবার ব্যবহার করা যেতে পারে যাতে বিকল্পের দীর্ঘ নামগুলি তৈরি করা যায়।

বিকল্প সংক্রান্ত সহায়তা

প্রতিটি OptionSet-এ একটি OptionHelp স্ট্রিং থাকে যা সংশ্লিষ্ট বিকল্পের উদ্দেশ্য এবং সিনট্যাক্স বর্ণনা করে। এই স্ট্রিংগুলি PrintOptionHelp() ফাংশন দ্বারা বিকল্প ব্যবহারের তথ্য তৈরি করতে ব্যবহৃত হয়।

প্রথাগতভাবে, বিকল্পের সহায়তা স্ট্রিংয়ে সিনট্যাক্সের উদাহরণ থাকে এবং তারপরে বিকল্পের টেক্সট বিবরণ থাকে। বিকল্পের কোনও সংক্ষিপ্ত ভার্সন বা উপনাম থাকলে, সেটি প্রাথমিক দীর্ঘ নামের আগে দেওয়া হয়। সামঞ্জস্য বজায় রাখার জন্য, সিনট্যাক্স লাইনে ২টি স্পেস এবং বিবরণের লাইনে ৭টি স্পেস দিয়ে ইন্ডেন্ট করা হয়। শেষেরটি সহ প্রতিটি বিকল্পের বিবরণের পরে একটি খালি লাইন থাকে।

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 ব্যবহার করে। একাধিক OptionSets-এর একই HelpGroupName থাকলে, PrintOptionHelp() একটি সাধারণ বিভাগের শিরোনামের অধীনে বিভিন্ন OptionSets-এর জন্য একসাথে বিকল্প সহায়তা প্রিন্ট করবে।

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
)