6 个版本
0.2.1 | 2022年7月4日 |
---|---|
0.2.0 | 2022年3月28日 |
0.1.3 | 2022年3月2日 |
0.1.1 | 2022年2月3日 |
0.1.0 | 2022年1月18日 |
#372 in 命令行界面
180KB
3K SLoC
命令行参数
注意:这是英文的 ReadMe,有关德文版本请参阅 LIESMICH.md。
待办事项:英文版本
命令行参数解析器,带有可选的自动帮助生成。
使用提供的关联函数创建参数,结果类型由类型变量指定。可以使用 combine!
宏或专用 combineN
函数将多个参数组合成更复杂的结构。
参数通过其长名称和可能的短名称进行识别。长名称通常在两个减号字符 --long
后给出。短名称通常在单个减号字符 -short
后给出。短名称预期只由一个 Grapheme 组成。
所有字符串都可以进行调整,例如帮助消息中参数的描述。如果相关,提供德语和英语版本的专业化函数。此外,德语和英语同义词也可用。使用 Language
类型可以避免字符串重复。
参数可以具有默认值,如果未使用其任何名称,则使用该默认值。如果没有默认值,则必须使用该参数,否则会导致解析错误。
标志
没有值的参数称为标志,它们可以是激活的或非激活的。在大多数情况下,它们代表 bool
参数,但也支持其他类型。
具有长名称 flag
、长前缀 --
、短名称 f
、短前缀 -
、反转前缀 no
和反转前缀 -
的标志可以通过 --flag
或 -f
激活,并通过 --no-flag
禁用。
如果存在多个具有短名称 f
、g
和 h
的标志,则可以使用 -fgh
一起激活。
早期退出
一种特殊的标志参数,用于引起早期退出。它们不能被禁用,并且会与相关消息一起引起早期退出。典型用途包括显示当前版本或帮助文本。
值
参数可以指定值。当使用长名称指定时,值可以在空格或=
字符之后给出。使用短名称时,可以直接在名称之后指定它。值从OsString
解析。
在生成的帮助文本中可以显示所有允许的值。
具有长名称value
、长前缀--
、短名称v
、短前缀-
和数值类型中值前缀=
的值参数解析结果为每个以下输入的3
--value3
--value=3
-v3
-v=3
-v3
“derive”特性
可以使用derive
特性自动生成接受的命令行参数。它允许为具有命名字段的struct
推导出Parse
特质的实现。
参数的长名称是字段名称,帮助文本中的描述是字段的文档字符串。
参数根据ParseArgument
特质进行解析。存在为bool
、String
、数字类型(i8
、u8
、i16
、u16
、...、f32
、f64
)、Option<T>
和EnumArgument
特质实例的实例。bool
字段产生默认关闭的标志参数;每种其他(提供的)类型都产生值参数;Option<T>
具有默认值None
,所有其他类型都产生必需的参数。可以为不包含数据的enum
类型推导出EnumArgument
特质的实现。用作ParseArgument
的类型必须是Display
的实例。
可以使用#[kommandozeilen_argumente(<Optionen>)]
属性更改默认行为。
在struct
声明中支持以下选项。
sprache: <sprache>
|language: <language>
:一些字符串的默认值,默认:english
。内建语言为deutsch
、englisch
和english
。version
:创建一个--version
、-v
标志。hilfe
|help
:创建一个帮助文本标志。hilfe(<opts>)
,help(<opts>)
,version(<opts>)
:与不带 ops 的变体相似,但默认情况下短名称不正确。可能的选项lang_präfix: <präfix>
|long_prefix: <prefix>
:在长名称之前的前缀。lang: <name>
,long [<namen>]
:覆盖长名称。kurz_präfix: <präfix>
|short_prefix: <prefix>
:在短名称之前的前缀。kurz
:将短名称设置为第一个长名称的第一个图形字符。kurz: <name>
,kurz: [<namen>]
:覆盖短名称。sprache: <sprache>
|language: <language>
:帮助文本和默认名称的语言。beschreibung: <programm-beschreibung>
|description: <program_description>
:仅支持hilfe(<opts>)
和help(<opts>)
。设置在帮助文本中显示的程序描述。
case: sensitive
,case: insensitive
:所有字符串(名称、前缀、中缀)解析为大小写敏感或不敏感,默认:case: sensitive
。case(<opts>)
:关于大小写敏感性的具体控制。所有选项具有以下形式<name>: <value>
,<value>
必须是sensitive
或insensitive
之一。允许的名称lang_präfix
|long_prefix
lang
|long
kurz_präfix
|short_prefix
kurz
|short
invertiere_präfix
|invert_prefix
invertiere_infix
|invert_infix
wert_infix
|value_infix
lang_präfix: <präfix>
|long_prefix: <prefix>
:在长名称前重写前缀的默认值,默认:--
。kurz_präfix: <präfix>
|short_prefix: <prefix>
:在短名称前重写前缀的默认值,默认:-
。invertiere_präfix: <string>
|invert_prefix: <string>
:重写用于反转标志的前缀的默认值,默认:kein
或no
。invertiere_infix: <string>
|invert_infix: <string>
:重写用于在前缀后反转标志的中缀的默认值,默认-
。wert_infix: <string>
|value_infix: <string>
:重写用于在相同参数中给出值的默认值,默认=
。meta_var: <string>
|meta_var: <string>
:重写帮助文本中显示的元变量的默认值,默认:WERT
或VALUE
。
字段支持以下选项
glätten
/flatten
:使用Parse
特性(包含配置的参数)。FromStr
:使用FromStr
特性(需要值为和错误类型的Display
实例)。benötigt
/required
:不使用配置的默认值。lang_präfix: <präfix>
|long_prefix: <prefix>
:在长名称之前的前缀。lang: <name>
|long: <name>
:重写长名称。lang: [<namen>]
|long: [<names>]
:设置多个长名称(逗号分隔列表)。kurz_präfix: <präfix>
|short_prefix: <prefix>
:在短名称之前的前缀。kurz
/short
:将短名称设置为第一个长名称的第一个字符。kurz: <wert>"
/short: <value>"
:覆盖短名称。kurz: [<namen>]
|short: [<names>]
:设置多个短名称(以逗号分隔的列表)。standard: <wert>
|default: <value>
:覆盖默认值。invertiere_präfix: <string>
|invert_prefix: <string>
:覆盖前缀以反转标志。invertiere_infix: <string>
|invert_infix: <string>
:覆盖前缀后的中缀以反转标志。wert_infix: <string>
|value_infix: <string>
:覆盖中缀以给出相同的参数中的值。meta_var: <string>
:覆盖帮助文本中使用的元变量。
示例
一个简单的示例,包含3个标志和2个值,使用函数API和derive API创建的struct
,可在GitHub仓库中找到。两种情况都产生以下帮助文本
kommandozeilen_argumente 0.2.0
program description.
derive_en.exe [OPTIONS]
OPTIONS:
--[no]-flag A flag with default settings. [Default: false]
--[no]-(other|names) | -u A flag with alternative names. [Default: false]
--[kein]-required | -r A flag without default value, with alternative prefix to invert the flag.
--value(=| )VALUE A String value.
--enumeration(=| )VAR | -e[=| ]VAR An Enumeration-value with default value and alternative meta variable. [Possible values: One, Two, Three | Default: Two]
--version | -v Show the current version.
--help | -h Show this text.
缺少(计划中)的功能
- 子命令
- 基于位置的参数
- 没有值的名称的不同默认值和名称不显示
- 参数组(这些N个标志中只能有一个是激活的)
依赖关系
~2MB
~64K SLoC