分析扩展参数

  • 项目

EngExtCpp 扩展框架提供了帮助分析传递给扩展的命令行参数的方法。 若要利用这些方法，扩展必须首先在EXT_COMMAND宏中声明命令行参数的格式。

若要绕过框架执行的命令行参数分析并让扩展本身分析参数，请将命令行说明设置为 "{{custom}}" 并使用方法 GetRawArgStr 获取用于分析的命令行参数。

打印时，将自动包装命令行说明字符串，以适应显示的列宽。 但是，换行符可以嵌入描述字符串中-使用“”\n来启动新行。

命令行说明可以是 NULL 或空字符串。 如果出现上述任一情况，则表示扩展命令不采用任何参数。

命令行说明

命令行参数的说明是一个序列，其中包含两种类型的组件：指令和参数。 说明可以选择包含每个指令之一，最多可以包含 64 个参数。

指令

指令指定如何分析参数。 它们由双大括号（'{{' 和 '}}'）括起来。 每个指令可以选择在描述参数的字符串中出现零次或一次。

以下指令可用：

custom
关闭扩展框架完成的分析，并允许该扩展执行自己的分析。

l:str
重写命令行参数的默认长说明。 扩展框架将使用 str 来完整描述所有参数。

opt:str
替代命名命令的默认前缀字符。 默认值为 "/-"，允许“”/或“”-用作标识命名参数的前缀。

s:str
替代命令行参数的默认简短说明。 扩展框架将针对所有参数的简短说明使用 str 。

下面是指令的一些示例。 以下字符串由解析其自己的参数的扩展命令使用。 它还提供用于自动 ！help extension 命令的简短和长说明：

{{custom}}{{s:<arg1> <arg2>}}{{l:arg1 - Argument 1\narg2 - Argument 2}}

以下字符串将参数选项前缀字符更改为“”/或“”。- 使用此指令，将使用“”和“”而不是“+arg:arg”和“/arg”指定-arg参数：

{{opt:+:}}

参数

参数可以是两种类型：命名和未命名。 未命名的参数是按位置读取的。 这两种类型的参数也有显示名称，由帮助命令使用。

参数说明由单大括号（'{' 和 '}'）括起来。

每个参数说明具有以下语法：

{[optname];[type[,flags]];[argname];[argdesc]}

其中：

optname
参数的名称。 这是命令和按名称提取参数的方法中使用的名称。 此名称是可选的。 如果存在该参数，则参数将变为“命名参数”;它可以显示在命令行上的任意位置，并按名称引用。 如果该参数不存在，则参数将变为“未命名参数”;它在命令行上的位置很重要，它由相对于其他未命名参数的位置引用。

type
自变量类型。 这会影响分析参数的方式及其检索方式。 类型参数可以具有以下值之一：

b
布尔类型。 该参数存在或不存在。 可以使用 HasArg 检索命名的布尔参数。

e[d][s][bits]
表达式类型。 该参数具有数值。 可以使用 GetArgU64 检索命名表达式参数，并且可以使用 GetUnnamedArgU64 检索未命名的表达式参数。

d
表达式限制为参数字符串中的下一个空格字符。 如果不存在，表达式计算器将使用命令行中的字符，直到它确定它到达表达式的末尾。

s
表达式的值是有符号的。 否则，表达式的值为无符号。

位
参数值中的位数。 位的最大值为 64。

s
字符串类型。 字符串限制为下一个空格字符。 可以使用 GetArgStr 检索命名字符串参数，可以使用 GetUnnamedArgStr 检索未命名的字符串参数。

x
字符串类型。 参数是命令行的其余部分。 使用 GetArgStr 或 GetUnnamedArgStr 检索参数，就像使用 s 字符串类型一样。

flags
参数标志。 这些参数确定分析器将如何处理参数。 标志参数可以具有以下值之一：

d=expr
参数的默认值。 如果命令行中不存在该参数，则参数设置为 expr。 默认值是一个字符串，根据参数的类型进行分析。

ds
默认值不会显示在帮助提供的参数说明中。

o
参数是可选的。 这是命名参数的默认值。

r
参数是必需的。 这是未命名参数的默认值。

argname
参数的显示名称。 这是自动 ！help 扩展命令和自动 /？ 或 -？ 命令行参数使用的名称。 打印命令行选项摘要时使用。

argdesc
参数的说明。 这是由自动 ！help 扩展和自动“/？”或“-？”命令行参数打印的说明。

下面是参数说明的一些示例。 以下表达式定义一个采用单个可选表达式参数的命令。 该参数必须适合 32 位。 如果命令行中不存在该参数，将使用0x100的默认值。

{;e32,o,d=0x100;flags;Flags to control command}

以下表达式定义具有可选的布尔值“/v”参数和必需的未命名字符串参数的命令。

{v;b;;Verbose mode}{;s;name;Name of object}

以下表达式定义一个命令，该命令具有可选的命名表达式参数 /oname expr 和可选的命名字符串参数 /eol str。 如果 存在 /eol ，则其值将设置为命令行的其余部分，并且不会再分析任何参数。

{oname;e;expr;Address of object}{eol;x;str;Commands to use}

命令行

下面是在命令行上分析参数的一些方法的列表：

  • 命名表达式和字符串参数的值遵循命令行上的名称。 例如 ， /name expr 或 /name str。

  • 对于命名的布尔参数，如果名称出现在命令行上，则值为 true;否则为 false。

  • 可以在命令行上将多个单字符命名的布尔选项组合在一起。 例如，可以使用速记表示法“/abc”（除非已有名为“abc”的参数）来编写“/b /c”。

  • 如果命令行包含命名参数“？” - 例如“/？”和“-？” - 参数分析结束，并显示扩展的帮助文本。

分析内部

参数分析器使用多种方法来设置参数。

SetUnnamedArg 方法将更改未命名参数的值。 为方便起见，SetUnnamedArgStr 和 SetUnnamedArgU64 方法将分别设置未命名的字符串和表达式参数。

命名参数存在类似的方法。 SetArg 用于更改任何命名参数的值，SetArgStr 和 SetArgU64 分别用于命名字符串和表达式参数。