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_prefixlang|longkurz_präfix|short_prefixkurz|shortinvertiere_präfix|invert_prefixinvertiere_infix|invert_infixwert_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