PSCompletions (psc)

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

介绍

TIP

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

一个 PowerShell 补全管理模块，更好、更简单、更方便的使用和管理补全
集中管理补全
en-US,zh-CN,... 多语言切换
动态排序补全项(根据使用频次)
提供了一个更强大的补全菜单
与 argc-completions 结合使用
- argc-completions 仓库

TIP

如果 PSCompletions 对你有所帮助，请为它点个 Star ⭐

新的变化

请查阅更新日志

常见问题

请查阅常见问题

安装

打开 PowerShell
安装模块:
- 除非你确定始终会使用管理员权限打开 PowerShell，否则不要省略 -Scope CurrentUser
powershell
```
Install-Module PSCompletions -Scope CurrentUser
```
- 静默安装:
powershell
```
Install-Module PSCompletions -Scope CurrentUser -Repository PSGallery -Force
```
导入模块:
powershell
```
Import-Module PSCompletions
```
- 如果不想每次启动 PowerShell 都需要导入 PSCompletions 模块，你可以使用以下命令将导入语句写入 $PROFILE 中
powershell
```
echo "Import-Module PSCompletions" >> $PROFILE
```

WARNING

导入 PSCompletions 后，就不要使用 Set-PSReadLineKeyHandler -Key <key> -Function MenuComplete 了
因为 PSCompletions 使用了它，如果再次使用，会覆盖 PSCompletions 中的设置，导致 PSCompletions 补全菜单无法正常工作
你应该通过 PSCompletions 中的配置去设置它
详细配置请参考关于补全触发按键

powershell

Import-Module PSCompletions 

Set-PSReadLineKeyHandler -Key <key> -Function MenuComplete

卸载

打开 PowerShell
卸载模块:
powershell
```
Uninstall-Module PSCompletions
```

使用

TIP

可用补全列表
如果补全列表里没有你想要的补全，你可以提交 issues
也可以与 argc-completions 结合使用

以 git 补全为例

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

Demo

demo

贡献

请查阅 CONTRIBUTING

Tips

关于补全触发按键

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

WARNING

导入 PSCompletions 后，就不要使用 Set-PSReadLineKeyHandler -Key <key> -Function MenuComplete 了
因为 PSCompletions 使用了它，如果再次使用，会覆盖 PSCompletions 中的设置，导致 PSCompletions 补全菜单无法正常工作

powershell

Import-Module PSCompletions 

Set-PSReadLineKeyHandler -Key <key> -Function MenuComplete

关于补全更新

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

关于选项类补全

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

关于补全菜单

除了 PowerShell 内置的补全菜单，PSCompletions 模块还提供了一个更强大的补全菜单。
- 配置: psc menu config enable_menu 1 (默认开启)
模块提供的补全菜单基于 PS-GuiCompletion 的实现思路，感谢 PS-GuiCompletion !
模块提供的补全菜单可用的 Windows 环境：
- PowerShell v4.0.0+
- Windows PowerShell v4.1.0+
  - 由于 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 的所有配置)

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

关于菜单增强 v4.2.0+

配置: psc menu config enable_menu_enhance 1 默认开启
现在，PSCompletions 对于补全有两种实现
1. Register-ArgumentCompleter
  - v4.1.0 及之前版本都使用此实现
  - v4.2.0+: 此实现变为可选
    - 你可以运行 psc menu config enable_menu_enhance 0 来继续使用它
    - 但并不推荐，它只能用于 psc add 添加的补全
2. Set-PSReadLineKeyHandler
  - v4.2.0+: 默认使用此实现
    - 需要 enable_menu 和 enable_menu_enhance 同时为 1
  - 它不再需要循环为所有补全命令注册 Register-ArgumentCompleter，理论上加载速度会更快
  - 同时使用 TabExpansion2 全局管理补全，不局限于 psc add 添加的补全
    - 例如:
      - cd/.\/..\/~\/... 这样的路径补全
      - Get-*/Set-*/New-*/... 这样的内置命令补全
      - 通过 Register-ArgumentCompleter 注册的补全
      - 由 cli 或模块注册的补全
      - 与 argc-completions 结合使用
      - ...

关于特殊符号

TIP

由于未来的 Windows Terminal 的变化，将导致在补全菜单中无法正常显示 😄🤔😎，因此这三个默认特殊符号将改变。
相关的 issue: https://github.com/microsoft/terminal/issues/18242
变化如下:
- 😄 => »
- 🤔 => ?
- 😎 => !

补全项后面的特殊符号用于在按下 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)

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)

关于语言

Global language: 默认为当前的系统语言
- psc config language 可以查看全局的语言配置
- psc config language zh-CN 可以更改全局的语言配置
Completion language: 为指定的补全设置的语言
- 例如: psc completion git language en-US
Available language: 每一个补全的 config.json 文件中有一个 language 属性，它的值是一个可用的语言列表

确定语言

确定指定的语言: 如果有 Completion language，优先使用它，没有则使用 Global language
确定最终使用的语言:
- 判断第一步确定的值是否存在于 Available language 中
- 如果存在，则使用它
- 如果不存在，直接使用 Available language 中的第一种语言(一般为 en-US)

关于路径补全

以 git 为例，当输入 git add，此时按下 Space 和 Tab 键，不会触发路径补全，只会触发模块提供的命令补全
如果你希望触发路径补全，你需要输入内容，且内容符合正则 ^(?:\.\.?|~)?(?:[/\\]).*
比如:
- 输入 ./ 或 .\ 后按下 Tab 以获取 子目录 或文件的路径补全
- 输入 ../ 或 ..\ 后按下 Tab 以获取 父级目录 或文件的路径补全
- 输入 / 或 \ 后按下 Tab 以获取 同级目录 的路径补全
- 更多的: ~/ / ../../ ...
因此，你应该输入 git add ./ 这样的命令再按下 Tab 键来获取路径补全

Stars

如果 PSCompletions 对你有所帮助，请考虑给它一个 Star ⭐

PSCompletions (psc) ​

介绍 ​

新的变化 ​

常见问题 ​

安装 ​

卸载 ​

使用 ​

Demo ​

贡献 ​

Tips ​

关于补全触发按键 ​

关于补全更新 ​

关于选项类补全 ​

关于补全菜单 ​

关于菜单增强 v4.2.0+ ​

关于特殊符号 ​

关于补全提示信息 ​

关于语言 ​

确定语言 ​

关于路径补全 ​

Stars ​

赞赏支持 ​

补全列表 ​

PSCompletions (psc)

介绍

新的变化

常见问题

安装

卸载

使用

Demo

贡献

Tips

关于补全触发按键

关于补全更新

关于选项类补全

关于补全菜单

关于菜单增强 v4.2.0+

关于特殊符号

关于补全提示信息

关于语言

确定语言

关于路径补全

Stars

赞赏支持

补全列表