PSCompletions (psc)

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

• GitHub: https://github.com/abgox/PSCompletions/blob/main/README-CN.md
• Gitee: https://gitee.com/abgox/PSCompletions/blob/main/README-CN.md

介绍

TIP

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

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

TIP

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

新的变化

• 请查阅 更新日志

常见问题

• 请查阅 常见问题

安装

WARNING

• PowerShell(pwsh): 除非你确定始终会使用管理员权限，否则不要添加 -Scope AllUsers
• Windows PowerShell: 除非你确定始终会使用管理员权限，否则不要省略 -Scope CurrentUser

1. 打开 PowerShell

2. 安装模块:

   • 普通安装

     Install-Module PSCompletions

   • 静默安装:

     Install-Module PSCompletions -Repository PSGallery -Force

   • 使用 Scoop 安装

     scoop bucket add abgox-bucket https://github.com/abgox/abgox-bucket

     scoop install abgox-bucket/PSCompletions

3. 导入模块:

   Import-Module PSCompletions

   • 如果不想每次启动 PowerShell 都需要导入 PSCompletions 模块，你可以使用以下命令将导入语句写入 $PROFILE 中

     echo "Import-Module PSCompletions" >> $PROFILE

   • 推荐将 Import-Module PSCompletions 添加到 $PROFILE 中靠前的位置，避免出现 编码问题
   • 关于补全触发按键

卸载

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

   Uninstall-Module PSCompletions

使用

TIP

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

• 以 git 补全为例

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

Demo

贡献

• 请查阅 CONTRIBUTING

Tips

关于补全触发按键

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

WARNING

• 如果需要指定 Set-PSReadLineKeyHandler -Key <key> -Function <MenuComplete|Complete>

• 请放在 Import-Module PSCompletions 之前

• 例如:

  Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete
  
  Import-Module PSCompletions

关于补全更新

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

关于选项类补全

• 选项类补全，指的是像 -* 的命令补全，例如 git config --global 中的 --global
• 你应该优先使用选项类补全
• 以 git 补全为例，如果你想要输入 git config user.name --global xxx
• 你应该先补全 --global，然后再补全 user.name，最后输入名称 xxx
• 对于以 = 结尾的选项，如果有相关补全定义，则可以直接按下 Tab 键触发补全

关于补全菜单

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

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

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

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

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

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

  1. 选用当前选中的补全项: Enter(回车) / Space(空格)

     • 当只有一个补全项时，也可以使用 Tab

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

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

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

  4. 选择补全项:

     选择上一项	选择下一项
     Up	Down
     Left	Right
     Shift + Tab	Tab
     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 对于补全有两种实现

  • Set-PSReadLineKeyHandler

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

  • Register-ArgumentCompleter

    • 可以通过配置 psc menu config enable_menu_enhance 0 来使用它
    • PSCompletions 只对通过 psc add 添加的补全生效
    • 其他补全由 Set-PSReadLineKeyHandler -Key <key> -Function <MenuComplete|Complete> 控制

关于特殊符号

TIP

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

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

  • 只有通过 psc add 添加的补全中才存在

  • 你可以将它们替换成空字符串来隐藏它们

    • psc menu symbol SpaceTab ""
    • psc menu symbol OptionTab ""
    • psc menu symbol WriteSpaceTab ""

• »,?,! : 如果出现多个, 表示符合多个条件, 可以选择其中一个效果

  • 定义:

    • Normal Completions: 子命令，例如在 git 中的 add/pull/push/commit/...
    • Optional Completions: 可选参数，例如在 git add 中的 -g/-u/...
    • General Optional Completions: 可以用在任何地方的通用可选参数，例如在 git 中的 --help/...
    • Current Completions: 当前的补全项列表

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

    • 可通过 psc menu symbol SpaceTab <symbol> 自定义此符号

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

    • 可通过 psc menu symbol OptionTab <symbol> 自定义此符号

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

    • 如果字符串有空格, 请使用 "(引号) 或 '(单引号) 包裹，如 "test content"
    • 如果同时还有 », 表示有预设的补全项, 你可以不输入字符串, 直接按下 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 键来获取路径补全

Stars

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

赞赏支持

补全列表

• Github: https://github.com/abgox/PSCompletions/blob/main/README-CN.md#补全列表
• Gitee: https://gitee.com/abgox/PSCompletions/blob/main/README-CN.md#补全列表