diff --git a/README-CN.md b/README-CN.md index 122fa00..b272163 100644 --- a/README-CN.md +++ b/README-CN.md @@ -10,6 +10,9 @@

+ + module version + license @@ -28,17 +31,18 @@ ## 介绍 -- `PowerShell`: 跨平台的 PowerShell。命令行中运行 `pwsh` 启动 +- [`PowerShell`](https://github.com/PowerShell/PowerShell): 跨平台的 PowerShell。命令行中运行 `pwsh` 启动 -- `Windows PowerShell`: Windows 系统内置的 PowerShell。命令行中运行 `powershell` 启动 +- [`Windows PowerShell`](https://learn.microsoft.com/powershell/scripting/what-is-windows-powershell): Windows 系统内置的 PowerShell。命令行中运行 `powershell` 启动 --- - 一个 `PowerShell` 补全管理模块，更好、更简单、更方便的使用和管理补全 - > `Windows PowerShell` 也可以使用此模块，但不建议 + > `Windows PowerShell` 也可以使用此模块，但更推荐使用 `PowerShell` - [集中管理补全](#补全列表 "点击查看可添加补全列表！") - `en-US`,`zh-CN`,... 多语言切换 - 动态排序补全候选(根据使用频次) +- [提供了一个更好用的补全菜单](#关于补全菜单) **如果 PSCompletions 对你有所帮助，请在右上角点个 Star ⭐** @@ -46,8 +50,10 @@ 1. 打开 `PowerShell` 2. `Install-Module PSCompletions -Scope CurrentUser` + > - 除非你确定始终会使用管理员权限打开 `PowerShell`，否则不要省略 `-Scope CurrentUser` 3. `Import-Module PSCompletions` - - 如果不想每次启动 `PowerShell` 都导入一次，就执行 `echo "Import-Module PSCompletions" >> $PROFILE` + - 如果不想每次启动 `PowerShell` 都需要导入 `PSCompletions` 模块，你可以将导入语句写入 `$PROFILE` 中 + - `echo "Import-Module PSCompletions" >> $PROFILE` ## 卸载 @@ -61,8 +67,8 @@ - 如果补全列表里没有你想要的补全，你可以 [提交 issues](https://github.com/abgox/PSCompletions/issues "点击提交 issues") 1. `psc add git` -2. 然后你就可以输入 `git`,按下 `Space`(空格键) `Tab` 键来获得命令补全 -3. 关于 `psc` 的更多命令，你可以输入 `psc` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过命令提示信息来了解 +2. 然后你就可以输入 `git`, 按下 `Space`(空格键) `Tab` 键来获得命令补全 +3. 关于 `psc` 的更多命令用法，你只需要输入 `psc` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过[补全提示信息](#关于补全提示信息)来了解 ## Demo @@ -77,16 +83,20 @@ ### 关于补全更新 -- 当打开 `PowerShell` 并导入 `PSCompletions` 后，`PSCompletions` 会开启一个后台作业去检查远程仓库中补全的状态 +- 当打开 `PowerShell` 并导入 `PSCompletions` 模块后，`PSCompletions` 会开启一个后台作业去检查远程仓库中补全的状态 - 获取到更新后，会在下一次打开 `PowerShell` 并导入 `PSCompletions` 后显示补全更新提示 ### 关于补全菜单 +- 除了语言内置的补全菜单，`PSCompletions` 模块还提供了一个好用的补全菜单。 - 模块提供的补全菜单基于 [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) 的实现思路，感谢 [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) ! -- 模块提供的补全菜单只能在 Windows 系统下使用 PowerShell(pwsh) 运行, 其他环境只能使用 PowerShell 自带的补全菜单 +- 模块提供的补全菜单可用的 Windows 环境： + - `PowerShell` v4.0.0+ support + - `Windows PowerShell` v4.1.0+ support + - 由于 `Windows PowerShell` 渲染问题，补全菜单的边框样式无法自定义 - 模块提供的补全菜单中的按键 - 1. 应用选中的补全项: `Enter`(回车键) + 1. 选用当前选中的补全项: `Enter`(回车键) 2. 删除过滤字符: `Backspace`(退格键) 3. 退出补全菜单: `ESC` / `Ctrl + c` - 当过滤区域没有字符时，也可以使用 `Backspace`(退格键) 退出补全菜单 @@ -101,31 +111,69 @@ | `Ctrl + u` | `Ctrl + d` | | `Ctrl + p` | `Ctrl + n` | -- 补全菜单的所有配置, 你可以输入 `psc menu` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过命令提示信息来了解 +- 补全菜单的所有配置, 你可以输入 `psc menu` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过[补全提示信息](#关于补全提示信息)来了解 - 对于配置的值，`1` 表示 `true`，`0` 表示 `false` (这适用于 `PSCompletions` 的所有配置) ### 关于特殊符号 -- 😄🤔😎 : 如果出现多个, 表示符合多个条件, 可以选择其中一个的效果 +- 补全项后面的特殊符号用于在按下 `Tab` 键之前提前感知是否有可用的补全候选项 + + - 如果你不需要也不想看到这些符号, 可以将它们替换成空字符串以隐藏它们 + - `psc menu symbol SpaceTab ""` + - `psc menu symbol OptionTab ""` + - `psc menu symbol WriteSpaceTab ""` + +- 😄🤔😎 : 如果出现多个, 表示符合多个条件, 可以选择其中一个效果 - 😄 : 表示选用当前选中的补全后, 可以按下 `Space`(空格键) 和 `Tab` 键继续获取补全(普通补全或选项类补全) - 可通过 `psc menu symbol SpaceTab ` 自定义此符号 - - 如: `psc menu symbol SpaceTab ""` 设置为空字符串 - 🤔 : 表示选用当前选中的选项类补全后, 你可以按下 `Space`(空格键) 和 `Tab` 键继续获取剩余选项类补全(如 --verbose) + - 通用选项类补全共用此符号，它可以在任何位置触发，不会影响它们 - 可通过 `psc menu symbol OptionTab ` 自定义此符号 - 😎 : 表示选用当前选中的选项类补全后, 你可以按下 `Space`(空格键), 再输入一个字符串, 然后按下 `Space`(空格键) 和 `Tab` 键继续获取剩余选项类补全 - - 如果字符串有空格, 请使用 "" 或 '' 包裹，如 "test content" + - 如果字符串有空格, 请使用 `"`(引号) 或 `'`(单引号) 包裹，如 "test content" - 如果同时还有 😄, 表示有几个预设的字符串可以补全, 你可以不输入字符串, 直接按下 `Space`(空格键) 和 `Tab` 键继续获取补全 - 可通过 `psc menu symbol WriteSpaceTab ` 自定义此符号 - - 如果存在通用选项类补全, 也可以触发通用选项的补全 - - 所有补全都可以在输入部分后按下 `Tab` 键触发补全 - - 如果你不需要也不想看到这些符号, 可以将它们替换成空字符串。如: `psc menu symbol SpaceTab ""` + - 所有补全都可以在输入部分字符后按下 `Tab` 键触发补全 + - 在 `Windows PowerShell` 中，输入 `-` 或 `--` 后按下 `Tab`键是无法获取补全的 + - 你应该先按下 `Tab` 键触发补全菜单，然后输入 `-` 或 `--` 进行筛选 + - 这个问题在 `PowerShell` 中不存在 - 使用 PowerShell 语言自带的补全菜单时, 如果 `...` 是最后一个补全, 则表示可显示区域过小, 无法显示所有候选项 - 使用模块提供的补全菜单时, 如果补全提示信息末尾出现 `...`, 则表示当前显示区域宽度不够, 提示信息显示不完整 +### 关于补全提示信息 + +- 补全提示信息只是辅助, 你也可以使用 `psc menu config menu_show_tip 0` 来禁用补全提示信息 + + - 启用补全提示信息: `psc menu config menu_show_tip 1` + - 也可以禁用特定补全的提示信息，如 `psc` + - `psc completion psc menu_show_tip 0` + +- 补全提示信息一般由三部分组成: 用法(Usage) + 描述(Description) + 举例(Example) + ```txt + U: install|add [-g|-u] [options] + 这里是命令的描述说明 + 在 U: 和 E: 之间的内容都是命令描述 + E: install xxx + add -g xxx + ``` +- 示例解析: + + 1. 用法: 以 `U:` 开头(Usage) + + - 命令名称: `install` + - 命令别名: `add` + - 必填参数: `` + - `app` 是对必填参数的简要概括 + - 可选参数: `-g` `-u` + - `[options]` 表示泛指一些选项类参数 + + 2. 描述: 在 `U:` 和 `E:` 之间的内容 + 3. 举例: 以 `E:` 开头(Example) + ### 关于语言 - `Global language`: 默认为当前的系统语言 @@ -147,12 +195,13 @@ - 以 `git` 为例，当输入 `git add`，此时按下 `Space` 和 `Tab` 键，不会触发路径补全，只会触发模块提供的命令补全 - 如果你希望触发路径补全，你需要输入内容 -- 只要输入的内容符合这个正则 `^\.*[\\/].*`，都会去获取路径补全，这是 PowerShell 的补全，与模块无关 +- 只要输入的内容符合这个正则 `^\.*[\\/]*`，都会触发 `PowerShell` 的路径补全 - 比如: - 输入 `./` 或 `.\` 后按下 `Tab` 以获取 **子目录** 或 **文件** 的路径补全 - 输入 `../` 或 `..\` 后按下 `Tab` 以获取 **父级目录** 或 **文件** 的路径补全 - 输入 `/` 或 `\` 后按下 `Tab` 以获取 **同级目录** 的路径补全 + - 更多的: `.` / `~/` / `../../` ... - 因此，你应该输入 `git add ./` 这样的命令再按下 `Tab` 键来获取路径补全 diff --git a/README.md b/README.md index cc5c554..962908a 100644 --- a/README.md +++ b/README.md @@ -3,13 +3,16 @@

- English | 简体中文 | + English | Github | Gitee

+ + module version + license @@ -28,17 +31,18 @@ ## Introduce -- `PowerShell`: A Cross-platform PowerShell. Start it in command line by running `pwsh`. +- [`PowerShell`](https://github.com/PowerShell/PowerShell): A Cross-platform PowerShell. Start it in command line by running `pwsh`. -- `Windows PowerShell`: A PowerShell which is built-in on Windows systems. Start it in command line by running `powershell`. +- [`Windows PowerShell`](https://learn.microsoft.com/powershell/scripting/what-is-windows-powershell): A PowerShell which is built-in on Windows systems. Start it in command line by running `powershell`. --- - A completion manager in `PowerShell` for better and simpler use completions. - > It can also be used in `Windows PowerShell`.(Not Recommend) + > It can also be used in `Windows PowerShell`, but it's a better choice to use `PowerShell`. - [Manage completions together.](#available-completions-list "Click it to view the completion list that can be added !") - Switch between languages(`en-US`,`zh-CN`,...) freely. - Sort completion tab dynamically by frequency of use. +- [It provides a useful completion menu.](#about-completion-menu) **If this project is helpful to you, please consider giving it a star ⭐.** @@ -46,9 +50,10 @@ 1. Start `PowerShell` 2. `Install-Module PSCompletions -Scope CurrentUser` + > - Don't omit `-Scope CurrentUser` unless you're sure you'll always open `PowerShell` with administrator permissions. 3. `Import-Module PSCompletions` + - If you don't want to import the `PSCompletions` module every time you start `PowerShell`, you can write it to `$PROFILE`. - `echo "Import-Module PSCompletions" >> $PROFILE` - - So you don't have to import the module every time you open PowerShell. ## How to uninstall @@ -62,8 +67,8 @@ - If it doesn't include the completion you want, you can [submit an issue](https://github.com/abgox/PSCompletions/issues "Click to submit an issue"). 1. `psc add git` -2. Then you can enter `git` and press `Space` `Tab` to get command completion. -3. For more commands on `psc`, you can learn by entering `psc` and then pressing `Space` `Tab`. +2. Then you can enter `git`, press `Space` and `Tab` key to get command completion. +3. For more usages on `psc`, you just need to enter `psc`, press `Space` and `Tab` key, and you will get all usages of `psc` by reading [the completion tip](#about-completion-tip). ## Demo @@ -73,18 +78,24 @@ ### About the completion trigger key -- The module uses the `Tab` key by default. +- `PSCompletions` uses the `Tab` key by default. - You can set it by running `Set-PSReadLineKeyHandler MenuComplete`. ### About completion update -- When the module is imported after opening `PowerShell`, `PSCompletions` will start a background job to check for the completion status of the remote repository. +- When `PSCompletions` module is imported after starting `PowerShell`, it will start a background job to check for the completion status of the remote repository. - After getting the update, `PSCompletions` will show the latest status of the completions in the next time. ### About completion menu +- In addition to the language's built-in completion menu, `PSCompletions` module also provides a useful completion menu. + - The module's completion menu provided by the module is based on [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) realization idea, thanks! -- It can only be used in PowerShell(pwsh) under Windows. + +- Available Windows environment: + - `PowerShell` v4.0.0+ support + - `Windows PowerShell` v4.1.0+ support + - Due to rendering problems of `Windows PowerShell`, the border style of the completion menu cannot be customized. - Some keys in the completion menu provided by the module. 1. Apply the selected completion item: `Enter` @@ -102,24 +113,60 @@ | `Ctrl + u` | `Ctrl + d` | | `Ctrl + p` | `Ctrl + n` | -- All configurations of it, you can trigger completion by running `psc menu`, then learn about them by completion tip. +- 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 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. + + - If you don't need or want to see these symbols, you can hide them by replacing them with the empty string. + - `psc menu symbol SpaceTab ""` + - `psc menu symbol OptionTab ""` + - `psc menu symbol WriteSpaceTab ""` + - 😄🤔😎 : If there are multiple, you can choose the effect of one of them. - 😄 : It means that after you apply it, you can press `Space` and `Tab` key to continue to get command completions.(Normal or optional completions) - It can be customized by running `psc menu symbol SpaceTab ` - 🤔 : It means that after you apply it (option completion), you can press `Space` and `Tab` key to continue to get option completions. (e.g. `--verbose`) + - Generic optional completions shares this symbol, but it does not affect them. - It can be customized by running `psc menu symbol OptionTab ` - 😎 : It means that after you apply it (option completion), you can press `Space` and enter a string, then press `Space` and `Tab` key to continue to get the rest of option completions. - - If the string has Spaces, Please use "" or '' to wrap it. e.g. 'test content' + - If the string has Spaces, Please use `"`(quote) or `'`(single quote) to wrap it. e.g. "test content" - 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 ` - - Completion of generic options can also be triggered if there is one or more generic option completion. - - All complements can be triggered by pressing the `Tab` key after entering a part. - - If you don't need or want to see these symbols, you can hide them by replacing them with the empty string. - - e.g. `psc menu symbol SpaceTab ""` + - 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 + +- The completion tip is only a helper, you can also disable the tip by running `psc menu config menu_show_tip 0` + + - To enable the completion tip, run `psc menu config menu_show_tip 1`. + - You can also disable the tip for a specific completion, such as `psc`. + - `psc completion psc menu_show_tip 0` + +- General structure of the completion tip: `Usage` + `Description` + `Example` + + ```txt + U: install|add [-g|-u] [options] + This is a description of the command. + E: install xxx + add -g xxx + ``` + +- Example Analysis: + 1. Usage: Begin with `U:` + - command name: `install` + - command alias: `add` + - required parameters: `` + - `app` is a simple summary of the parameters. + - optional parameters: `-g` `-u` + - `[options]`: Some options. + 2. Description: The description of the command. + 3. Example: Begin with `E:` ### About language @@ -144,11 +191,12 @@ - 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 get the path completion, which is PowerShell completion. +- If the content matches this regex rule `^\.*[\\/]*`, it will trigger `PowerShell` path completion. - 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: `.` / `~/` / `../../` ... - So you can enter `git add ./` and then press `Tab` key to get the path completion. ## Available Completions List