nl:: ArgParser 语
摘要
枚举 |
|
---|---|
OptionArgumentType
|
枚举 定义命令行选项的参数要求。 |
类型定义符 |
|
---|---|
NonOptionArgHandlerFunct)(const char *progName, int argc, char *argv[])
|
typedefbool(*
可以调用以处理任何剩余的非选项命令行参数的函数。 |
OptionHandlerFunct)(const char *progName, OptionSet *optSet, int id, const char *name, const char *arg)
|
typedefbool(*
一个可以调用以处理一组命令行选项的函数。 |
变量 |
|
---|---|
PrintArgError = DefaultPrintArgError)(const char *msg,...)
|
void(*
指针,用于输出参数解析期间发生的错误。
|
gActiveOptionSets = NULL
|
OptionSet **
传递到当前活跃的 ParseArgs() 调用的 OptionSet 列表。
|
函数 |
|
---|---|
CountAllOptions(OptionSet *optSets[])
|
size_t
|
CountAllOptions(OptionSet **optSets)
|
size_t
|
CountOptionSets(OptionSet *optSets[])
|
size_t
|
CountOptionSets(OptionSet **optSets)
|
size_t
|
DefaultPrintArgError(const char *msg, ...)
|
void
输出与参数解析相关的错误消息。
|
FindOptionById(OptionSet **optSets, int optId, OptionSet *& optSet, OptionDef *& optDef)
|
void
|
FindOptionByIndex(OptionSet **optSets, int optIndex, OptionSet *& optSet, OptionDef *& optDef)
|
void
|
GetNextArg(char *& parsePoint)
|
bool
|
IsShortOptionChar(int ch)
|
bool
|
MakeLongOptions(OptionSet **optSets)
|
struct option *
|
MakeShortOptions(OptionSet **optSets)
|
char *
|
MakeUniqueHelpGroupNamesList(OptionSet *optSets[])
|
const char **
|
ParseArgs(const char *progName, int argc, char *argv[], OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler, bool ignoreUnknown)
|
bool
解析一组命令行样式参数,调用处理函数来处理每个选项和非选项参数。
|
ParseArgs(const char *progName, int argc, char *argv[], OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler)
|
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)
|
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
解析文本格式的 Weave 面料 ID。
|
ParseHexString(const char *hexStr, uint32_t strLen, uint8_t *outBuf, uint32_t outBufSize, uint32_t & outDataLen)
|
bool
解析以十六进制形式提供的字节字符串。
|
ParseIPAddress(const char *str, IPAddress & output)
|
bool
解析文本格式的 IP 地址。
|
ParseInt(const char *str, uint64_t & output, int base)
|
bool
解析并尝试将字符串转换为 64 位无符号整数,并根据基本参数应用适当的解释。
|
ParseInt(const char *str, uint32_t & output, int base)
|
bool
解析并尝试将字符串转换为 32 位无符号整数,并根据基本参数应用适当的解释。
|
ParseInt(const char *str, int32_t & output, int base)
|
bool
解析并尝试将字符串转换为 32 位的带符号整数,并根据基本参数应用适当的解释。
|
ParseInt(const char *str, uint64_t & output)
|
bool
解析并尝试将解释为十进制值的字符串转换为 64 位无符号整数,并根据基本参数应用适当的解释。
|
ParseInt(const char *str, uint32_t & output)
|
bool
解析并尝试将解释为十进制值的字符串转换为 32 位无符号整数,并根据基本参数应用适当的解释。
|
ParseInt(const char *str, int32_t & output)
|
bool
解析并尝试将解释为十进制值的字符串转换为 32 位带符号整数,并根据基本参数应用适当的解释。
|
ParseInt(const char *str, uint16_t & output)
|
bool
解析并尝试将解释为十进制值的字符串转换为 16 位无符号整数,并根据基本参数应用适当的解释。
|
ParseInt(const char *str, int16_t & output)
|
bool
解析并尝试将解释为十进制值的字符串转换为 16 位带符号整数,从而根据基本参数应用适当的解释。
|
ParseInt(const char *str, uint8_t & output)
|
bool
解析并尝试将解释为十进制值的字符串转换为 8 位无符号整数,并根据基本参数应用适当的解释。
|
ParseNodeId(const char *str, uint64_t & nodeId)
|
bool
解析文本格式的 Weave 节点 ID。
|
ParseSubnetId(const char *str, uint16_t & subnetId)
|
bool
解析并尝试将字符串转换为 16 位未签名子网 ID,将字符串解读为十六进制。
|
PrintOptionHelp(OptionSet *optSets[], FILE *s)
|
void
输出数据流选项的指定选项列表的帮助文本。
|
PutStringWithBlankLine(FILE *s, const char *str)
|
void
|
PutStringWithNewLine(FILE *s, const char *str)
|
void
|
SplitArgs(char *argStr, char **& argList, char *initialArg)
|
int32_t
|
类 |
|
---|---|
nl:: |
用于处理信息选项(帮助、版本)的常用 OptionSet。 |
nl:: |
一个 OptionSet,其中处理程序是一个虚拟函数。 |
结构体 |
|
---|---|
nl:: |
定义命令行选项。 |
nl:: |
定义一组逻辑相关和可重复使用的命令行选项。 |
枚举
OptionArgumentType
OptionArgumentType
定义命令行选项的参数要求。
类型定义符
NonOptionArgHandlerFunct
bool(* NonOptionArgHandlerFunct)(const char *progName, int argc, char *argv[])
可以调用以处理任何剩余的非选项命令行参数的函数。
OptionHandlerFunct
bool(* OptionHandlerFunct)(const char *progName, OptionSet *optSet, int id, const char *name, const char *arg)
一个可以调用以处理一组命令行选项的函数。
变量
PrintArgError
void(* PrintArgError)(const char *msg,...) = DefaultPrintArgError
指针,用于输出参数解析期间发生的错误。
应用应调用 PrintArgError() 以报告其选项和非选项参数处理函数中的错误,而不是直接输出到 stdout/stderr。
默认为指向 DefaultPrintArgError()
函数的指针。
gActiveOptionSet
OptionSet ** gActiveOptionSets = NULL
传递到当前活跃的 ParseArgs() 调用的 OptionSet 列表。
如果没有调用 ParseArgs(),此值将为 NULL。
函数
CountAllOptions
size_t CountAllOptions( OptionSet *optSets[] )
CountAllOptions
size_t CountAllOptions( OptionSet **optSets )
CountOption 集
size_t CountOptionSets( OptionSet *optSets[] )
CountOption 集
size_t CountOptionSets( OptionSet **optSets )
DefaultPrintArgError 类中的方法
void DefaultPrintArgError( const char *msg, ... )
输出与参数解析相关的错误消息。
默认函数,用于输出因解析参数而产生的错误消息。
详细信息 | |||
---|---|---|---|
参数 |
|
应用应通过 PrintArgError 函数指针进行调用,而不是直接调用此函数。
查找选项 ID
void FindOptionById( OptionSet **optSets, int optId, OptionSet *& optSet, OptionDef *& optDef )
FindOptionByIndex
void FindOptionByIndex( OptionSet **optSets, int optIndex, OptionSet *& optSet, OptionDef *& optDef )
GetNextArg
bool GetNextArg( char *& parsePoint )
IsShortOptionChar
bool IsShortOptionChar( int ch )
MakeLongOptions
struct option * MakeLongOptions( OptionSet **optSets )
MakeShortOptions
char * MakeShortOptions( OptionSet **optSets )
MakeUniqueHelpGroupNamesList
const char ** MakeUniqueHelpGroupNamesList( OptionSet *optSets[] )
ParseArgs
bool ParseArgs( const char *progName, int argc, char *argv[], OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler, bool ignoreUnknown )
解析一组命令行样式参数,调用处理函数来处理每个选项和非选项参数。
ParseArgs() 接受参数列表 (argv
) 并根据提供的一组选项定义对其进行解析。该函数支持长选项 (opt) 和短选项 (-o),并实现与 GNU getopt_long(3) 函数相同的选项语法。
详细信息 | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||||
返回值 |
如果所有选项和非选项参数都已成功解析,则返回
true ;如果某个选项无法识别或者某个处理程序函数运行失败(即返回 false),则返回 false 。 |
选项定义作为一组 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 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 } };
选项 ID
选项 ID 用于标识处理这些选项的代码的选项(OptionHandler 函数)。选项 ID 是相对于它们在其中出现的 OptionSet 而言的,因此可重复用于不同的 OptionSet(不过,请参阅下面的“短选项”)。常见的惯例是从 1000 开始对选项 ID 进行编号,但 128 以下的任意数字均可使用。可以使用具有不同选项名称的相同选项 ID 来创建别名选项。
简短选项
与 getopt_long(3) 不同,ParseArgs() 不接受用于指定短选项字符列表的单独字符串。ID 值在图形 ASCII 字符范围内的任何选项都将允许将该字符用作简短选项。
ParseArgs() 要求所有选项集的短选项字符都是唯一的。因此,不建议在程序之间共享任何选项集,因为这会发生明显的冲突。短选项字符可以在单个 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";
选项的帮助论坛
选项集包含一个 HelpGroupName
字符串,用于将帮助输出中的选项分组在一起。PrintOptionHelp()
函数在生成的用法输出中会使用 HelpGroupName 作为部分标题。如果多个 OptionSet 具有相同的 HelpGroupName,PrintOptionHelp() 会在通用部分的标题下方输出适用于不同 OptionSet 的选项帮助。
ParseArgs
bool ParseArgs( const char *progName, int argc, char *argv[], OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler )
ParseArgs
bool ParseArgs( const char *progName, int argc, char *argv[], OptionSet *optSets[] )
ParseArgsFromEnvVar
bool ParseArgsFromEnvVar( const char *progName, const char *varName, OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler, bool ignoreUnknown )
从指定的环境变量中解析一组参数。
ParseArgsFromEnvVar() 读取命名的环境变量并将值传递给 ParseArgsFromString()
进行解析。如果未设置环境变量,则该函数将不执行任何操作。
详细信息 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
如果所有选项和非选项参数均成功解析,或者指定的环境变量未设置,则返回
true ;如果任一选项无法识别、某个处理程序函数失败(即返回 false),或发生内部错误,则返回 false 。 |
ParseArgsFromEnvVar
bool ParseArgsFromEnvVar( const char *progName, const char *varName, OptionSet *optSets[] )
ParseArgsFromEnvVar
bool ParseArgsFromEnvVar( const char *progName, const char *varName, OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler )
ParseArgsFromString
bool ParseArgsFromString( const char *progName, const char *argStr, OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler, bool ignoreUnknown )
从给定字符串解析一组参数。
ParseArgsFromString() 将给定字符串 (argStr
) 拆分为一组参数,并使用 ParseArgs() 函数解析参数。
详细信息 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
如果所有选项和非选项参数都已成功解析,则返回
true ;如果某个选项无法识别,某个处理程序函数失败(即返回 false),或者发生内部错误,则返回 false 。 |
输入字符串的语法与 unix shell 命令语法相似,但使用简化的英文引号方案。具体而言:
- 参数由空格分隔,除非空格被加引号或转义。
- 反斜杠转义以下字符,导致其被视为普通字符。反斜杠本身会被删除。
- 以英文单引号或双引号开头/结尾的带英文引号的子字符串。在子字符串中,唯一特殊字符是反斜杠(用于转义下一个字符)以及相应的结束引号。开头/结尾的引号字符已去掉。
例如:
--listen --count 10 --sw-version '1.0 (DEVELOPMENT)' "--hostname=nest.com"
ParseArgsFromString
bool ParseArgsFromString( const char *progName, const char *argStr, OptionSet *optSets[], NonOptionArgHandlerFunct nonOptArgHandler )
ParseArgsFromString
bool ParseArgsFromString( const char *progName, const char *argStr, OptionSet *optSets[] )
ParseBoolean
bool ParseBoolean( const char *str, bool & output )
将字符串解析为布尔值。
此函数接受以下输入值(不区分大小写):"true"、"yes"、"t"、"y"、"1"、"false"、"no"、"f&ott>.
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseFabricId
bool ParseFabricId( const char *str, uint64_t & fabricId, bool allowReserved )
解析文本格式的 Weave 面料 ID。
ParseFabricId() 函数接受十六进制格式的 64 位结构 ID,带前导或 '0x'。
详细信息 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
如果值成功解析,则返回 true;如果值未解析,则返回 false。
|
ParseHexString
bool ParseHexString( const char *hexStr, uint32_t strLen, uint8_t *outBuf, uint32_t outBufSize, uint32_t & outDataLen )
解析以十六进制形式提供的字节字符串。
ParseHexString() 要求输入格式为十六进制数字对(大写或小写)。您可以用以下任意字符分隔十六进制数:冒号、分号、逗号、句点或短划线。此外,输入字符串中任意位置的空格字符都会被忽略。
详细信息 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
如果值成功解析,则返回 true;如果输入数据格式不正确,或者
outBuf 太小,则返回 false。 |
ParseIPAddress
bool ParseIPAddress( const char *str, IPAddress & output )
解析文本格式的 IP 地址。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果值成功解析,则返回 true;如果值未解析,则返回 false。
|
ParseInt
bool ParseInt( const char *str, uint64_t & output, int base )
解析并尝试将字符串转换为 64 位无符号整数,并根据基本参数应用适当的解释。
详细信息 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseInt
bool ParseInt( const char *str, uint32_t & output, int base )
解析并尝试将字符串转换为 32 位无符号整数,并根据基本参数应用适当的解释。
详细信息 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseInt
bool ParseInt( const char *str, int32_t & output, int base )
解析并尝试将字符串转换为 32 位的带符号整数,并根据基本参数应用适当的解释。
详细信息 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseInt
bool ParseInt( const char *str, uint64_t & output )
解析并尝试将解释为十进制值的字符串转换为 64 位无符号整数,并根据基本参数应用适当的解释。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseInt
bool ParseInt( const char *str, uint32_t & output )
解析并尝试将解释为十进制值的字符串转换为 32 位无符号整数,并根据基本参数应用适当的解释。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseInt
bool ParseInt( const char *str, int32_t & output )
解析并尝试将解释为十进制值的字符串转换为 32 位带符号整数,并根据基本参数应用适当的解释。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseInt
bool ParseInt( const char *str, uint16_t & output )
解析并尝试将解释为十进制值的字符串转换为 16 位无符号整数,并根据基本参数应用适当的解释。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseInt
bool ParseInt( const char *str, int16_t & output )
解析并尝试将解释为十进制值的字符串转换为 16 位带符号整数,从而根据基本参数应用适当的解释。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseInt
bool ParseInt( const char *str, uint8_t & output )
解析并尝试将解释为十进制值的字符串转换为 8 位无符号整数,并根据基本参数应用适当的解释。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果成功则为 true;否则为 false。
|
ParseNodeId
bool ParseNodeId( const char *str, uint64_t & nodeId )
解析文本格式的 Weave 节点 ID。
ParseNodeId() 函数接受以十六进制格式(有或不带前导 '0x')或字词 'any' 或 'all' 解读为任何节点 ID (0xFFFFFFFFFFFFFFFF) 的节点 ID。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果值成功解析,则返回 true;如果值未解析,则返回 false。
|
Parse 子网 ID
bool ParseSubnetId( const char *str, uint16_t & subnetId )
解析并尝试将字符串转换为 16 位未签名子网 ID,将字符串解读为十六进制。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果成功则为 true;否则为 false。
|
打印选项帮助
void PrintOptionHelp( OptionSet *optSets[], FILE *s )
输出数据流选项的指定选项列表的帮助文本。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
PutStringWithBlankLine
void PutStringWithBlankLine( FILE *s, const char *str )
PutStringWithNewLine
void PutStringWithNewLine( FILE *s, const char *str )
分离式
int32_t SplitArgs( char *argStr, char **& argList, char *initialArg )