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 位无符号整数,并根据 base 参数应用适当的解释。
|
ParseInt(const char *str, uint32_t & output, int base)
|
bool
解析并尝试将字符串转换为 32 位无符号整数,并根据 base 参数应用适当的解释。
|
ParseInt(const char *str, int32_t & output, int base)
|
bool
解析并尝试将字符串转换为 32 位有符号整数,并根据 base 参数应用适当的解释。
|
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 位有符号整数,并根据 base 参数应用适当的解释。
|
ParseInt(const char *str, uint16_t & output)
|
bool
解析并尝试将解释为十进制值的字符串转换为 16 位无符号整数,并根据基本参数应用适当的解释。
|
ParseInt(const char *str, int16_t & output)
|
bool
解析并尝试将解释为十进制值的字符串转换为 16 位有符号整数,并根据 base 参数应用适当的解释。
|
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:: |
用于处理信息选项(help、version)的常用 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()
函数的指针。
gActiveOptionSets
OptionSet ** gActiveOptionSets = NULL
传递给当前活跃的 ParseArgs() 调用的 OptionSet 列表。
如果没有正在进行对 ParseArgs() 的调用,此值将为 NULL。
函数
CountAllOptions
size_t CountAllOptions( OptionSet *optSets[] )
CountAllOptions
size_t CountAllOptions( OptionSet **optSets )
CountOptionSets
size_t CountOptionSets( OptionSet *optSets[] )
CountOptionSets
size_t CountOptionSets( OptionSet **optSets )
DefaultPrintArgError
void DefaultPrintArgError( const char *msg, ... )
输出与参数解析相关的错误消息。
默认函数,用于输出因参数解析而出现的错误消息。
详细信息 | |||
---|---|---|---|
参数 |
|
应用应通过 PrintArgError 函数指针调用,而不是直接调用此函数。
FindOptionById
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
),并根据提供的一组选项定义对其进行解析。该函数支持 long (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 中重复使用(不过,请参阅下面的“简短选项”)。常见惯例是将选项 ID 从 1000 开始编号,但任何大于号的数字可以使用 128。可以使用带有不同选项名称的相同选项 ID 来创建别名选项。
简短选项
与 getopt_long(3) 不同,ParseArgs() 不采用单独的字符串来指定短选项字符列表。相反,ID 值在图形 ASCII 字符范围内的任何选项都允许将该字符用作短选项。
ParseArgs() 要求短选项字符在所有 OptionSet 中都是唯一的。因此,建议不要对跨程序共享的任何 OptionSet 使用短选项,因为极有可能发生冲突。可以在单个 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";
选项帮助论坛
OptionSet 包含一个 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”“n”“0”。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
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 位无符号整数,并根据 base 参数应用适当的解释。
详细信息 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
true;否则,如果失败,则为 false。
|
ParseInt
bool ParseInt( const char *str, uint32_t & output, int base )
解析并尝试将字符串转换为 32 位无符号整数,并根据 base 参数应用适当的解释。
详细信息 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
true;否则,如果失败,则为 false。
|
ParseInt
bool ParseInt( const char *str, int32_t & output, int base )
解析并尝试将字符串转换为 32 位有符号整数,并根据 base 参数应用适当的解释。
详细信息 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
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 位有符号整数,并根据 base 参数应用适当的解释。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
true;否则,如果失败,则为 false。
|
ParseInt
bool ParseInt( const char *str, uint16_t & output )
解析并尝试将解释为十进制值的字符串转换为 16 位无符号整数,并根据基本参数应用适当的解释。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
true;否则,如果失败,则为 false。
|
ParseInt
bool ParseInt( const char *str, int16_t & output )
解析并尝试将解释为十进制值的字符串转换为 16 位有符号整数,并根据 base 参数应用适当的解释。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
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() 函数接受以十六进制格式提供的 64 位节点 ID(带有或不带前导“0x”)或单词“any”。或“all”这表示任何节点 ID (0xFFFFFFFFFFFFFFFF)。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
如果值成功解析,则为“true”;false。
|
ParseSubnetId
bool ParseSubnetId( const char *str, uint16_t & subnetId )
解析并尝试将字符串转换为 16 位无符号子网 ID,从而将该字符串解释为十六进制。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
true;否则,如果失败,则为 false。
|
PrintOptionHelp
void PrintOptionHelp( OptionSet *optSets[], FILE *s )
PutStringWithBlankLine
void PutStringWithBlankLine( FILE *s, const char *str )
PutStringWithNewLine
void PutStringWithNewLine( FILE *s, const char *str )
SplitArgs
int32_t SplitArgs( char *argStr, char **& argList, char *initialArg )