#command-line-arguments #default-value #arguments-parser #exit #flags #parse-error #help

命令行参数

带有可选自动帮助生成的命令行参数解析器

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 命令行界面

MIT 许可证

180KB
3K SLoC

命令行参数

注意:这是英文的 ReadMe,有关德文版本请参阅 LIESMICH.md

待办事项:英文版本

命令行参数解析器,带有可选的自动帮助生成。

使用提供的关联函数创建参数,结果类型由类型变量指定。可以使用 combine! 宏或专用 combineN 函数将多个参数组合成更复杂的结构。

参数通过其长名称和可能的短名称进行识别。长名称通常在两个减号字符 --long 后给出。短名称通常在单个减号字符 -short 后给出。短名称预期只由一个 Grapheme 组成。

所有字符串都可以进行调整,例如帮助消息中参数的描述。如果相关,提供德语和英语版本的专业化函数。此外,德语和英语同义词也可用。使用 Language 类型可以避免字符串重复。

参数可以具有默认值,如果未使用其任何名称,则使用该默认值。如果没有默认值,则必须使用该参数,否则会导致解析错误。

标志

没有值的参数称为标志,它们可以是激活的或非激活的。在大多数情况下,它们代表 bool 参数,但也支持其他类型。

具有长名称 flag、长前缀 --、短名称 f、短前缀 -、反转前缀 no 和反转前缀 - 的标志可以通过 --flag-f 激活,并通过 --no-flag 禁用。

如果存在多个具有短名称 fgh 的标志,则可以使用 -fgh 一起激活。

早期退出

一种特殊的标志参数,用于引起早期退出。它们不能被禁用,并且会与相关消息一起引起早期退出。典型用途包括显示当前版本或帮助文本。

参数可以指定值。当使用长名称指定时,值可以在空格或=字符之后给出。使用短名称时,可以直接在名称之后指定它。值从OsString解析。

在生成的帮助文本中可以显示所有允许的值。

具有长名称value、长前缀--、短名称v、短前缀-和数值类型中值前缀=的值参数解析结果为每个以下输入的3

  • --value3
  • --value=3
  • -v3
  • -v=3
  • -v3

“derive”特性

可以使用derive特性自动生成接受的命令行参数。它允许为具有命名字段的struct推导出Parse特质的实现。

参数的长名称是字段名称,帮助文本中的描述是字段的文档字符串。

参数根据ParseArgument特质进行解析。存在为boolString、数字类型(i8u8i16u16、...、f32f64)、Option<T>EnumArgument特质实例的实例。bool字段产生默认关闭的标志参数;每种其他(提供的)类型都产生值参数;Option<T>具有默认值None,所有其他类型都产生必需的参数。可以为不包含数据的enum类型推导出EnumArgument特质的实现。用作ParseArgument的类型必须是Display的实例。

可以使用#[kommandozeilen_argumente(<Optionen>)]属性更改默认行为。

struct声明中支持以下选项。

  • sprache: <sprache> | language: <language>:一些字符串的默认值,默认:english。内建语言为deutschenglischenglish
  • 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: sensitivecase: insensitive:所有字符串(名称、前缀、中缀)解析为大小写敏感或不敏感,默认:case: sensitive
  • case(<opts>):关于大小写敏感性的具体控制。所有选项具有以下形式 <name>: <value><value> 必须是 sensitiveinsensitive 之一。允许的名称
    • 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>:重写用于反转标志的前缀的默认值,默认:keinno
  • invertiere_infix: <string> | invert_infix: <string>:重写用于在前缀后反转标志的中缀的默认值,默认 -
  • wert_infix: <string> | value_infix: <string>:重写用于在相同参数中给出值的默认值,默认 =
  • meta_var: <string> | meta_var: <string>:重写帮助文本中显示的元变量的默认值,默认:WERTVALUE

字段支持以下选项

  • 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个值,使用函数APIderive 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