From aac7c46c2961cee7c9b546cf8ac8e3bae0a4dae5 Mon Sep 17 00:00:00 2001 From: abgox Date: Fri, 9 Aug 2024 19:39:24 +0800 Subject: [PATCH] feat(README): update --- README-CN.md | 36 +++++++++++++++++++++++++----------- README.md | 34 ++++++++++++++++++++++++++-------- 2 files changed, 51 insertions(+), 19 deletions(-) diff --git a/README-CN.md b/README-CN.md index b272163..9938399 100644 --- a/README-CN.md +++ b/README-CN.md @@ -72,14 +72,14 @@ ## Demo -![demo](https://abgop.netlify.app/pscompletions/demo.gif) +![demo](https://wsrv.nl/?url=oh-my-pic.netlify.app/PSCompletions-demo.gif&output=gif&n=-1&default=oh-my-pic.netlify.app/PSCompletions-demo.gif) ## Tips ### 关于补全触发按键 - 模块默认使用 `Tab` 键作为补全触发按键 -- 你可以使用 `Set-PSReadLineKeyHandler MenuComplete` 去设置它 +- 你可以使用 `psc menu config menu_trigger_key ` 去设置它 ### 关于补全更新 @@ -89,6 +89,7 @@ ### 关于补全菜单 - 除了语言内置的补全菜单，`PSCompletions` 模块还提供了一个好用的补全菜单。 + - 配置: `psc menu config menu_enable 1` (默认开启) - 模块提供的补全菜单基于 [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) 的实现思路，感谢 [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) ! - 模块提供的补全菜单可用的 Windows 环境： - `PowerShell` v4.0.0+ support @@ -97,6 +98,7 @@ - 模块提供的补全菜单中的按键 1. 选用当前选中的补全项: `Enter`(回车键) + - 当只有一个可选项时，也可以使用 `Tab` 或 `Space` 键 2. 删除过滤字符: `Backspace`(退格键) 3. 退出补全菜单: `ESC` / `Ctrl + c` - 当过滤区域没有字符时，也可以使用 `Backspace`(退格键) 退出补全菜单 @@ -114,6 +116,25 @@ - 补全菜单的所有配置, 你可以输入 `psc menu` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过[补全提示信息](#关于补全提示信息)来了解 - 对于配置的值，`1` 表示 `true`，`0` 表示 `false` (这适用于 `PSCompletions` 的所有配置) +#### 关于菜单增强 + +- v4.2.0+ support + +- 配置: `psc menu config menu_enhance 1` 默认开启 +- 现在，`PSCompletions` 对于补全有两种实现 + + 1. `Register-ArgumentCompleter` + + - v4.1.0 support 及之前版本都使用此实现 + - v4.2.0+ support 变为可选: 设置 `menu_enhance` 为 `0` + - 此实现只能管理 `psc add` 添加的补全 + + 2. `Set-PSReadLineKeyHandler` + - `v4.2.0` 及之后版本都默认使用此实现 + - 需要 `menu_enable` 和 `menu_enhance` 同时为 `1` + - 它不再需要循环为所有补全命令注册 `Register-ArgumentCompleter`，理论上加载速度会更快 + - 同时使用 [`TabExpansion2`](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/tabexpansion2) 全局管理补全，不局限于 `psc add` 添加的补全 + ### 关于特殊符号 - 补全项后面的特殊符号用于在按下 `Tab` 键之前提前感知是否有可用的补全候选项 @@ -137,12 +158,6 @@ - 可通过 `psc menu symbol WriteSpaceTab ` 自定义此符号 - 所有补全都可以在输入部分字符后按下 `Tab` 键触发补全 - - 在 `Windows PowerShell` 中，输入 `-` 或 `--` 后按下 `Tab`键是无法获取补全的 - - 你应该先按下 `Tab` 键触发补全菜单，然后输入 `-` 或 `--` 进行筛选 - - 这个问题在 `PowerShell` 中不存在 - -- 使用 PowerShell 语言自带的补全菜单时, 如果 `...` 是最后一个补全, 则表示可显示区域过小, 无法显示所有候选项 -- 使用模块提供的补全菜单时, 如果补全提示信息末尾出现 `...`, 则表示当前显示区域宽度不够, 提示信息显示不完整 ### 关于补全提示信息 @@ -194,14 +209,13 @@ ### 关于路径补全 - 以 `git` 为例，当输入 `git add`，此时按下 `Space` 和 `Tab` 键，不会触发路径补全，只会触发模块提供的命令补全 -- 如果你希望触发路径补全，你需要输入内容 -- 只要输入的内容符合这个正则 `^\.*[\\/]*`，都会触发 `PowerShell` 的路径补全 +- 如果你希望触发路径补全，你需要输入内容，且内容符合正则 `^(?:\.\.?|~)?(?:[/\\]).*` - 比如: - 输入 `./` 或 `.\` 后按下 `Tab` 以获取 **子目录** 或 **文件** 的路径补全 - 输入 `../` 或 `..\` 后按下 `Tab` 以获取 **父级目录** 或 **文件** 的路径补全 - 输入 `/` 或 `\` 后按下 `Tab` 以获取 **同级目录** 的路径补全 - - 更多的: `.` / `~/` / `../../` ... + - 更多的: `~/` / `../../` ... - 因此，你应该输入 `git add ./` 这样的命令再按下 `Tab` 键来获取路径补全 diff --git a/README.md b/README.md index 962908a..79374b6 100644 --- a/README.md +++ b/README.md @@ -72,14 +72,14 @@ ## Demo -![demo](https://abgop.netlify.app/pscompletions/demo.gif) +![demo](https://wsrv.nl/?url=oh-my-pic.netlify.app/PSCompletions-demo.gif&output=gif&n=-1&default=oh-my-pic.netlify.app/PSCompletions-demo.gif) ## Tips ### About the completion trigger key - `PSCompletions` uses the `Tab` key by default. -- You can set it by running `Set-PSReadLineKeyHandler MenuComplete`. +- You can set it by running `psc menu config menu_trigger_key `. ### About completion update @@ -116,6 +116,28 @@ - All configurations of it, you can trigger completion by running `psc menu`, then learn about them by [the completion tip](#about-completion-tip). - For configured values, `1` means `true` and `0` means `false`. (It applies to all configurations of `PSCompletions`) +#### About menu enhance + +- v4.2.0+ support + +- config: `psc menu config menu_enhance 1` (Default: `1`) +- Now, `PSCompletions` has two completion implementations + + 1. `Register-ArgumentCompleter` + + - v4.1.0 support : It's used. + - v4.2.0+ support: It's optional. + + - You can use it by running `psc menu config menu_enable 0`. + - It' Not recommended. It only works for completions added by `psc add`. + + 2. `Set-PSReadLineKeyHandler` + - v4.2.0+ support: It's used by default. + - Requires: `menu_enable`and `menu_enhance` both set to `1`. + - It no longer needs to loop through registering `Register-ArgumentCompleter` for all completions, which theoretically makes loading faster. + - It use [`TabExpansion2`](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/tabexpansion2) to manage completions globally, not limited to those added by `psc add`. + - For example, commands such as `Get-*`/`Set-*`/... in `PowerShell` will use the completion menu provided by `PSCompletions` to render the completion. + ### About special symbols - Special symbols after the completion item are used to let you know in advance if completions are available before you press the `Tab` key. @@ -136,9 +158,6 @@ - If there is also 😄, it means that there are some strings to complete, you can press `Space` and `Tab` key to continue to get command completions without entering a string. - It can be customized by running `psc menu symbol WriteSpaceTab ` - All completions can be triggered by pressing the `Tab` key after entering a part. - - In `Windows PowerShell`, if you press the `Tab` key after entering `-` or `--`, you won't get the completions. - - You should press the `Tab` key to trigger the completion menu, and then type `-` or `--` to filter. - - This problem isn't in `PowerShell`. ### About completion tip @@ -190,13 +209,12 @@ ### About path completion - Take `git` for example, when entering `git add`, pressing the `Space` and `Tab` keys, path completion will not be triggered, only completion provided by the module will be triggered. -- If you want to trigger path completion, you need to enter a content. -- If the content matches this regex rule `^\.*[\\/]*`, it will trigger `PowerShell` path completion. +- If you want to trigger path completion, you need to enter a content which matches `^(?:\.\.?|~)?(?:[/\\]).*`. - e.g. - Please enter `./` or `.\` and press `Tab` key to get path completion for the **subdirectory** or **file**. - Please enter `../` or `..\` and press `Tab` key to get path completion for the **parent directory** or **file**. - Please enter `/` or `\` and press `Tab` key to get path completion for the **sibling directory**. - - More examples: `.` / `~/` / `../../` ... + - More examples: `~/` / `../../` ... - So you can enter `git add ./` and then press `Tab` key to get the path completion. ## Available Completions List