PSCompletions

zh-CN - 简体中文

en-US - English

zh-CN - 简体中文

en-US - English

主题

PSCompletions (psc) ​

本页内容来自于项目 README，内容更新可能延后，请以项目 README 为准！

介绍 ​

socialify

喜欢这个项目？请给它 Star ⭐️ 或 赞赏 💰

TIP

  • PowerShell(pwsh): 跨平台的 PowerShell (Core)，运行 pwsh/pwsh.exe 启动
  • Windows PowerShell: Windows 系统内置的 PowerShell (Desktop)，运行 powershell/powershell.exe 启动
  • 它们都可以使用 PSCompletions，但是更推荐 PowerShell(pwsh)

一个补全管理器，为 PowerShell 带来更出色、更简便的 Tab 补全体验。

演示 ​

TIP

demo

新的变化 ​

请查阅 更新日志

常见问题 ​

请查阅 常见问题

贡献 ​

请查阅 贡献指南

安装 ​

  1. 安装模块

  2. 导入模块

    powershell
    Import-Module PSCompletions

TIP

  • 如果使用了 . $Profile，请运行 psc 以重载模块的按键绑定及数据
  • 参考: Source profile

使用 ​

  • 使用 内置的补全库，以 git 补全为例

    1. 使用 psc add git 添加补全
    2. 输入 git，按下 Space(空格键) 和 Tab 键获取命令补全

  • 使用官方补全或其他的补全库

    • 如果存在官方补全，可以使用类似的命令

      powershell
      xxx completion powershell | Out-String | Invoke-Expression

    • 使用其他的补全库: argc-completions, Carapace

    • 更多详情，参考 菜单增强

  • 使用 PSFzf 作为补全菜单，参考 与 PSFzf 结合使用

Tips ​

关于补全菜单 ​

  • 除了 PowerShell 内置的补全菜单，PSCompletions 模块还提供了一个更强大的补全菜单。

    • 配置: psc menu config enable_menu 1 (默认开启)
    • 相关的按键绑定可运行 psc 查看

  • 它只在 Windows 中可用，因为在 Linux/MacOS 中 PowerShell 没有实现相关底层方法

  • 补全菜单的所有配置，你可以输入 psc menu 然后按下 Space(空格键) 和 Tab 键触发补全，通过 补全提示信息 来了解

    • 对于配置的值，1 表示 true，0 表示 false (这适用于 PSCompletions 的所有配置)
    • 常见的菜单行为:
      • 只有一个补全项时自动应用: psc menu config enable_enter_when_single 1
      • ...

关于菜单增强 ​

  • 配置: psc menu config enable_menu_enhance 1 (默认开启)
  • PSCompletions 对于补全有两种实现

    • Set-PSReadLineKeyHandler

      • 默认使用此实现
        • 前提: 配置项 enable_menu 和 enable_menu_enhance 同时为 1
        • 它使用 Set-PSReadLineKeyHandler -Key <Key> -ScriptBlock { ... }
          • <Key> 是 psc menu config trigger_key 的值 (默认: Tab)
        • 因此，你不能再使用 Set-PSReadLineKeyHandler -Key Tab -ScriptBlock { ... }
      • 它使用 TabExpansion2 全局管理补全，不局限于 psc add 添加的补全
        • 路径补全: cd/.\/..\/~\/...
        • 内置命令补全: Get-*/Set-*/New-*/...
        • 通过 Register-ArgumentCompleter 注册的补全
        • 由 cli 或模块注册的补全
        • ...

    • Register-ArgumentCompleter

      • 可以通过运行 psc menu config enable_menu_enhance 0 来使用它
      • 则模块的补全菜单只对通过 psc add 添加的补全生效

关于选项类补全 ​

  • 选项类补全，指的是像 -* 的命令补全，例如 git config --global 中的 --global
  • 你应该优先使用选项类补全
  • 以 git 补全为例，如果你想要输入 git config user.name --global xxx
  • 你应该先补全 --global，然后再补全 user.name，最后输入名称 xxx

关于路径补全 ​

  • 以 git 为例，当输入 git add，此时按下 Space(空格键) 和 Tab 键，不会触发路径补全，只会触发模块提供的命令补全

  • 如果你希望触发路径补全，你需要输入内容，且内容符合正则 ^(?:\.\.?|~)?(?:[/\\]).*

  • 比如:

    • 输入 ./ 或 .\ 后按下 Tab 以获取 子目录 或 文件 的路径补全
    • 输入 ../ 或 ..\ 后按下 Tab 以获取 父级目录 或 文件 的路径补全
    • 输入 / 或 \ 后按下 Tab 以获取 同级目录 的路径补全
    • 更多的: ~/, ../../, ...

  • 因此，你应该输入 git add ./ 这样的命令再按下 Tab 键来获取路径补全

关于特殊符号 ​

TIP

  • 补全项后面的特殊符号用于在按下 Tab 键之前提前感知是否有可用的补全项

    • 它们仅存在于 psc add 添加的补全中
    • 你可以使用 psc menu symbol <type> <symbol> 来自定义
    • 例如，你可以替换成空字符串来隐藏它们
      • psc menu symbol SpaceTab ""
      • psc menu symbol OptionTab ""
      • psc menu symbol WriteSpaceTab ""

  • ~,?,! : 如果出现多个，表示符合多个条件

    • ~ : 表示选用当前选中的补全后，可以按下 Tab 键继续获取补全
    • ? : 表示选用当前选中的 选项类补全 后，可以按下 Tab 键继续获取当前的补全项列表
    • ! : 表示选用当前选中的 选项类补全 后，你应该输入一个字符串，然后按下 Tab 键继续获取当前的补全项列表
      • 如果字符串有空格，请使用 " 或 ' 包裹，如 "test content"
      • 如果同时还有 ~，表示有预设的补全项，你可以不输入字符串，直接按下 Tab 键继续获取它们

关于补全提示信息 ​

  • 补全提示信息只是辅助，可按需使用

    • 禁用所有补全的提示信息: psc menu config enable_tip 0
    • 禁用特定补全的提示信息: psc completion git enable_tip 0

  • 补全提示信息一般由三部分组成: 用法(Usage) + 描述(Description) + 举例(Example)

    txt
    U: install, add [-g, -u] [options] <app>
这里是命令的描述说明
(在 U: 和 E: 之间的内容都是命令描述)
E: install xxx
   add -g xxx

  • 示例解析:

    1. 用法: 以 U: 开头(Usage)

      • 命令名称: install
      • 命令别名: add
      • 必填参数: <app>
        • app 是对必填参数的简要概括
      • 可选参数: -g -u
      • [options] 表示泛指一些选项类参数

    2. 描述: 在 U: 和 E: 之间的内容

    3. 举例: 以 E: 开头(Example)

关于语言 ​

TIP

  • Global language: 默认为当前的系统语言
    • psc config language 可以查看全局的语言配置
    • psc config language zh-CN 可以更改全局的语言配置
  • Completion language: 为指定的补全设置的语言
    • 例如: psc completion git language en-US
  • Available language: 每一个补全的 config.json 文件中有一个 language 属性，它的值是一个可用的语言列表
  1. 如果有 Completion language，优先使用它，没有则使用 Global language
  2. 判断第一步确定的值是否存在于 Available language 中
    • 如果存在，则使用它
    • 如果不存在，直接使用 Available language 中的第一种语言: en-US

致谢 ​

  • PSReadLine: PowerShell 的一个内置模块，增强命令行编辑体验
    • PSCompletions 使用了 Set-PSReadLineKeyHandler 和 Get-PSReadLineOption
  • PS-GuiCompletion: 适用于 PowerShell 的 GUI 风格的制表符补全菜单

补全列表 ​