gen-completions

[!warning] 此项目正在开发中，因此它非常不稳定且大部分功能不完善。

这是一个解析手册页以生成 shell 完成建议的 crate，既可以解析手册页，也可以从 KDL/JSON 文件中生成。它既有一个库，也有一个二进制文件，如果您想查看库的文档，请参阅 https://docs.rs/gen-completions/。但您可能更关注的是二进制文件，如果您想了解相关信息，请继续阅读。

目前，它生成 Bash、Zsh 和 Nushell 完成建议，尽管我只对 Zsh 和 Nushell 进行了适当的测试。如果您使用的是其他 shell，它还会生成 Carapace 规范。除此之外，它还生成 KDL 和 JSON 文件，这样您就可以处理命令信息，自行生成完成建议或其它内容。

手册页解析主要移植自 Fish 的完成脚本，尽管这个 crate 目前还不支持 Fish 脚本支持的所有类型的手册页。特别是，MacOS 手册页目前还不能解析。对此有任何帮助都将非常受欢迎。

安装

• 使用 Cargo: cargo install gen-completions
• 从 发布页面：简单地下载适用于您的平台的最新的可执行文件
• 作为 Nix flake: github:ysthakur/gen-completions
  • 用 nix shell github:ysthakur/gen-completions 尝试
• 自己构建
  • 下载此仓库 (git clone [email protected]:ysthakur/gen-completions.git)
  • cdgen-completions && cargo构建 --发布

用法

您可以使用 gen-completions 定期生成任何命令的完成建议。

例如，如果您有一个名为 ~/generated-completions 的目录，用于存放所有生成的完成建议，并且您想从 ncdu 的手册页生成 Zsh 完成建议，可以使用：

gen-completions man zsh ~/generated-completions --cmds="ncdu"

如果您有一个配置文件用于生成补全项，您可以使用

gen-completions for zsh ncdu-completions.kdl ~/generated-completions

CLI使用env_logger作为日志后端，因此要配置它，设置环境变量RUST_LOG（链接中有说明）。

以下为具体标志和相关信息。

从手册页生成

Usage: gen-completions man [OPTIONS] <SHELL> <PATH>

Arguments:
  <SHELL>
          Shell(s) to generate completions for

          Possible values:
          - zsh:      Generate completions for Zsh
          - bash:     Generate completions for Bash
          - nu:       Generate completions for Nushell
          - kdl:      Output parsed options as KDL
          - json:     Output parsed options as JSON
          - carapace: Output Carapace spec

  <PATH>
          Directory to output completions to

Options:
  -d, --dirs <PATH,...>
          Directories to search for man pages in, e.g. `--dirs=/usr/share/man/man1,/usr/share/man/man6` Note that `--dirs` will search directly inside the given directories, not inside `<dir>/man1`, `<dir>/man2`, etc. If you want to search for man pages in a specific set of directories, set `$MANPATH` before running this command

  -c, --cmds <REGEX>
          Commands to generate completions for. If omitted, generates completions for all found commands. To match the whole name, use "^...$"

  -C, --exclude-cmds <REGEX>
          Commands to exclude (regex). To match the whole name, use "^...$"

      --not-subcmds <COMMAND-NAME,...>
          Commands that should not be treated as subcommands, to help deal with false positives when detecting subcommands

      --subcmds <man-page=sub cmd,...>
          Explicitly list which man pages are for which subcommands. e.g. `git-commit=git commit,foobar=foo bar`

  -h, --help
          Print help (see a summary with '-h')

从KDL/JSON/YAML生成

Usage: gen-completions for <SHELL> <CONF> [OUT]

Arguments:
  <SHELL>
          Shell(s) to generate completions for

          Possible values:
          - zsh:      Generate completions for Zsh
          - bash:     Generate completions for Bash
          - nu:       Generate completions for Nushell
          - kdl:      Output parsed options as KDL
          - json:     Output parsed options as JSON
          - carapace: Output Carapace spec

  <CONF>
          File to generate completions from

  [OUT]
          File to generate completions to. Outputted to stdout if not given

Options:
  -h, --help
          Print help (see a summary with '-h')

Zsh

您可以将补全项生成到已经存在于$fpath的目录中，其中Zsh查找函数，或者您可以创建一个新目录。如果您选择后者，请确保在您的~/.zshrc中将其添加到$fpath中。

fpath=(path/to/my/directory $fpath)

[!note] fpath必须在调用compinit之前更新。

之后，如果您的选择目录是~/generated-completions，您可以运行

gen-completions man zsh ~/generated-completions --cmds="^ncdu"

然后当您尝试ncdu <TAB>时，您应该看到ncdu所有标志的补全项。

Bash

TODO

Nushell

TODO

贡献

欢迎任何和所有的贡献。有关需要工作的信息，请参阅CONTRIBUTING.md。

工作原理的详细信息

有关生成的文件类型的示例，请查看expected文件夹中的tests文件夹。

有关一些示例手册页，请查看samples文件夹。

它具有非常基本的子命令检测。如果手册页命名为git-commit-tree，它将在文件中查找文本git commit tree、git-commit tree和git commit-tree。当它在手册页中找到文本git commit-tree时，它将假设commit-tree是git的子命令。我不确定Fish脚本如何生成子命令——我太懒了，只是浏览了一下——但最终我会把它移植到Fish的子命令检测。