✨PSCompletions(psc) ✨

English | 简体中文 | Github | Gitee

介绍

• PowerShell: 跨平台的 PowerShell。命令行中运行 pwsh 启动

• Windows PowerShell: Windows 系统内置的 PowerShell。命令行中运行 powershell 启动

• 一个 PowerShell 补全管理模块，更好、更简单、更方便的使用和管理补全

  Windows PowerShell 也可以使用此模块，但更推荐使用 PowerShell

• 集中管理补全
• en-US,zh-CN,... 多语言切换
• 动态排序补全项(根据使用频次)
• 提供了一个更好用的补全菜单

如果 PSCompletions 对你有所帮助，请在此项目点个 Star ⭐

新的变化

• 请查阅 更新日志

安装

1. 打开 PowerShell

2. 安装模块:

   • 除非你确定始终会使用管理员权限打开 PowerShell，否则不要省略 -Scope CurrentUser

   Install-Module PSCompletions -Scope CurrentUser
   • 静默安装:

   Install-Module PSCompletions -Scope CurrentUser -Repository PSGallery -Force

3. 导入模块:

   Import-Module PSCompletions
   • 如果不想每次启动 PowerShell 都需要导入 PSCompletions 模块，你可以将导入语句写入 $PROFILE 中

   echo "Import-Module PSCompletions" >> $PROFILE

卸载

1. 打开 PowerShell
2. 卸载模块:

   Uninstall-Module PSCompletions

使用

可用补全列表

如果补全列表里没有你想要的补全，你可以 提交 issues

• 以 git 补全为例

1. psc add git
2. 然后你就可以输入 git, 按下 Space(空格键) Tab 键来获得命令补全
3. 关于 psc 的更多命令用法，你只需要输入 psc 然后按下 Space(空格键) Tab 键触发补全，通过 补全提示信息 来了解

Demo

贡献

• 请查阅 CONTRIBUTING

Tips

关于补全触发按键

• 模块默认使用 Tab 键作为补全触发按键
• 你可以使用 psc menu config trigger_key <key> 去设置它

关于补全更新

• 当打开 PowerShell 并导入 PSCompletions 模块后，PSCompletions 会开启一个后台作业去检查远程仓库中补全的状态
• 获取到更新后，会在下一次打开 PowerShell 并导入 PSCompletions 后显示补全更新提示

关于补全菜单

• 除了语言内置的补全菜单，PSCompletions 模块还提供了一个更好用的补全菜单。

  • 配置: psc menu config enable_menu 1 (默认开启)

• 模块提供的补全菜单基于 PS-GuiCompletion 的实现思路，感谢 PS-GuiCompletion !

• 模块提供的补全菜单可用的 Windows 环境：

  • PowerShell
  • Windows PowerShell
    • 由于 Windows PowerShell 渲染问题，补全菜单的边框样式无法自定义
    • 如果需要自定义，请使用 PowerShell

• 模块提供的补全菜单中的按键

  1. 选用当前选中的补全项: Enter(回车键)

     • 当只有一个补全项时，也可以使用 Tab 或 Space(空格) 键

  2. 删除过滤字符: Backspace(退格键)

  3. 退出补全菜单: ESC / Ctrl + c

     • 当过滤区域没有字符时，也可以使用 Backspace(退格键) 退出补全菜单

  4. 选择补全项:

     选择上一项	选择下一项
     Up	Down
     Left	Right
     Shift + Tab	Tab
     Shift + Space	Space
     Ctrl + u	Ctrl + d
     Ctrl + p	Ctrl + n

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

  • 对于配置的值，1 表示 true，0 表示 false (这适用于 PSCompletions 的所有配置)

关于菜单增强

• 配置: psc menu config enable_menu_enhance 1 默认开启

• 现在，PSCompletions 对于补全有两种实现

  1. Register-ArgumentCompleter

     • 及之前版本都使用此实现
     • : 此实现变为可选
       • 你可以运行 psc menu config enable_menu_enhance 0 来继续使用它
       • 但并不推荐，它只能用于 psc add 添加的补全

  2. Set-PSReadLineKeyHandler

     • : 默认使用此实现
       • 需要 enable_menu 和 enable_menu_enhance 同时为 1
     • 它不再需要循环为所有补全命令注册 Register-ArgumentCompleter，理论上加载速度会更快
     • 同时使用 TabExpansion2 全局管理补全，不局限于 psc add 添加的补全
       • 例如:
         • cd/.\/..\/~\/... 这样的路径补全
         • Get-*/Set-*/New-*/... 这样的内置命令补全
         • 由 cli 或模块注册的补全
         • ...

关于特殊符号

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

  • 如果你不需要也不想看到这些符号, 可以将它们替换成空字符串以隐藏它们
    • psc menu symbol SpaceTab ""
    • psc menu symbol OptionTab ""
    • psc menu symbol WriteSpaceTab ""

• 😄🤔😎 : 如果出现多个, 表示符合多个条件, 可以选择其中一个效果

  • 定义:

    • Normal Completion: 子命令，例如在 git 中的 add/pull/push/commit/...
    • Optional Completion: 可选参数，例如在 git add 中的 -g/-u/...
    • General Optional Completion: 可以用在任何地方的通用可选参数，例如在 git 中的 --help/...

  • 😄 : 表示选用当前选中的补全后, 可以按下 Space(空格键) 和 Tab 键继续获取 Normal Completion 或者 Optional Completion

    • 仅在有 Normal Completion 或 Optional Completion 时才会显示此符号
    • 可通过 psc menu symbol SpaceTab <symbol> 自定义此符号

  • 🤔 : 表示选用当前选中的补全(Optional Completion)后, 你可以按下 Space(空格键) 和 Tab 键继续获取其他的 Optional Completion

    • General Optional Completion 也使用此符号
    • 可通过 psc menu symbol OptionTab <symbol> 自定义此符号

  • 😎 : 表示选用当前选中的补全(Optional Completion 或者 General Optional Completion)后, 你可以按下 Space(空格键), 再输入一个字符串, 然后按下 Space(空格键) 和 Tab 键继续获取其他的 Optional Completion 或者 General Optional Completion

    • 如果字符串有空格, 请使用 "(引号) 或 '(单引号) 包裹，如 "test content"
    • 如果同时还有 😄, 表示有几个预设的字符串(Normal Completion)可以补全, 你可以不输入字符串, 直接按下 Space(空格键) 和 Tab 键继续获取它们
    • 可通过 psc menu symbol WriteSpaceTab <symbol> 自定义此符号

  • 所有补全都可以在输入部分字符后按下 Tab 键触发补全

关于补全提示信息

• 补全提示信息只是辅助, 你也可以使用 psc menu config enable_tip 0 来禁用补全提示信息

  • 启用补全提示信息: psc menu config enable_tip 1
  • 也可以禁用特定补全的提示信息，如 psc
    • psc completion psc enable_tip 0

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

  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)

关于语言

• 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)

关于路径补全

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

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

• 比如:

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

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

补全列表

• 说明
  • Completion ：可添加的补全。点击跳转命令官方网站，按照数字字母排序(0-9,a-z)。
    • 特殊情况: abc(a)，这表示你需要通过 psc add abc 去下载它，但默认使用 a 而不是 abc 去触发补全
  • Language: 支持的语言，以及翻译进度
    • 翻译进度是相较于 en-US 的
  • Description: 命令描述